We began presenting an example of a software repository in part 2 of this column, illustrating how a lot of the heavy lifting of data and metadata management could be made much simpler by using available Web tools and open Web standards such as XML, XSLT, and RDF. Since building the core of the software repository was so simple, we now have time to contemplate how to represent this in a Web service.

In this article, we will look at ways of adding content to the software repository using HTTP POST and SOAP. Also, we'll look at a SD description of the resulting Web service and how 4Suite Server can help expose this. You will want to be familiar with the work from part 2 as well as with HTML forms and the Hypertext Transport Protocol (HTTP) protocol (see Resources).

Software by post

To begin with we should look at updates using simple HTTP POST. This can serve as a means for both human contributors and software agents to provide updates, the former by way of a browser form.

Start by making sure that the software repository core is set up using the steps we explained in part 2. Unfortunately, there's a twist. The last article was based on 4Suite Server version 0.10.2, but since then we released version 0.11.0, with significant improvements. See Resources for an update to the last article that covers the 0.11.0 release.

Let's say the form for contributors to use in adding entries to the repository is as in Figure 1. This corresponds to the HTML in Listing 1.

4Suite Server allows us to set up an XSL transform to handle POST requests such as this form generates, creating a new document that is added to the XML repository. The XSL transform we use for the purpose of adding an entry to the software repository is in Listing 2.

The action attribute of the form element in our HTML source is interpreted with the document at the path in the URI as the source, and the template-xslt argument is interpreted as the XSL transform to use for generating the new document.

<?xml version="1.0"?>
<xsl:stylesheet
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:ftext="http://xmlns.4suite.org/ext"
  extension-element-prefixes="ftext"
  version="1.0"
>
  <xsl:param name='title'/>
  <xsl:param name='creator'/>
  <xsl:param name='home'/>
  <xsl:param name='version'/>
  <xsl:param name='description'/>
  <xsl:template match="/">
<rdf:RDF
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  xmlns:dc="http://purl.org/dc/elements/1.1"
  xmlns="http://namespaces.4suite.org/www/software-map"
>
  <Software rdf:ID="{$title}">
    <dc:Title><xsl:value-of select='$title'/></dc:Title>
    <dc:Creator><xsl:value-of select='$creator'/></dc:Creator>
    <dc:Description><xsl:value-of select='$description'/></dc:Description>
    <CurrentVersion><xsl:value-of select='$version'/></CurrentVersion>
    <Home rdf:resource="{$home}"/>
  </Software>
</rdf:RDF>
    <ftext:set-post-template-params
      new-doc-uri="incoming/{$title}-{$version}.xml"
      response-uri="thanks.xhtml"
      docdef="dublin_core"
    />
  </xsl:template>
</xsl:stylesheet>

The first thing to note is the group of parameters such as title and creator. These are automatically set by the server to the values from the form elements of the same name, which become HTTP POST query arguments. These parameters can then be used to craft the output using all the tools XSLT places at our disposal. As you can see, the transform is creating a software description document in the form we introduced in the first part of this series. We omitted some optional fields for simplicity.

Finally, observe the ftext:set-post-template-params extension element at the end of the transform. This is a special extension set up by the server which allows you to set such important parameters as the URI of the document to be added, its document definition and the URI to be used by the server to generate the HTML to be sent in response to the HTTP POST (this is, for instance, the HTML that would appear in the browser after the "Submit" button was clicked to submit an entry).

The steps involved are briefly outlined here:

1. Create a container and give universal read access to it.
2. Create a document for the HTTP POST operation.
3. Create the XSLT template.
4. Create the submission response document.
5. Create the container to store the output.

To try this yourself, first create an appropriate container and grand universal read access to it:

$ 4ss create container /softrepo
$ 4ss set acl --world-read /softrepo

Then create a simple dummy document (just "<null/>") as the HTTP POST target. For example:

$ 4ss create document - BASE_XML /softrepo/submit-new-software-entry
<null/>
$ 4ss set acl --world-read /softrepo/submit-new-software-entry

If you specify "-" as the source for the XML document, the command will read the XML source from standard input. Next, create the template XSLT document, as shown below:

$ 4ss create document submit-entry.xslt BASE_XSLT /softrepo/submit-entry.xslt
$ 4ss set acl --world-read softrepo/submit-entry.xslt

Now create the submission response document as follows:

