MoSeS - Deployment

Once you have registered your data types, namespaces and your services, once you generated their datatypes and skeletons, and finally once you implemented business logic of the new services, it is time to make them visible as web services. This last step is usually called service deployment. Deploying a service (in Java world) means usually two things: Also, there are two kinds of deployments: Before going to details how to deploy your services, note that Moses BaseCmdLineClient gives you an opportunity to fully test your implementation before you deploy it. The recommended pattern here is to test your service as much as you can - and only then to deploy them.

Also note that there is no harm to deploy the same service several times.

Deployment properties

The deployment is an Ant target (task) - so everything is driven by Ant properties. As usual, the properties can be specified in (at least) three ways:

Here is a list of properties that are used by both, local and remote deployment. Other, specific properties, are described later, in their particular sections.

users.lib.dir = <directory-name>
This property defines a directory with your own implementation. In most cases, you are not using jMoby directory for development of your classes - but you have them somewhere separately, in their own Java packages.

The Moses deployment will take all .jar files from this directory and copies them to the Tomcat (either directly or indirectly as described later in local and remote deployment).

users.lib.file = <fully-qualified-jar-file-name>
This property defines just one .jar file with your implementation. Otherwise, it is used in the same way as the property users.lib.dir described above. Actually, both these properties can be used in the same time, and contents of both are copied to Tomcat.
service.<your-service-name> = <your-class-name-implementing-this-service>
This is probably the most important property in the Moses deployment. You can have more such properties, one for each service you are going to deploy. For example, using the names of services introduced in other Moses documents:
service.Mabuhay = org.jmoby.tutorial.service.MabuhayImpl
service.HelloBiomobyWorld = org.jmoby.tutorial.service.HelloBiomobyWorldImpl
At least one such property must be found, otherwise Ant will complain and stop.

Later, you will see that the same properties are used to define what services should be un-deployed. In that case, the implementation class part can be missing (property has just a name but no value).

services.list = <comma-separated list of service names>
This is an optional property that can limit the list of service names given by service.NAME properties. Note that it is not enough just to use this property and to forget to specify separate property service.NAME for each service.

Use this property if you have a larger list of your services (probably kept in which you do not wish to touch, and you want to deploy only some of them now.

The property contains a name of a service, or a comma-separated list of service names. For example:

services.list = Mabuhay
services.list = Mabuhay,HelloBiomobyWorld
For an un-deployment of services, this property is enough (you do not need to have separate properties service.NAME).

Local deployment

Local deployment means to move files to local server, and to call a program provided by Axis toolkit to configure Axis in order to know about new services. Properties for that, therefore, define where is your server, and where is Axis installed within this server.

server.home = <your-server-directory>
Where your server is installed (e.g. /usr/local/tomcat or /usr/local/jboss). Note that moving things there will require a write access to some directories in the server directory, especially to directory where Axis has its libraries (which is, by default, <server-home>/<axis-home>/WEB-INF/lib).

If you have installed Axis in the server in a standard place, and if your server listens on a standard port, this is the only property you need to specify.

axis.relative.path = <directory-with-Axis-in-server>
Where is Axis installed in the server. Put here a path starting in <server-home>/ (but excluding this beginning). Default value is webapps/axis as for Tomcat (for JBoss the default value is server/default/deploy/axis.war). = <server-computer-name>
A machine name where the server is installed. Default is localhost. This is used by the Axis program when deploying new services. If it is not a localhost then it is called remote administration and Axis User's Guide tells about it:
Note that by default, the Axis server is configured to only accept administration requests from the machine on which it resides - if you wish to enable remote administration, you must set the enableRemoteAdmin property of the AdminService to true. To do this, find the server-config.wsdd file in your webapp's WEB-INF directory. In it, you'll see a deployment for the AdminService. Add an option as follows:
<service name="AdminService" provider="java:MSG">
  <parameter name="className" value="org.apache.axis.util.Admin"/>
  <parameter name="allowedMethods" value="*"/>
<parameter name="enableRemoteAdmin" value="true"/>
server.port = <server-port-number>
A port where the server is listening. Default value is 8080.
axis.admin.url = <URL-path>
Used to find a correct piece of Axis when deploying services. Very rarely needed to be changed. Default value (which depends on a property defined above) is axis/servlet/AxisServlet. You can check this by typing in http://<server.home>:<server.port>/<axis.admin.url> in your browser.
wsdd.template = <filename-with-wsdd-template>
Deployment of a service uses a template that defines how to deploy the service. A standard template is in file src/webapps/standard.wsdd.template. Mostly you do not need to change it, but there may be situations where you need to provide your own template. For example, if you need to use special Axis chains and Axis handlers (don't worry if you do not know what they are).

How to deploy locally

Having set all properties shown above, you just type:
ant deploy-services
After that, restart your server (because new classes where added there).

How to un-deploy local services

ant undeploy-services
It removes Axis configuration of your services but it does not clean up server/Axis lib directory. That would be a more complex task...

Remote deployment

A remote deployment does not need any server running on your machine. It creates a local file (slightly fat, because it includes both Axis and Ant libraries) which you will then move (by ftp, for example) to a real machine where you have a server running and where you want to have your services deployed.

In order to make easy to use the resulting file on a target machine, you still need to set server and Axis properties before creating this file here. By default, the same properties are used as for local server:

server.home = <your-server-directory>
axis.relative.path = <directory-with-Axis-in-server> = <server-computer-name>
wsdd.template = <filename-with-wsdd-template>
server.port = <server-port-number>
axis.admin.url = <URL-path>
But you can also set them using different names (so you can have both set to different values if you deploy sometimes locally and sometimes for a remote machine). The alternative names start with cross:
cross.server.home = <your-server-directory>
cross.axis.relative.path = <directory-with-Axis-in-server> = <server-computer-name>
cross.server.port = <server-port-number>
cross.axis.admin.url = <URL-path>
And, of course, you still have to say which services you want to deploy - see the beginning of this document.

How to deploy for a remote machine

Having set all (or some) properties shown above, you just type:
ant deploy-remote
Then move the created file to a target machine, and log it there. Untar there the file - it creates directory moby-services-to-deploy-<date>. Change to this directory and type:
sh deploy
And again, restarting the server is often a good idea.

If you want first to see if your properties were specified correctly, try first:

sh deploy info

How to un-deploy on a remote machine

You can use the same directory for un-deploying services by calling:
sh deploy undeploy

Martin Senger
Last modified: Thu Feb 14 15:01:03 2008