Montag
Montag Web
 
   

Montag Web Services Working Guide
Notice: This guide always refers to the latest Montag version.

Introduction

This guide will show you the differences between the local and remote modes, and how to use the services and their RPC-style operations in both modes.

Connecting to Montag web services

After configuring Montag and starting your application server, you can connect to every service using the URL: 

 host.name.org:port/montag/services/service_name

Here, host.name.org:port is your hostname with the application server port, and service_name is the name of the service you want to connect to.
Example: localhost:8080/montag/services/GetDocument

Using web services in local mode

In local mode, web services don't store any state between different method calls, whether the calling client is the same or not. So, for every operation the service must connect to the database collection and, at the end of the operation, close the collection; however, this is absolutely transparent to the client: it must only call the wanted operation.
Username and password for connecting to the collection (if required) are taken from the local-config.xml file, located in the computer where Montag is installed, or from the header of the SOAP client request; in the latter case, the client must insert, into the header of its SOAP request message, the following two elements:

  • username: containing the username for the collection you want to connect to.
  • password: containing the password for the collection you want to connect to.

If username and password are in both the local-config file and in the SOAP header, the latter will be used.


Note
Why calling this working mode "local"?
Because, for working in this mode, you must locally configure Montag (through the local-config file), or passing, for every operation, username and password in the SOAP message header, which is secure only if your clients interact with Montag locally in the same machine (or in a safe network like a LAN).


For using Montag services in this mode, simply configure the montag-config.xml and the local-config.xml files. For doing this, refer to the Montag Configuration Guide.
A per service explanation follows.

CollectionManager Web Service

This service permits client to create and remove XML Database collections.
It has two methods:

  • createCollection

    void createCollection(String parent, String newCol)

    Use this method to create a new collection, starting from a given parent collection.
    These are, in order, the method parameters:

    1. parent: The parent collection name, in its full path from the root collection and without the leading slash (examples: test1, or test1/test2).
    2. newCol: The new collection name.


    Optional extensions in the SOAP request header: username and password elements for accessing the desired collection.
    Returns: Nothing.
    Throws: a SOAP Fault if there were some errors (see the Error Codes section for additional information).

  • removeCollection

    void removeCollection(String parent, String col, boolean removeContents)

    Use this method to remove an existing collection, starting from a given parent collection.
    These are, in order, the method parameters:

    1. parent: The parent collection name, in its full path from the root collection and without the leading slash (examples: test1, or test1/test2).
    2. col: The name of the collection to remove.
    3. removeContents: A boolean value that must be set to true to remove a collection and all of its content.


    Optional extensions in the SOAP request header: username and password elements for accessing the desired collection.
    Returns: Nothing.
    Throws: a SOAP Fault if there were some errors (see the Error Codes section for additional information).

AddDocumet Web Service

This service permits client to add XML documents to a collection.
It has one method:

  • addDocument

    void addDocument(String collection, String id, String xmlDoc)

    Use this method to add a new document to a given collection.
    These are, in order, the method parameters:

    1. collection: The collection to which adding the document, in its full path from the root collection and without the leading slash (examples: test1, or test1/test2).
    2. id: The identification string for the new document.
      This must be unique among the documents in the same collection.
    3. xmlDoc: A string representing the XML document to add.


    Optional extensions in the SOAP request header: username and password elements for accessing the desired collection.
    Returns: Nothing.
    Throws: a SOAP Fault if there were some errors (see the Error Codes section for additional information).

RemoveDocumet Web Service

This service permits client to remove XML documents from a collection.
It has one method:

  • removeDocument

    void removeDocument(String collection, String id)

    Use this method to remove a document from a given collection.
    These are, in order, the method parameters:

    1. collection: The collection from which removing the document, in its full path from the root collection and without the leading slash (examples: test1, or test1/test2).
    2. id: The identification string of the document to remove.


    Optional extensions in the SOAP request header: username and password elements for accessing the desired collection.
    Returns: Nothing.
    Throws: a SOAP Fault if there were some errors (see the Error Codes section for additional information).

GetDocumet Web Service

This service permits client to retrieve a XML document from a collection.
It has one method:

  • getDocument

    String getDocument(String collection, String id)

    Use this method to get a document from a given collection.
    These are, in order, the method parameters:

    1. collection: The collection to which adding the document, in its full path from the root collection and without the leading slash (examples: test1, or test1/test2).
    2. id: The identification string of the document to retrieve.


    Optional extensions in the SOAP request header: username and password elements for accessing the desired collection.
    Returns: A string representing the requested XML document (if any).
    Throws: a SOAP Fault if there were some errors (see the Error Codes section for additional information).

QueryService Web Service

