Notes explaining how the VOSpace service works.

The attached diagram shows the main components and steps that are invoked when a client calls the VOSpace service and asks to create a new Node.

HTTP request

The client sends a HTTP POST request containing a SOAP message to the Tomcat web server.

    POST /astrogrid-vospace/vospace-1.1/03efc4cd1c0a3e3c011c0a418d15000b HTTP/1.0
    Content-Type: text/xml; charset=utf-8
    Accept: application/soap+xml, application/dime, multipart/related, text/*
    User-Agent: Axis/1.2.1
    Host: vospace.metagrid.co.uk:8080
    Cache-Control: no-cache
    Pragma: no-cache
    SOAPAction: "http://www.ivoa.net/xml/VOSpaceContract-v1.1-rc3:CreateNode"
    Content-Length: 549

    <?xml version="1.0" encoding="UTF-8"?>
    <soapenv:Envelope>
     <soapenv:Body>
      <CreateNode>
       <node
          uri="vos://org.astrogrid.test!vospace-service/.auto"
          xsi:type="ns1:ContainerNodeType">
        <properties/>
       </node>
      </CreateNode>
     </soapenv:Body>
    </soapenv:Envelope>

The HTTP specification defines the format of a HTTP request.

The first line of a HTTP request contains the verb, POST, followed by the path from the request URL and the protocol version, HTTP/1.0

    POST /astrogrid-vospace/vospace-1.1/03efc4cd1c0a3e3c011c0a418d15000b HTTP/1.0

The next lines contain the HTTP headers, formatted as 'name: value' pairs, upto the first blank line.

    ....
    Content-Type: text/xml; charset=utf-8
    Accept: application/soap+xml, application/dime, multipart/related, text/*
    User-Agent: Axis/1.2.1
    Host: vospace.metagrid.co.uk:8080
    Cache-Control: no-cache
    Pragma: no-cache
    SOAPAction: "http://www.ivoa.net/xml/VOSpaceContract-v1.1-rc3:CreateNode"
    Content-Length: 549

Everything after the first blank line is the request body, in this example it contains our SOAP XML message.

    ....
    <?xml version="1.0" encoding="UTF-8"?>
    <soapenv:Envelope>
     <soapenv:Body>
      <CreateNode>
       <node
          uri="vos://org.astrogrid.test!vospace-service/.auto"
          xsi:type="ns1:ContainerNodeType">
        <properties/>
       </node>
      </CreateNode>
     </soapenv:Body>
    </soapenv:Envelope>

Tomcat

Tomcat processes the request URL to determine which webapp to pass the request to.

    POST /astrogrid-vospace/vospace-1.1/03efc4cd1c0a3e3c011c0a418d15000b HTTP/1.0
    Content-Type: text/xml; charset=utf-8
    ....

Webapp context

The first part of the URL is the 'context' or webapp name 'astrogrid-vospace' in this example.

    POST /astrogrid-vospace/.....
    ....

This matches the 'context' or webapp name used to deploy the AstroGrid VOSpace web application in Tomcat. See webapp deployment.

Servlet mapping

The next part of the URL determines which servlet to pass the request to.

    POST /astrogrid-vospace/vospace-1.1/03efc4cd1c0a3e3c011c0a418d15000b
    ....

The VOSpace web application is a little unusual in that it does not pass the request direct to the Axis Servlet. The 'vospace-1.1' part of the URL is mapped to an intermediate servlet that logs the request, grabs the identifier from the end of the URL, and then passes the request on to the Axis SOAP servlet.

• See servlet doPost()
• See VOSpace Axis servlet doPost()

The net effect is the same as a normal SOAP service, the URL path is matched within the web application, and the request is passed to the Axis servlet.

So far only the first part of the HTTP request has been processed, upto and including the headers. The message body has not been read yet.

Axis Servlet

The HTTP request is passed to the Axis servlet servlet doPost() method, as a HttpRequest object.

The Axis servlet reads the SOAP message by calling getReader() on the HttpRequest.

    ....
    <?xml version="1.0" encoding="UTF-8"?>
    <soapenv:Envelope>
     <soapenv:Body>
      <CreateNode>
       <node
          uri="vos://org.astrogrid.test!vospace-service/.auto"
          xsi:type="ns1:ContainerNodeType">
        <properties/>
       </node>
      </CreateNode>
     </soapenv:Body>
    </soapenv:Envelope>

The Axis servlet processes the outer SOAP envelope elements

    ....
    <?xml version="1.0" encoding="UTF-8"?>
    <soapenv:Envelope>
     <soapenv:Body>
        ....
     </soapenv:Body>
    </soapenv:Envelope>

and then converts the VOSpace message elements into a set of Java Beans that represent the message

    ....
      <CreateNode>
       <node
          uri="vos://org.astrogrid.test!vospace-service/.auto"
          xsi:type="ns1:ContainerNodeType">
        <properties/>
       </node>

The resulting Java Beans are passed to the createNode method on the VOSpace SOAP service.

VOSpace SOAP service

The outer interface of the VOSpace SOAP service is based on a template generated from the VOSpace WSDL specification, which defines the service methods what parameters they take, what results they return, and what exceptions they can throw.

The Java Beans are generated from the VOSpace message schema, which defines the structure of the message components, e.g. CreateNode , Node, Property etc.

The public methods of the Service implementation match the template interface generated from the service WSDL using the Axis tools.

Given all of this information, the Axis servlet will convert this XML

    ....
      <CreateNode>
       <node
          uri="vos://org.astrogrid.test!vospace-service/.auto"
          xsi:type="ns1:ContainerNodeType">
        <properties/>
       </node>

into a call to the createNode method on the service implementation

    /**
     * Create a new node.
     * @param request The Axis request message bean.
     *
     */
    public CreateNodeResponseType createNode(CreateNodeRequestType request)
    throws LinkFoundFaultType ....
        {
        ....
        }

