Deploying Soaplab2 services

It sounds easy and obvious - but it never is. Soaplab2 tries hard, hopefully, to make it easy at least for the default cases.

Supported protocols for Soaplab2 services

The Soaplab2 architecture is flexible enough to allow several protocols. At the moment, the main protocol is the SOAP protocol, using the document/literal flavour. It is one of the three [sic] standarised flavours. This protocol is also well supported in Java, up to the point that the toolkit is now part of the Java 1.6. (Unfortunately, it is much less supported in other languages, yet.)

Reflecting the name of the Java toolkit (JAX-WS), we are referring to this protocol as a jax or jaxws protocol. It is a default one for deploying Soaplab2 services.

Mainly because of the backward compatibility with the previous versions of Soaplab (more about it in the compatibility guide), Soaplab2 also supports the SOAP protocol, using the rpc/encoded flavour. Again reflecting the major Java toolkit for this flavour, we refer to is as axis1 protocol.

It makes also possible to use Soaplab2 features (like calling external processes, or fetching and screen scraping remote web pages) within another Java project - Soaplab2 is just another library used there.

We refer to this last protocol as the local protocol.

Deploying Soaplab2 services

Deployment Ant's tasks

Summarizing, what has to be done before calling any deployment task:

• Create service metadata in XML format. The metadata are supposed to be created in the metadata/generated directory (that is the place where the deployment tasks will be looking for them).

• A part of generated metadata is also one or more application list files. They contain a list of your services (with few other details). These files must be listed in the soaplab.properties configuration file (as a property applist). There may be other properties that you wish to set differently from the default. Check the configuration guide.

• Check if your build.properties file has the property tomcat.home, pointing to the location where your Tomcat is installed. Otherwise deployment task cannot copy there any files.

  The same file build.properties could also have the property tomcat.host (with a host name under which your Tomcat is visible to the outside world).

Ant tasks: jaxdeploy, axis1deploy

The main question is What services are being deployed?.

The answer is: all services whose names are listed in the application list files included in the applist property (or properties) in the soaplab.properties file.

The soaplab.properties is created either from the src/etc/config/soaplab.properties.template file or from your own file defined by the my.soaplab.properties property.

It sounds complicated and it may be so (even though I prefer to call it rather flexible). But the good news is that it becomes complicated and flexible only when you start to apply your own wishes. Using defaults is simple:

• You create your ACD files in the src/etc/acd/sowa or src/etc/acd/gowlab directories, and generate XML by calling

  ant gen
  

  (as explained in the metadata guide).

• Then you call

  ant jaxdeploy
  

  (or ant axis1deploy, depending of the protocol of your choice).

And that's it.

Let's continue now with the optional customisation. There are few build-time properties that can influence what and how is deployed:

context.name

The deployment task takes your services and copy all necessary files to the <tomcat-home>/webapps directory, under the name either soaplab2 (for the jaxws protocol) or soaplab2-axis (for the axis1 protocol). The name (called a context name) is important because it will become part of the URL of your services. By default, your services will be accessible as:

http://url.of.your.tomcat/soaplab2/services

or as:

http://url.of.your.tomcat/soaplab2-axis/services

But you can customise it by using this property. The property value is used as a new context name for the jaxws protocol, and with appended suffix -axis for the axis1 protocol. If you do not like the suffix, you can specify the whole context name for the axis1 protocol by using another, more specific, property axis1.context.name.

server.log4j.configuration

This property points to your own configuration file that will be used by Soaplab services when deployed. This is a similar property as the log4j.configuration that is used with the local protocol.

server.log.dir

This property does not replace the whole logging configuration file (as the previous one) but it changes only the location of the log file. By default, there are two log files, soaplab2.log and soaplab2-others.log, both created in the <tomcat-home>/logs directory. This property can change it.

server.metadata.dir

Soaplab2 services read their metadata in the run-time. By default, all metadata are copied (as a part of deployment) to the directory <tomcat-home>/webapps/soaplab2/metadata. Which is usually fine and it makes the Soaplab2 war file self-contained. Everything sits nicely inside the Tomcat container.

But there may be situations that you prefer to have easier access to the metadata even after services have been deployed. Typical case will be un-deploying services on-the-fly (dynamically, without restarting Tomcat).

Therefore, you can define that services should look for their metadata elsewhere. And it is done by this property. Typically, you point this property to the original place where the metadata have been generated into. This is an example from my build.properties file (the example includes also similar properties, described below):

