O'Reilly logo

Java SOA Cookbook by Eben Hewitt

Stay ahead with the world's most comprehensive technology and business learning platform.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, tutorials, and more.

Start Free Trial

No credit card required

Installing Metro


You want to use the latest Java APIs available to make it easier to develop interoperable web services.


Install Metro. Metro is hosted at https://metro.dev.java.net as a free and open source project.


Metro 1.0.1 is included with Glassfish 9.1 update 1. The JAX-WS Reference Implementation, available within Java SE 6 and Glassfish, provides a rich set of APIs for producing and consuming web services, including WS-Addressing and MTOM capabilities. Metro extends the capabilities of this basic platform but without vendor lock-in.


WSIT, or Web Services Interoperability Technology, is what ensures that JAX-WS applications interoperate with web services and clients from other platforms that conform to the Basic Profile 1.1. WSIT is bundled with JAX-WS 2.1, as included in Glassfish. The WSIT technology is not based on any JSR, and as such is not available as a plug-in for other application servers. Other vendors, such as Oracle WebLogic 10.3, offer roughly equivalent technology, however. In fact, Oracle’s WebLogic implementation uses considerable code from the Glassfish and Metro open source projects.

Think of Metro as two basic layers. The core layer gives you the JAX-WS RI, and implementations of key web services specifications to promote interoperability: WS-I Basic Profile, WS-I Attachments Profile, and WS-Addressing. WS-IT, or Web Services Interoperability Technology, provides interoperability with the .NET 3.0 and 3.5 web services platform on Windows. If you download only Glassfish and not the separate Metro 1.1, you get these features.

The second layer of Metro offers advanced features in four categories: Transports, Reliability, Security, and Transactions, as highlighted in Table 4-1.

Table 4-1. Metro capabilities

Metro capabilityKey features implemented
TransportsSOAP over TCP with FastInfoset, JMS and SMTP transports, MTOM and XOP for optimized binary encoding
ReliabilityWS-ReliableMessaging implementation
SecurityWS-Security and WS-Trust
TransactionsOffers transactional support for web services and implements WS-Coordination and WS-Atomic Transactions

JAX-WS relies on JAXB (Java API for XML Binding) to provide a translation or mapping layer between XML and Java.


WS-Addressing abstracts the physical location of a web service resource for looser coupling. MTOM (Message Transmission Optimization Mechanism) optimizes the transmission of binary data within SOAP messages.

While Metro is available as a separate download that can work in conjunction with other containers such as WebLogic 10.3, it is generally considered as the Sun web services stack, as shown in Figure 4-5.

Metro: the Java web services stack

Figure 4-5. Metro: the Java web services stack

In addition to implementing these important specifications, Metro also provides certain conveniences. For example, it offers a single annotation that allows you to perform schema validation against incoming and outgoing message payloads. Metro gives you support for REST via the Jersey project, as well as Spring and JSON (JavaScript Object Notation) integration.

Here’s how to get Metro:

  1. Download the most recent stable build from https://metro.dev.java.net.

  2. In a console, navigate to the directory you downloaded it to.

  3. Execute > java -jar metro-installer.jar. Agree to the license. The installer will expand a directory containing a variety of samples and documentation, as well as a few JARs in the lib directory.

  4. Navigate to the directory the installer created and run the appropriate Ant script for your platform. First, get the location of your Glassfish home and set that variable on the command. Run wsit-on-glassfish.xml as follows:

    > ant -Denv.AS_HOME=C:\\programs/glassfishv2ur1 -f wsit-on-glassfish.xml

You should see that some files were copied and the installation was successful. After restart, the latest version of Metro should now be available for your Glassfish domains.


Metro comes with some tools that are newer versions of the ones that come with the JDK, and some of these are also in Glassfish. For example, the wsimport tool that comes with Java SE 1.6.0_05 is version 2.1.1. However, invoking > wsimport -version from within the <glassfish-home>/bin directory shows “JAX-WS RI 2.1.3-hudson-390-” after installing Metro. It’s important to keep your paths straight while using these tools!

This solution assumes that you already have a recent version of Glassfish running locally. It is available at https://glassfish.dev.java.net. Glassfish 9.1 update 1, Metro 1.3, and JDK 1.6.0_05 were used to test the examples I’ve written for this book. If you do not want to use Glassfish, Metro also works with Tomcat, JBoss, and WebLogic.

Using Metro 1.3 in Maven

Here are the dependencies to add to your pom.xml if you are using Maven 2 to build your web service and you want to use extra features in Metro:


With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, interactive tutorials, and more.

Start Free Trial

No credit card required