Most of the createNode() method involves converting request the parameters into something that can be passed to the back-end server, and converting the results or exceptions back into their SOAP equivalents.

The VOSpace web application needs to support three SOAP web interfaces, the original AstroGrid MySpace service, and two versions of the VOSpace service (VOSpace-1.0 and VOSpace 1.1). It may also need to support the new VOSpace-2.x REST web interface when that comes online.

In order to do this, the back-end VOSpace server is defined as an abstract server interface that is used by all the web services. The actual web service components act as a translation layer, implementing the web service methods defined in the service specification by calling methods on the back-end server interface.

The inner part of the createNode() method checks what type of node is being requested, and then calls the corresponding method on the back-end server (represented by the session).

    /**
     * Create a new node.
     * @param request The Axis request message bean.
     *
     */
    public CreateNodeResponseType createNode(CreateNodeRequestType request)
    throws LinkFoundFaultType ....
        {
        ....
        //
        // Create our service session.
        Session session = factory.create();

        ....
            //
            // Check the node type
            switch (this.type(request.getNode()))
                {
                //
                // Container node.
                case TREE_NODE :
                        {
                        node = session.createTreeNode(
                            base.ident(),
                            request.getNode().getUri().getPath()            
                            );
                        }
                    break ;
                ....
                }
        ....
        }

VOSpace server

The VOSpace back-end server implements all of the business logic required to manage the tree of nodes and the state transitions involved in creating, modifying and deleting nodes, along with handling the data import and export transfers.

Note - the server (Session) interface isn't pretty, but it does work. It was never really designed, it evolved, adding each bit of functionality a step at a time.

As each bit of functionality was added, the server interface was extended and a corresponding set of JUnit tests were added to the test suite. We now have a set of tests that define pretty much exactly what the server needs to do to support all the web services. The hope is to be able to gradually refactor the server code into a much more structured design, while maintaining the functionality by validating it against the test suite.

Most of the server code operates on plain Java objects with little or no reference to the underlying database structure. It isn't completely isolated from the database yet, and some aspects of the database structure still leak into the code, but again, we hope to improve this by gradual refactoring.

.... map of the business objects and state transitions ....

Hibernate mapping

The server code uses the Hibernate toolkit to map the persistent Java objects onto the database tables. This hides almost all of the details of the database structure and handles all of the database queries.

Hibernate supports several SQL dialects, including most of the common of database servers. This means that the VOSpace web application should be able to function without modification with any of the supported database platforms.

Note - as yet we have only tested with PostgreSQL and MySQL, although we also know someone is planning to use Oracle in the near future.

Database transaction

The result of all this is that we end up with a new object created in the database table.

Return result

The new Node object is passed back up the chain of method calls to the VOSpace SOAP service layer, which wraps the Node as a SOAP message Bean which is then returned to the Axis servlet.

HTTP response

The Axis servlet serializes the SOAP message Bean into XML and sends this back in the HTTP response.

    <?xml version="1.0" encoding="utf-8"?>
    <soapenv:Envelope>
     <soapenv:Body>
      <CreateNodeResponse>
       <node
          uri="vos://org.astrogrid.test!vospace-service/03efc4cd1cd81b01011eaab1a84a1988"
          xsi:type="ns1:ContainerNodeType">
          <properties/>
       </node>
      </CreateNodeResponse>
     </soapenv:Body>
    </soapenv:Envelope>

---

---

-- DaveMorris - 06 Jan 2009

• vospace-request.odg: OpenOffice diagram

• vospace-request.pdf: PDF version