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.
Theaction attribute of the form element in our HTML source is interpreted with the document at the path in the URI as the source, and thetemplate-xslt argument is interpreted as the XSL transform to use for generating the new document.Listing 2: XSLT transform to turn HTTP POST data into a new XML document
The first thing to note is the group of parameters such astitle andcreator. 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 theftext: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:
To try this yourself, first create an appropriate container and grand universal read access to it:Listing 3a
Then create a simple dummy document (just "<null/>") as the HTTP POST target. For example:Listing 3b
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:Listing 3c
Now create the submission response document as follows:Listing 3d
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.Listing 3e
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.
Software on a Rope
Listing 4 is a simple Python command-line program that adds a software entry file using the direct SOAP API. Note the special encoding stylehttp://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.Listing 4: A Python Program to Send a SOAP Request According to the Core API
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 theSoftRepoSoapHandler 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 theAddEntry 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.Listing 6a
You also need to add a line to the PythonServer or ApacheServer configuration stanza referring to the new handler we set up:Listing 6b
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.Listing 7: An example client to the software repository
blog comments powered by Disqus