# deployment - to use project root directory and not the "embedded"
# files in the Tomcat
server.metadata.dir = /home/senger/soaplab2/metadata/generated
server.runtime.dir  = /home/senger/soaplab2/_R_
server.scripts.dir  = /home/senger/soaplab2/run

server.runtime.dir

Soaplab2 services need some space in the file system to keep inputs and results. By default, this space is located in the <tomcat-home>/temp directory.

Again, the default place is good because everything is self-contained within Tomcat space. This is especially useful when you do not have easy or direct access to your Tomcat (for example, if you are using the Tomcat manager to upload a Soaplab2 war file there).

But sometimes you need to use a different place (for example because of Tomcat's disk limitations). Use this property to point to a different directory.

server.scripts.dir

Soaplab2 services run (usually) external programs. This was, after all, the main original reason for making Soaplab. You have to assure that they can find them. In order to do that, you can use the run-time property addtopath.dir (see the configuration guide).

Or, you can put the program executable (usually a script) in the directory specified by this property. By default, the deployment task copies the whole contents of the run directory into <tomcat-home>/webapps/soaplab2/WEB-INF/run directory. The directory name is then put in the property scripts.dir, which is (again by default) used in the addtopath.dir (so the services will look there for the external programs/scripts).

user.lib.dir

user.lib.include

These properties are important for developers adding new plug-ins to the core Soaplab2. If they have a new code to be used by Soaplab2, they have to tell, of course, the deployment task where the code is. And this is the role of these properties.

The property user.lib.dir does not have any default value. If it is defined, however, then it points to a directory where all files matching the pattern given by the property user.lib.include are copied from. The default value for the property user.lib.include is *.jar.

The same properties, by the way, work also for the config task when the run-time scripts are being created in the build/run directory.

And there are couple of properties influencing the look & feel of the Spinet web client. Look at them in a separate section.

Ant tasks: jaxdist, axis1dist

It is a separate task because sometimes you can use so-called hot deployment where the servlet container can be pointed to other place to find its classes and other files. It is handy specially in the development time. Useful for Eclipse Web Tool plug-in .

Ant tasks: jaxwar, axis1war

It is a separate task because sometimes you do not have an access to the Tomcat when you are deploying your services. Perhaps Tomcat is running on a different machine than you are building Soaplab2 services. Or, Tomcat is accessible only by the Tomcat manager that accepts war file by uploading them.

The name of the war file is created from the property context.name as described above. It is placed in the build/dist directory.

Ant tasks: jaxdeployx, axis1deployx

tomcat.manager.username

tomcat.manager.password

tomcat.manager.url

How to configure your own web.xml

jaxws.web.xml.template

jaxws.xml.template

axis1.web.xml.template

First of all, you can have your own whole templates. These properties define their locations. Caveat lecture!

The properties names reflect different protocols.

web.display.name

This property specifies the Web Application display name, a short name that can be displayed by GUI tools for servlet container (such as the Tomcat Manager). Default value is: Soaplab Web Services.

web.display.desc

This property provides a descriptive text about the Web Application (again, used by GUI tools, such as Tomcat Manager). The default value is: The project home page is http://soaplab.sourceforge.net/soaplab2/.

url.pattern.for.list

url.pattern.for.others

These two properties are only for jaxws protocol. They define patterns that - when found in the requesting URL - redirect request to the Soaplab2 services. The property url.pattern.for.list is a URL pattern for the Soaplab2 service providing list of all individual Soaplab2 services, and the url.pattern.for.others defines a pattern for individual services.

In other words, these properties define the URLs to access Soaplab2 services (they are not the only ones, other parts of the URLs are defined by the context.name and your Tomcat host name and port number).

It is probably easier to show where these properties are used. This is a part of the web.xml template file (the tokens in upper-cases will be replaced by values of your properties:

<!-- Soaplab2 List service -->
<servlet-mapping>
  <servlet-name>soaplab2</servlet-name>
  <url-pattern>@URL_FOR_LIST@</url-pattern>
</servlet-mapping>

<!-- Soaplab2 all other services -->
<servlet-mapping>
  <servlet-name>soaplab2</servlet-name>
  <url-pattern>@URL_FOR_OTHERS@</url-pattern>
</servlet-mapping>

The default values are /services/list for the list service and /services/* for the individual services.

Un-deploying Soaplab2 services

Such services will still finish their currently running jobs, and may even return their results (it depends on how long they were running and how are the run-time properties jobs.cleaning.interval and services.cleaning.interval set), but they will not be able to start new jobs.