This service permits client to make XPath queries at document-level or collection-level.
It has two methods:

  • queryDocument

    String queryDocument(String collection, String id, String query, String[] namespaces)

    Use this method to make a XPath query to a single document, identified by its id.
    These are, in order, the method parameters:

    1. collection: The collection to which the document belongs, in its full path from the root collection and without the leading slash (examples: test1, or test1/test2).
    2. id: The document identification string.
    3. query: A string representing the XPath query.
    4. namespaces: An array of strings in the form (prefix,uri,prefix,uri ...), which defines the namespaces used in the query.


    Optional extensions in the SOAP request header: username and password elements for accessing the desired collection.
    Returns: A string representing the query results, formatted in a particular XML document (see the XML Result Set Definition section for additional information).
    Throws: a SOAP Fault if there were some errors (see the Error Codes section for additional information).

  • queryCollection

    String queryCollection(String collection, String query, boolean addNodeSet, String[] namespaces)

    Use this method to make a XPath query to a whole collection.
    These are, in order, the method parameters:

    1. collection: The collection to query, in its full path from the root collection and without the leading slash (examples: test1, or test1/test2).
    2. query: A string representing the XPath query.
    3. addNodeSet: A boolean value that must be set to true for adding node sets to the XML result set.
    4. namespaces: An array of strings in the form (prefix,uri,prefix,uri ...), which defines the namespaces used in the query.


    Optional extensions in the SOAP request header: username and password elements for accessing the desired collection.
    Returns: A string representing the query results, formatted in a particular XML document (see the XML Result Set Definition section for additional information).
    Throws: a SOAP Fault if there were some errors (see the Error Codes section for additional information).

XUpdateService Web Service

This service permits client to modify XML documents simply sending XUpdate instructions to a XML Database collection, removing the need to extract the documents from the collection and modify them by hand.
It has two methods:

  • updateDocument

    long updateDocument(String collection, String id, String xupdate)

    Use this method to modify a single document, identified by its id.
    These are, in order, the method parameters:

    1. collection: The collection to which the document belongs, in its full path from the root collection and without the leading slash (examples: test1, or test1/test2).
    2. id: The document identification string.
    3. xupdate: The XUpdate document containing the instructions for modifying the target document.


    Optional extensions in the SOAP request header: username and password elements for accessing the desired collection.
    Returns: The number of modified nodes.
    Throws: a SOAP Fault if there were some errors (see the Error Codes section for additional information).

  • updateCollection

    long updateCollection(String collection, String xupdate)

    Use this method to modify a collection of documents. XUpdate instructions will be applied to every document.
    These are, in order, the method parameters:

    1. collection: The target collection, in its full path from the root collection and without the leading slash (examples: test1, or test1/test2).
    2. xupdate: The XUpdate document containing the instructions for modifying the documents in the target collection.


    Optional extensions in the SOAP request header: username and password elements for accessing the desired collection.
    Returns: The number of modified nodes.
    Throws: a SOAP Fault if there were some errors (see the Error Codes section for additional information).


Note
The namespaces used in XPath queries into the XUpdate document must be declared in the root element.
For additional information about XUpdate, please refer to this link.


Using web services in remote mode

In remote mode, every single service works in a session-oriented fashion, storing state between different calls from the same client.
These are the necessary steps involved in managing the session with a service and using its operations:

  1. Opening the connection:: This connects the service to a specified XML Database collection and maintains the collection opened.
    The client must specify the collection name, username and password.
    Moreover, this operation returns, in the SOAP header, a session identifier (in an element named sid) that the client will have to insert in the header of its following SOAP requests, in order to bind them to the established session.
  2. Calling the service operations: After the session establishment, the client can call the service operations whenever it wants; it must only remember to pass its sid in the header of every SOAP request, inserting its value in an element named sid. Note that every operation returns in its SOAP response header the same sid.
  3. Closing the connection: This simply closes the connection with the collection; again, the client must remember to pass its sid in the SOAP request header, inserting its value in an element named sid.

So, every remote service will have two common methods:

  • connect

    void connect(String col, String username, String password)

    These are, in order, the method parameters:
    1. col: The name of the collection to connect to, in its full path from the root collection and without the leading slash (examples: test1, or test1/test2).
    2. username: The username for connecting to the collection (if required).
    3. password: The password for connecting to the collection (if required).


    Required extensions in the SOAP response header: A sid element containing the session identifier in string format.
    Returns: Nothing.
    Throws: a SOAP Fault if there were some errors (see the Error Codes section for additional information).

  • close

    void close()

    There are no method parameters.


    Required extensions in the SOAP request header: A sid element containing the session identifier in string format.
    Returns: Nothing.
    Throws: a SOAP Fault if there were some errors (see the Error Codes section for additional information).


