## Samples

This document explains the samples that are bundled along with Metro. The samples included with Metro that is distributed on Java.net documents how to use Metro in a non-JavaEE 5 servlet container. This means that you can these Metro sample applications in any servlet container that has been enabled with Metro. Applications that use the proprietary deployment and servlet will run in a Metro-enabled JavaEE 5 servlet container, but they will be non-portable. If you wish to use these Metro samples in a JavaEE container in a JavaEE portable manner you need to modify them to use the standard JavaEE 5 deployment descriptor; please refer to the JavaEE 5 or GlassFish documentation/samples.

All these samples are tested to run on Glassfish AS and on Apache Tomcat 5.x.

## 1.0 Directory Structure

This section explains the directory structure of the Metro `samples` directory in the bundle:

- `docs/` - contains Metro samples documentation, particularly `index.html` (this file)
- sample directories - please consult a nested `README` file in each sample directory for the description of the sample and specific instructions how to run the sample.

## 2.0 Prerequisites

Here is the list of prerequisites that needs to be met before any of the samples can be invoked:

1. Download Java Platform, Standard Edition 6.0 Update 20 or later. Set `JAVA_HOME` to the JavaSE 6.0 installation directory.

2. Download GlassFish Open Source Edition 3.1 or later application server and install it.

3. Make sure that the Application Server is configured for port `8080` (which is the default HTTP port for a Glassfish installation) as samples hard-coded with this port info. Should you want to use different port instead, you need to manually update samples to use the correct port.

4. Set up the environment,

   1. Set `AS_HOME` to point to the Application Server installation directory.

   2. Set `METRO_HOME` to the Metro installation directory.

5. GlassFish Open Source Edition 3.1 integrates Metro 2.1. So you may just start using it and skip step 6 below unless you want to use the latest Metro build.

6. If you have downloaded a standalone Metro bundle,

   1. refer to the `readme.html` in `$METRO_HOME` for information how to install standalone Metro on an application server or a servlet container.

## 3.0 Invoking the sample

Each sample can be built, deployed and invoked using the `$ANT_HOME/bin/ant` and `build.xml` ant script in the root directory of the sample. Each ant script supports the following set of targets:

server | Builds and deploy the service endpoint WAR
client | Builds the client
run | Runs the client

Some samples(e.g. fromjava, supplychain) can be built, deployed using `jakarta.xml.ws.Endpoint` API. These samples support extra targets:

server-j2se | Builds and deploys the Endpoint API based service endpoint(doesn't terminate until server-j2se-stop is called)
server-j2se-stop | Stops the Endpoint API based service endpoint(need to run from a different window)

It is essential for the service endpoint to be deployed on an Application Server before clients can be built because clients use the WSDL exposed from the service endpoint deployed in the Application Server. So please make sure that your Application Server is either running before the `server` target is invoked or run it after the `server` target is invoked. You will have to wait a few minutes for the Application Server to deploy the service endpoint correctly before building the client.

Running Samples with Tomcat:

1. Set up the environment,

   1. Set `CATALINA_HOME` to your Tomcat installation..

   2. Set `METRO_HOME` to the Metro installation directory.

2. Make sure that the Tomcat is configured for port `8080` as samples hard-coded with this port info. Should you want to use different port instead, you need to manually update samples to use the correct port.

3. If you have downloaded a standalone Metro bundle,

   1. refer to the `readme.html` in `$METRO_HOME` for information how to install standalone Metro on an application server or a servlet container.

4. Make sure the Tomcat container is up and running before running sample.

5. While running the ant targets in samples, specify “-Dtomcat=true”. For example:

   `ant clean server -Dtomcat=true`, this will build the service and deploy the war to /webapps.

   `ant clean client`, this would create client-side artifacts and compiles the files.

   `ant run`

We appreciate your feedback, please send it to metro@javaee.groups.io.