Getting Started with Metro

These series of articles require the following software to be installed on your system:

The following steps are required only if using Apache Tomcat as a web container (Glassfish v3 already contains Metro libraries): Unzip downloaded Metro Standalone Bundle and copy all .jar files from the lib/ directory into <tomcat-install-directory>/endorsed (where <tomcat-install-directory> points to your Apache Tomcat installation directory). Also put a copy of the servlet-api.jar library (<tomcat-install-directory>/lib) into endorsed/ libs.

The Java code and configuration files for the examples used in this document presume that the web container is listening on port 8080. Port 8080 is the default "listen" port for both GlassFish (domain1) and Tomcat. If you have changed the "listen" port, you will need to edit the example source files to account for that. The following is a list of the files which contain references to the "listen" port:

Before building and deploying the web service and its client, the home directory of the web container must be set either as an environment variable or as a property in the respective build.xml file.

One way to create a web service application is to start by coding the endpoint in Java. If you are developing your Java web service from scratch or have an existing Java class you wish to expose as a web service, this is the most direct path.

The web service is written as a normal Java class. Then the class and its methods that are to be exposed are annotated with specific web service annotations, @WebService and @WebMethod. The following code snippet shows an example:

@WebService
public class AddNumbersImpl {
    @WebMethod
    public int addNumbers(int a, int b) throws AddNumbersException {
        if (a < 0 || b < 0) {
            throw new AddNumbersException("Negative number cant be added!",
                    "Numbers: " + a + ", " + b);
        }
        return a + b;
    }
}

If you are using GlassFish, the web service in the wsit-jaxws-fromjava example can be compiled and bundled simply by invoking:

ant server

If using Tomcat, the command-line would be:

ant -Duse.tomcat=true server

The server target in build.xml in turn invokes the tools necessary to process the annotations and compile the sources, and to bundle the Java class files and configuration files into a deployable web archive (WAR file). The WAR file will be build/war/wsit-jaxws-fromjava.war. The tools that were called by ant during this step are briefly described next.

The JAX-WS tool apt (annotation processing tool) processes the annotated source code and invokes the compiler itself, resulting in the class files for each of the Java source files. In the accompanying fromjava example, the ant target build-server-java in build.xml handles this portion of the process. Then the individual class files are bundled together along with the web service's supporting configuration files into the application's WAR file. It is this file that will be deployed to the web container in the next step. The create-war target takes care of this.

Typically, you would start from WSDL to build your web service if you want to implement a web service that is already defined either by a standard or an existing instance of the service. In either case, the WSDL already exists. The JAX-WS wsimport tool will process the existing WSDL document, either from a local copy on disk or by retrieving it from a network address. An example of manually accessing a service's WSDL using a web browser is shown below as part of the section on verifying deployment.

As in the previous example, to build the wsit-jaxws-fromwsdl service for GlassFish, you can simply invoke:

ant server

Otherwise for Tomcat use:

ant -Duse.tomcat=true server

wsimport will take the WSDL description and generate a corresponding Java interface and other supporting classes. Then the Java compiler needs to be called to compile both the user's code and the generated code. Finally, the class files are bundled together into the WAR file. The details can be seen in the wsit-jaxws-fromwsdl build.xml file as the build-server-wsdl and create-war targets.

For development purposes, it is simplest to use the "autodeploy" facility of GlassFish. To do so, copy your application's WAR file to the autodeploy directory for the domain to which you want to deploy. If you are using the default domain, domain1, set up by the GlassFish installation process, then the appropriate directory path would be <glassfish-install-home>/domains/domain1/autodeploy.

The build.xml file which accompanies this example has a deploy target for GlassFish. Invoke that target by running ant in the top-level directory of the respective examples, either fromjava or fromwsdl, as follows.

ant deploy

Tomcat also has an "autodeploy" feature. That feature can be turned off but is enabled by Tomcat’s "out of the box" configuration settings. Look in <tomcat-install-directory>/conf/server.xml for the value of "autoDeploy" if you are unsure. Assuming "autoDeploy" is enabled, then copying your application to <tomcat-install-home>/webapps is all that is necessary. Again, there is a target in the ant build.xml file which accompanies this sample. The deploy target can be invoked by running the following command in the example's top-level directory.

ant -Duse.tomcat=true deploy

One basic test to verify that the application has deployed properly is to use a web browser to retrieve the application's WSDL from its hosting web container. The following URLs would retrieve the WSDL from each of the two example services. If you are running your web browser and web container on different machines, you will need to replace "localhost" with the name of the machine hosting your web service. It is also worth ensuring that your web container is actually running at this point.

If the browser displays a pageful of XML, things are working. If not, check the web container logs for any error messages related to the the sample WAR you have just deployed. For GlassFish, the appropriate log can be found at <glassfish-install-directory>/domains/<your-domain>/logs/server.log. For Tomcat, the appropriate log file will be <tomcat-install-directory>/logs/catalina.out.

The asadmin command provides the simplest method of undeploying a web service from GlassFish.

asadmin undeploy --user admin wsit-jaxws-fromjava
asadmin undeploy --user admin wsit-jaxws-fromwsdl

Undeploying a given web service from Tomcat requires deleting its WAR file from the Tomcat webapps directory. For a typical UNIX scenario the commands below would delete the sample WAR files. Tomcat then automatically undeploys the web service within a few seconds.

rm $CATALINA_HOME/webapps/wsit-jaxws-fromjava.war
rm $CATALINA_HOME/webapps/wsit-jaxws-fromwsdl.war

When developing a web service from scratch or based on an existing Java class, WSIT features are enabled using a configuration file. That file, wsit-fromjava.server.AddNumberImpl.xml, is written in WSDL format. An example configuration file can be found in the accompanying samples:

The configuration file settings will be incorporated dynamically by the WSIT run-time into the WSDL it generates for the web service. So when a client requests the service's WSDL, the run-time will embed into the WSDL any publically visible policy assertions contained in the configuration file. For the example link above, the Addressing and Reliable Messsaging assertions would be part of the WSDL as seen by the client.

When developing a web service starting from an existing WSDL, the situation is actually simpler. The policy assertions needed to enable various WSIT technologies will already be embedded in the WSDL document. Here is an example WSDL document in the accompanying samples:

asadmin undeploy --user admin wsit-enabled-fromjava
asadmin undeploy --user admin wsit-enabled-fromwsdl

rm $CATALINA_HOME/webapps/wsit-enabled-fromjava.war
rm $CATALINA_HOME/webapps/wsit-enabled-fromwsdl.war