Note
Once connected, every operation acts to the collection specified at connection time.
For changing connection, simply close the connection and connect to a new collection.


For using Montag services in this mode, simply configure the montag-config.xml and the remote-config.xml files. For doing this, refer to the Montag Configuration Guide.
A per service explanation follows.


Note
Why calling this working mode "remote"?
Because it should be used when Montag services cannot be locally configured and/or when its clients are not in the same machine and they communicate through an insecure channel, raising the need to pass username and password only one time, at connection.


CollectionManager Web Service

This service permits client to create and remove XML Database collections.
It has two methods:

  • createCollection

    void createCollection(String newCol)

    Use this method to create a new collection, starting from the given parent collection specified at connection time.
    These are, in order, the method parameters:

    1. newCol: The new collection name.


    Required extensions in the SOAP request header: A sid element containing the session identifier in string format.
    Required extensions in the SOAP response header: A sid element containing the session identifier in string format.
    Returns: Nothing.
    Throws: a SOAP Fault if there were some errors (see the Error Codes section for additional information).

  • removeCollection

    void removeCollection(String col, boolean removeContents)

    Use this method to remove an existing collection, starting from the given parent collection specified at connection time.
    These are, in order, the method parameters:

    1. col: The name of the collection to remove.
    2. removeContents: A boolean value that must be set to true to remove a collection and all of its content.


    Required extensions in the SOAP request header: A sid element containing the session identifier in string format.
    Required extensions in the SOAP response header: A sid element containing the session identifier in string format.
    Returns: Nothing.
    Throws: a SOAP Fault if there were some errors (see the Error Codes section for additional information).

AddDocumet Web Service

This service permits client to add XML documents to the collection specified at connection time.
It has one method:

  • addDocument

    void addDocument(String id, String xmlDoc)

    Use this method to add a new document to a given collection.
    These are, in order, the method parameters:

    1. id: The identification string for the new document.
      This must be unique among the documents in the same collection.
    2. xmlDoc: A string representing the XML document to add.


    Required extensions in the SOAP request header: A sid element containing the session identifier in string format.
    Required extensions in the SOAP response header: A sid element containing the session identifier in string format.
    Returns: Nothing.
    Throws: a SOAP Fault if there were some errors (see the Error Codes section for additional information).

RemoveDocumet Web Service

This service permits client to remove XML documents from the collection specified at connection time.
It has one method:

  • removeDocument

    void removeDocument(String id)

    Use this method to remove a document from a given collection.
    These are, in order, the method parameters:

    1. id: The identification string of the document to remove.


    Required extensions in the SOAP request header: A sid element containing the session identifier in string format.
    Required extensions in the SOAP response header: A sid element containing the session identifier in string format.
    Returns: Nothing.
    Throws: a SOAP Fault if there were some errors (see the Error Codes section for additional information).

GetDocumet Web Service

This service permits client to retrieve a XML document from the collection specified at connection time.
It has one method:

  • getDocument

    String getDocument(String id)

    Use this method to get a document from a given collection.
    These are, in order, the method parameters:

    1. id: The identification string of the document to retrieve.


    Required extensions in the SOAP request header: A sid element containing the session identifier in string format.
    Required extensions in the SOAP response header: A sid element containing the session identifier in string format.
    Returns: A string representing the requested XML document (if any).
    Throws: a SOAP Fault if there were some errors (see the Error Codes section for additional information).

QueryService Web Service

This service permits client to make XPath queries at document-level or collection-level.
It has two methods:

  • queryDocument

    String queryDocument(String id, String query, String[] namespaces)

    Use this method to make a XPath query to a single document, identified by its id and belonging to the collection specified at connection time.
    These are, in order, the method parameters:

    1. id: The document identification string.
    2. query: A string representing the XPath query.
    3. namespaces: An array of strings in the form (prefix,uri,prefix,uri ...), which defines the namespaces used in the query.


    Required extensions in the SOAP request header: A sid element containing the session identifier in string format.
    Required extensions in the SOAP response header: A sid element containing the session identifier in string format.
    Returns: A string representing the query results, formatted in a particular XML document (see the XML Result Set Definition section for additional information).
    Throws: a SOAP Fault if there were some errors (see the Error Codes section for additional information).

  • queryCollection

    String queryCollection(String query, boolean addNodeSet, String[] namespaces)

    Use this method to make a XPath query to the whole collection, specified at connection time.
    These are, in order, the method parameters:

    1. query: A string representing the XPath query.
    2. addNodeSet: A boolean value that must be set to true for adding node sets to the XML result set.
    3. namespaces: An array of strings in the form (prefix,uri,prefix,uri ...), which defines the namespaces used in the query.


    Required extensions in the SOAP request header: A sid element containing the session identifier in string format.
    Required extensions in the SOAP response header: A sid element containing the session identifier in string format.
    Returns: A string representing the query results, formatted in a particular XML document (see the XML Result Set Definition section for additional information).
    Throws: a SOAP Fault if there were some errors (see the Error Codes section for additional information).

