Anzo.JS Devolpment Guide

Anzo.JS is a full JavaScript implementation of the Anzo API outlined in AnzoClientDesign. This brief guide shows how to quickly deploy a simple Anzo.JS based application into the Open Anzo server.

Setting up the application context

Because Anzo.JS connects directly to the server via Ajax, any HTML and JS files that use Anzo.JS need to be hosted from the Anzo server due to cross-domain restrictions.

To accomplish this, you must setup a servlet context to serve the static resources. In openanzo-3.1.0/configuration/config you'll need to create a properties file that defines the context. For example

org.example.testapp.properties

service.factoryPid=org.openanzo.servlet.StaticResourceFactory
org.openanzo.services.instanceURI=http://example.org/openanzo/test
org.openanzo.servlet.contextPath=/testapp
org.openanzo.servlet.pathSpec=/*
org.openanzo.servlet.docRoot=c:/tmp/docroot
org.openanzo.servlet.authorizationType=NONE

Any requests bound to http://localhost:8080/testapp/ will serve files out of c:/tmp/docroot. Finally, because this is a configuration change, if you have previously started the server, you will need to delete the three openanzo-3.1.0/configuration/org.eclipse.* folders before restarting.

Writing a simple Anzo.JS app

The complete example, index.html, is attached below.

First we need two script tags to setup the Anzo.JS environment. It is critical to setup the djConfig JavaScript object with the path to the Anzo.JS module before bringing in the Dojo toolkit source.

    <script type="text/javascript">
	   var djConfig = {
	       modulePaths: {'anzo': '/openanzo-js/anzo'}
	   };
	</script>
    <script type="text/javascript" src="/openanzo-js/dojo/dojo.js"></script>

Next, inside the main script section we setup the Anzo client.

    // specify what anzo libraries are needed
    dojo.require("anzo.client.AnzoClient");
    dojo.require("anzo.rdf.Statement");

   
    var properties = {
        // location of the comet service, does not typically change
	location            : "/cometd/",  
        // update the login information if necessary
	username            : "sysadmin", // user name for authentication
	password            : "123"       // password for authentication
    }

    var anzoClient = new anzo.client.AnzoClient(properties);

Next, we connect the client, and perform the rest of the sample in the in-line callback.

// connect to the server
anzoClient.connect(function(status, message) {
    
    // check if the connect was successful
    if (status != anzo.messaging.CONNECTION_STATUS_CONNECTED) {
	setStatus("Failed to connect to the server: "+message);
	throw Error("Failed to connect to the server: "+message);
     }
     setStatus("Connected to the server.");
 
     // use the anzo node API to create some URIs and statements.
     var graphUri = anzo.createURI("http://example.org/graph1");
     var predUri = anzo.createURI("http://example.org/pred1"); 
     var stmt1 = anzo.createStatement(graphUri,predUri,"val1",graphUri);
     var stmt2 = anzo.createStatement(graphUri,predUri,"val2",graphUri);
 
     // begin a transaction
     anzoClient.begin();
     // create a new graph.  getReplicaGraph creates a new graph if it doesn't exist
     anzoClient.getReplicaGraph(graphUri, {create: true}, function(graph, error) {
         setStatus("Got replica graph: " + graphUri);
         // add couple statements to the graph
         graph.add(stmt1);
	 graph.add(stmt2);
         // commit the transaction
	 anzoClient.commit();

         // setup a callback for the updateRepository call.
	 var handle = dojo.connect(anzoClient,"updateRepositoryComplete", function(success, errors) {
	     dojo.disconnect(handle);
	     setStatus("Repository udpate complete");

            // check that the statements are in the graph
	     var stmts = graph.getStatements();
	     for (var i=0;i<stmts.length;i++) {
	         setStatus("Statement added: " + stmts[i]);
	     }

             // close the graph and disconnect the client
             graph.close();
	     anzoClient.close(function(status){
	         setStatus("Disconnected from server");
	     });
	 });
	 anzoClient.updateRepository();

    });
});

Copy the attached index.html to c:/tmp/docroot or whatever you set in the properties. Point your browser at

http://localhost:8080/testapp/index.html

and you should see the following output

Status: Done
Connecting to the server.
Connected to the server.
Got replica graph: http://example.org/graph1
Repository udpate complete
Statement added: { http://example.org/graph1, http://example.org/pred1, val1, http://example.org/graph1 }
Statement added: { http://example.org/graph1, http://example.org/pred1, val2, http://example.org/graph1 }
Disconnected from server

Documentation

You can read about the general Anzo API at AnzoClientDesign and for specific Anzo.JS documentation you can also check the documentation comments on the API methods in the source. For example the AnzoClient source is at AnzoClient.js.

General Tips

• Notice that the Anzo.JS API is almost all asynchronous. Any method that may send a network request take a callback argument. When the operation is completed the function given in the callback argument is called. The arguments will contain the result of the operation. This is good because it means that your HTML UI won't hang waiting for network requests but it does make the code slightly more complicated.
• Take a look at the useful information found at AnzoJSLoggingGuide and AnzoJSDebuggingGuide.