$ 4ss create document - BASE_XML softrepo/thanks.xhtml
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE html PUBLIC
"-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html xmlns='http://www.w3.org/1999/xhtml'>
<head>
<title>Thanks for your submission</title>
</head>
<body>
  <p>Thanks for your submission to the software repository.</p>
</body>
$ 4ss set acl --world-read softrepo/thanks.xhtml

Finally, create the container where submitted software records will go. This one must be world-writable in order for the documents to be added by anonymous users. See listing 3e.

$ 4ss create container softrepo/incoming
$ 4ss set acl --world-write softrepo/incoming

Once this is set up, people can enter the data into a form, or software agents can enter the data using HTTP libraries in the language of choice. There is, however, an alternative growing in popularity for software-to-software access of data, without involving humans.

Back to top

Software on a rope

4Suite Server implements the basic SOAP API, which we can use as the basis of our software repository Web service.

Listing 4 is a simple Python command-line program that adds a software entry file using the direct SOAP API. Note the special encoding style http://4suite.org/4ss/direct used in the direct 4Suite Server API. This encoding basically consists of an element representing the method invocation and attributes representing the parameters, and in some cases a body containing a document that serves as a parameter. Other than that, Listing 4 is pretty straightforward code to construct an XML representing a SOAP request document from command-line parameters -- put this into an HTTP request, send it off and listen for the response.

import sys, string, httplib, base64, mimetools
SERVER_ADDR = '127.0.0.1'
SERVER_PORT = 8080
BODY_TEMPLATE = """<SOAP-ENV:Envelope
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:ft="http://xmlns.4suite.org/services"
  SOAP-ENV:encodingStyle="http://4suite.org/4ss/direct"
>
  <SOAP-ENV:Body>
    <ft:Create doc-def-name="%s" uri="%s">
%s
    </ft:Create>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>"""
#define the function
def AddSoftwareFromFile(entry, docdef, uri):
    body = BODY_TEMPLATE%(docdef, uri, base64.encodestring(entry))
    blen = len(body)
    requestor = httplib.HTTP(SERVER_ADDR, SERVER_PORT)
    requestor.putrequest('POST', '/soap-handler')
    requestor.putheader('Host', SERVER_ADDR)
    requestor.putheader('Content-Type', 'text/plain; charset="iso-8859-1"')
    requestor.putheader('Content-Length', str(blen))
    requestor.putheader('SOAPAction', "")
    requestor.endheaders()
    requestor.send(body)
    (status_code, message, reply_headers) = requestor.getreply()
    reply_body = requestor.getfile().read()
    print status_code
    print message
    print reply_body
if __name__ == "__main__":
    fname = sys.argv[1]
    docdef = sys.argv[2]
    uri = sys.argv[3]
    entry = open(fname, 'r').read()
    AddSoftwareFromFile(entry, docdef, uri)

A sample session running this program is shown in Listing 4b.

As you can see, the server merely echoes back the document added to the repository.

But what if we simply want to pass the server a few bits of relevant information for us and have it construct the software repository entry, as we did in the above HTTP POST example? 4Suite Server allows you to write your own specialized SOAP handler as shown in the example in Listing 5. This example handles SOAP messages consisting of the various fields describing the software, composes the description file on the server side, and then, adds it to the repository.

The most important part of this module is the SoftRepoSoapHandler class that is subclassed from the 4Suite Server SoapHandler. All the customized class has to do is define a mapping, NS_TO_HANDLER_MAPPING, which for each namespace defines another mapping from SOAP body element name to a handler function. In our case, we set up the AddEntry function to handle our intended requests.

In order to use this handler module, we must register it with 4Suite Server. This can be done by copying the Python file to a spot on the PYTHONPATH and appending a stanza such as the following to the configuration file.See listing 6a.

  <rdf:Description ID='SoftRepoSoapHandler'>
    <rdf:type resource='http://xmlns.4Suite.org/4ss/properties#HttpHandler'/>    
    <Priority>30</Priority>
    <Module>SoftRepoSoapHandler</Module>
  </rdf:Description>

You also need to add a line to the PythonServer or ApacheServer configuration stanza referring to the new handler we set up:

    <Handler resource='#SoftRepoSoapHandler'/>

Once the handler is set up, you can make even simpler SOAP calls to add an entry to the software repository. Listing 7 is example client code for the purpose.