XUpdateService Web Service

This service permits client to modify XML documents simply sending XUpdate instructions to a XML Database collection, removing the need to extract the documents from the collection and modify them by hand.
It has two methods:

  • updateDocument

    long updateDocument(String id, String xupdate)

    Use this method to modify a single document, identified by its id and belonging to the collection specified at connection time.
    These are, in order, the method parameters:

    1. id: The document identification string.
    2. xupdate: The XUpdate document containing the instructions for modifying the target document.


    Required extensions in the SOAP request header: A sid element containing the session identifier in string format.
    Required extensions in the SOAP response header: A sid element containing the session identifier in string format.
    Returns: The number of modified nodes.
    Throws: a SOAP Fault if there were some errors (see the Error Codes section for additional information).

  • updateCollection

    long updateCollection(String xupdate)

    Use this method to modify a collection of documents, specified at connection time. XUpdate instructions will be applied to every document.
    These are, in order, the method parameters:

    1. xupdate: The XUpdate document containing the instructions for modifying the documents in the target collection.


    Required extensions in the SOAP request header: A sid element containing the session identifier in string format.
    Required extensions in the SOAP response header: A sid element containing the session identifier in string format.
    Returns: The number of modified nodes.
    Throws: a SOAP Fault if there were some errors (see the Error Codes section for additional information).


Note
The namespaces used in XPath queries into the XUpdate document must be declared in the root element.
For additional information about XUpdate, please refer to this link.


Getting the WSDL

Clients can get the WSDL (Web Services Definition Language) of every service making a request to the service with the "wsdl" word appended.
Example: 

                http://localhost/montag/AddDocument?wsdl

This will return the WSDL document for the service.

XML Result Set Definition

Every query operation returns a string representation of a particular XML document that formats results in a database independent and machine understandable way.
Here is an example, containing the nodes of the documents that match the query: 

            
                    <?xml version="1.0" encoding="UTF-8"?>
                    <result-set>
                            <item collection="test" id="1">
                                    <node>
                                            <nested>content</nested>
                                    </node>
                            </item>
                            <item collection="test" id="2">
                                    <node>
                                            <nested>other content</nested>
                                    </node>
                            </item>
                    </result-set>

And another example, which doesn't contain the nodes of the documents that match the query: 

            
                    <?xml version="1.0" encoding="UTF-8"?>
                    <result-set>
                            <item collection="test" id="1"/>
                            <item collection="test" id="2"/>
                    </result-set>

So, the structure is simple: there is an item element for each XML document that matches the query, and each item has two mandatory attributes, acting as a key for the element:

  • collection: the collection to which the XML document belongs.
  • id: the identification string of the XML document.

Plus an optional content, the matching nodes of the XML document, that can be any valid, well formed, XML data; this can be left out for faster transmission and elaboration time.

Error Codes Definition

If something goes wrong, every service method throws a SOAP fault to inform the client about the error.
Every fault has a fault string, which describes the error, and a machine understandable fault code, composed by the word client, if it was a client error, or the word server, if it was a server error, plus an identification number.
Here are the error codes actually implemented:

Client.1
Error in service method parameters.
Server.2
Error in connecting to a collection.
Server.3
Error in closing a collection.
Server.4
Error in adding a document.
Server.5
Error in removing a document.
Server.6
Error in retrieving a document.
Server.7
Error in querying a document or a whole collection.
Client.8
Remote mode error: client tried to make an operation over the database without first connecting to a collection.
Server.9
Session management error.
Server.10
Error in creating a collection.
Server.11
Server side error in removing a collection.
Client.12
Client side error in removing a collection.
Server.13
Error in WSDL generation.
Server.14
Error in updating a document or a whole collection.
Server.15
The requested operation is not supported by the Native XML Database.

Final Words

Despite of the features and the two different working modes, I think using Montag web services is simple and straightforward.
I hope this guide will help you.
For any help request, error report, suggestion or contribution, please use the forums, the mailing list, or send me an e-mail, putting the word Montag in the subject, at sb_tourist@tin.it.

by Sergio Bossa; Version 1.0
Copyright © 2004 - 2005 Sergio Bossa (sb_tourist@tin.it) All rights reserved.