Mako Application Programming Interfaces (APIs)
The Mako API is the XMLDataService API. It uses the base Mobius API as its foundation. The XMLDataService interface provides accessors that allow the execution of operations on Grid XML data services. The XMLDataService interface is an extension of the GridService interface (contained in the base API). It thus provides base grid service operations as well as XML related operations. Handles to XML data services can be created using the grid service resolver as follows:
GridServiceResolver resolver = GridServiceResolver.getInstance();
GridService gs = resolver.getGridService("MAKO://localhost");
XMLDataService xds = (XMLDataService)gs;
An XML data service consists of a set of collections that contain XML documents and their corresponding schemas. XML collections are represented in the Mako API with the XMLCollection interface. When performing operations on a XMLDataService that returns or requires the use of an XML collection, the XMLCollection interface is used. The XMLCollection provides operations that can be performed on XML collections. Such operations include, but are not limited to, adding a schema, adding a document, and performing an XPath query.
XML collections consist of a collection of XML documents, which are represented in the Mako API by the XMLDocument interface. The XMLDocument interface provides accessors to operations that can be performed on XML documents.
Finally the MakoAPI consists of two other objects that represent components that could be returned in the results of a query. The XMLAttribute interface represents an attribute in an XML document and the XMLText object represents a CDATA section in an XML document.
The remainder of this page will be devoted to giving code examples for performing operations on XML data services. The code examples assume that the GridServiceResolver has been configured with a default GridServiceFactory, this can be done as follows:
GridServiceResolver resolver = GridServiceResolver.getInstance(); resolver.setDefaultFactory(new NetworkServiceFactory());
The code snippet below shows how to get a handle to an XML Data Service and prints all the root level collections that exist on an XML data service.
GridServiceResolver resolver = GridServiceResolver.getInstance();
GridService gs = resolver.getGridService("MAKO://localhost");
XMLDataService xds = (XMLDataService)gs;
List collections = xds.getCollections();
for(int i=0; i<collections.size(); i++){
XMLCollection col = (XMLCollection)collections;
System.out.println(col.getName());
}
The following code shows an example of how to print out all the sub-collections for a collection, called "myCollection".
GridServiceResolver resolver = GridServiceResolver.getInstance();
GridService gs = resolver.getGridService("MAKO://localhost");
XMLDataService xds = (XMLDataService)gs;
XMLCollection collection = xds.getCollection("/myCollection");
List collections = collection.getSubCollections();
for(int i=0; i<collections.size(); i++){
XMLCollection col = (XMLCollection)collections;
System.out.println(col.getName());
}
The code snippet below shows how to create a collection on an XML data service.
GridServiceResolver resolver = GridServiceResolver.getInstance();
GridService gs = resolver.getGridService("MAKO://localhost");
XMLDataService xds = (XMLDataService)gs;
XMLCollection collection = xds.createCollection("/myCollection");
The code snippet below shows how to create a sub-collection on collection.
GridServiceResolver resolver = GridServiceResolver.getInstance();
GridService gs = resolver.getGridService("MAKO://localhost");
XMLDataService xds = (XMLDataService)gs;
XMLCollection collection = xds.getCollection(/"myCollection"");
XMLCollection subCol = collection.createSubCollection("mySubCollection"");
The code snippet below shows how to remove a collection from a XML data service.
GridServiceResolver resolver = GridServiceResolver.getInstance();
GridService gs = resolver.getGridService("MAKO://localhost");
XMLDataService xds = (XMLDataService)gs;
xds.removeCollection("/myCollection");
The code snippet below shows how to remove a sub-collection from a collection.
GridServiceResolver resolver = GridServiceResolver.getInstance();
GridService gs = resolver.getGridService(""MAKO://localhost");
XMLDataService xds = (XMLDataService)gs;
XMLCollection collection = xds.getCollection("/myCollection");
collection.removeSubCollection("mySubCollection");
Below is an example for adding a schema to an XML collection.
GridServiceResolver resolver = GridServiceResolver.getInstance();
GridService gs = resolver.getGridService("MAKO://localhost");
XMLDataService xds = (XMLDataService)gs;
XMLCollection collection = xds.getCollection("/myCollection");
collection.addSchema(schemaText);
The following code illustrates how to submit an XML document to an XML collection.
GridServiceResolver resolver = GridServiceResolver.getInstance();
GridService gs = resolver.getGridService("MAKO://localhost");
XMLDataService xds = (XMLDataService)gs;
XMLCollection collection = xds.getCollection("/myCollection");
collection.addDocument(xmlText);
XML Documents and, in most cases, elements within documents are all assigned unique identifiers within a Mako. This provides the ability for users to support retrieval of subsets of documents or even request partial documents. These unique identifies are referred to as document references. Document references are compromised of a three tuple identifier consisting of the service id of the Grid service it resides on, the collection that the XML entity resides in, and the unique identifier assigned to it by a Mako. A document reference is a unique identifier within a grid.
Documents can be retrieved from a Mako by requesting them directly or through a query such as XPath. A subset of an XML document can be retrieved by requesting the sub entity by its document reference. Partial documents can be retrieved by requesting the XML depth of the XML document. For example if a depth of 2 is requested, the root element and it children will be returned with document references to its children's children. This feature allows clients to work efficiently with large documents.
Mako can also distribute a single XML document across multiple Makos. When retrieving such documents one may specify whether or not entities on other Makos should be resolved. If they are not resolved, Document References are included instead.
Below we show an example of retrieving an XML document from a Mako. The XMLRetrievalPolicy object is used to specify how the document is to be retrieved. The example below retrieves the entire XML document. For a custom materialization, one could create a custom XMLRetrievalPolicy.
GridServiceResolver resolver = GridServiceResolver.getInstance();
GridService gs = resolver.getGridService("MAKO://localhost");
XMLDataService xds = (XMLDataService)gs;
XMLCollection collection = xds.getCollection("/myCollection");
XMLDocument doc = collection.getDocument("28000000000000001");
String xml = doc.getContent(XMLRetrievalPolicy.FULL_MATERIALIZATION);
System.out.println(xml);
A Mako can be queried using XPath. Like direct document retrieval, XPath document retrieval requires an XMLRetrievalPolicy to specify how the results are retrieved. Performing an XPath query also requires a NamespaceManager, which allows XML namespaces to be built into XPath queries. An XPath query returns a list of result objects. Depending on the query the result list will contain XMLDocument, XMLText, or XMLAttribute objects. Below is a code snippet illustrating how to perform an XPath query:
GridServiceResolver resolver = GridServiceResolver.getInstance();
GridService gs = resolver.getGridService("MAKO://localhost");
XMLDataService xds = (XMLDataService) gs;
XMLCollection collection = xds.getCollection("/myCollection");
NamespaceManager nm = new NamespaceManager();
Namespace defaultNS = new Namespace("projectmobius.org/1/Person");
Namespace ns1 = new Namespace("projectmobius.org/1/Address");
nm.setDefaultNamespace(defaultNS);
nm.addNamespace("ns1", ns1);
String xpath = "/person/ns1:address";
List results = collection.performXPath(nm, xpath, XMLRetrievalPolicy.FULL_MATERIALIZATION);
for (int i=0; i<results.size(); i++) {
XMLDocument doc = (XMLDocument) results.get(i);
String xml = doc.getContent(XMLRetrievalPolicy.FULL_MATERIALIZATION);
System.out.println(xml);
}
The code snippet below illustrates how to submit and then remove a document from a Mako.
GridServiceResolver resolver = GridServiceResolver.getInstance();
GridService gs = resolver.getGridService("MAKO://localhost");
XMLDataService xds = (XMLDataService)gs;
XMLCollection collection = xds.getCollection("/myCollection");
XMLDocument doc = collection.addDocument(xmlText);
String docId = doc.getDocumentId();
collection.removeDocument(docId,true);
The code snippet below illustrates how to remove XML documents from a Mako via an XPath.
GridServiceResolver resolver = GridServiceResolver.getInstance();
GridService gs = resolver.getGridService("MAKO://localhost");
XMLDataService xds = (XMLDataService) gs;
XMLCollection collection = xds.getCollection("/myCollection");
NamespaceManager nm = new NamespaceManager();
Namespace defaultNS = new Namespace("projectmobius.org/1/Person");
nm.setDefaultNamespace(defaultNS);
String xpath = "/person";
collection.removeDocumentsByXPath(nm,xpath,true);
This code illustrates how to perform an XUpdate on a collection:
GridServiceResolver resolver = GridServiceResolver.getInstance();
GridService gs = resolver.getGridService("MAKO://localhost");
XMLDataService xds = (XMLDataService) gs;
XMLCollection collection = xds.getCollection("/myCollection");
collection.performXUpdate(xupdateText);