import sys, httplib
SERVER_ADDR = '127.0.0.1'
SERVER_PORT = 8080
BODY_TEMPLATE = """<SOAP-ENV:Envelope
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:s="http://spam.com/softrepo"
  SOAP-ENV:encodingStyle="http://spam.com/softrepo/encoding"
>
  <SOAP-ENV:Body>
    <s:Add>
      <s:Title><![CDATA[%s</s:Title>
      <s:Creator><![CDATA[%s</s:Creator>
      <s:Home><![CDATA[%s</s:Home>
      <s:Version><![CDATA[%s</s:Version>
      <s:Description><![CDATA[%s</s:Description>
    </s:Add>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>"""
#define the function
def AddEntry(title, version):
    creator = raw_input("Creator: ")
    home = raw_input("Home: ")
    desc = raw_input("Description: ")
    body = BODY_TEMPLATE%(title, creator, home, version, desc)
    blen = len(body)
    requestor = httplib.HTTP(SERVER_ADDR, SERVER_PORT)
    requestor.putrequest('POST', '/softrepo/soap-handler')
    requestor.putheader('Host', SERVER_ADDR)
    requestor.putheader('Content-Type', 'text/plain; charset="iso-8859-1"')
    requestor.putheader('Content-Length', str(blen))
    requestor.putheader('SOAPAction', "")
    requestor.endheaders()
    requestor.send(body)
    (status_code, message, reply_headers) = requestor.getreply()
    reply_body = requestor.getfile().read()
    print status_code
    print message
    print reply_body
if __name__ == "__main__":
    title = sys.argv[1]
    version = sys.argv[2]
    AddEntry(title, version)

Save Listing 7 as add_software2.py and try it out as shown in Listing 7b.

Back to top

Moving right along...

SOAP support allows integration of our software repository with the rapidly emerging Web services infrastructure, while basic HTTP POST support allows humans and more traditional HTTP-based automation. As we have shown it is fairly simple to build both those interfaces into the same application using Python based services. In the next installment we shall round out the techniques for development of our software repository as a Web Service.

Resources

• Participate in the discussion forum.
  
  
• Get an overview of the purpose of this series by reading the first installment.
  
  
• In previous installment in this series introduces the software repository and has links to other relevant resources, including the software we use. However, this last installment only addresses 4Suite Server 0.10.2, so we have placed an update of the article for 4SS 0.11.0. Please take a look at it: Web services software repository, Part 1
  
  
• RFC 2616: The IETF format specification for HTTP
  
  
• RFC 2068: The IETF HTTP 1.1 specification
  
  
• Brief ApacheWeek article on HTTP authoring
  
  
• The SOAP 1.1 specification
  
  
• The xml.org Cover Pages on SOAP
  
  
• Developmentor's SOAP pages, including a SOAP FAQ
  
  

About the authors

Mike Olson (molson@fourthought.com) and Uche Ogbuji (uche@fourthought.com) are co-founders of and principal consultants at Fourthought Inc., where they develop the open-source tools 4Suite and 4Suite Server , and provide commercial consulting, training, and 4Suite customization for clients working with XML and Web services. They reside in Boulder, Colorado.

Mike Olson (molson@fourthought.com) and Uche Ogbuji (uche@ogbuji.net) are co-founders of and principal consultants at Fourthought Inc., where they develop the open-source tools 4Suite and 4Suite Server , and provide commercial consulting, training, and 4Suite customization for clients working with XML and Web services. They reside in Boulder, Colorado.

Rate this article

Comments

Back to top

Table of contents

• Software by post
• Software on a rope
• Moving right along...
• Resources
• About the authors
• Comments

Next steps from IBM

Rational Tester for SOA Quality is an automated web services testing and SOA testing tool that supports Web services SOAP, HTTP(S), JMS, WS-Security, UDDI, and RESTful standards.

---

• Try: The no-charge Rational Service Tester for SOA Quality helps quality assurance professionals validate web service based SOA application..
• Article: See the whats new with Rational Service Tester for SOA Quality, and its Generic Service Client, which provides a single client to interact with any SOA service type.
• Tutorial: Get hands-on experience with this Transport for SOAP feature tutorial using Rational Tester for SOA Quality.
• Buy: Rational Service Tester for SOA Quality

Dig deeper into SOA and Web services on developerWorks

Discover knowledge paths

Skill-building guides for Linux, open source, cloud, Java, business analytics, and more.

Special offers