Metro 2.3-b05 User Guide

Bootstrapping and configuration consists of using a URL to access a web service, retrieving its WSDL file, and using the WSDL file to create a web service client that can access and consume a web service. The process consists of the following steps, which are shown in Bootstrapping and Configuration.

Figure 1.2. Bootstrapping and Configuration

Bootstrapping and Configuration explains how to bootstrap and configure a web service client and a web service endpoint that use the Metro's WSIT technologies.

A primary function of web services applications is to share data among applications over the Internet. The data shared can vary in format and include large binary payloads, such as documents, images, music files, and so on. When large binary objects are encoded into XML format for inclusion in SOAP messages, even larger files are produced. When a web service processes and transmits these large files over the network, the performance of the web service application and the network are negatively affected. In the worst case scenario the effects are as follows:

One way to deal with this problem is to encode the binary objects so as to optimize both the SOAP application processing time and the bandwidth required to transmit the SOAP message over the network. In short, XML needs to be optimized for web services. This is the exactly what the Message Optimization technology does. It ensures that web services messages are transmitted over the Internet in the most efficient manner.

Sun recommends that you use message optimization if your web service client or web service endpoint will be required to process binary encoded XML documents larger than 1KB.

For instructions on how to use the Message Optimization technology, see Message Optimization.

Reliable Messaging is a Quality of Service (QoS) technology for building more reliable web services. Reliability (in terms of what is provided by WS-ReliableMessaging) is measured by a system's ability to deliver messages from point A to point B. The primary purpose of Reliable Messaging is to ensure the delivery of application messages to web service endpoints.

The reliable messaging technology ensures that messages in a given message sequence are delivered at least once and not more than once and optionally in the correct order. When messages in a given sequence are lost in transit or delivered out of order, this technology enables systems to recover from such failures. If a message is lost in transit, the sending system retransmits the message until its receipt is acknowledged by the receiving system. If messages are received out of order, the receiving system may re-order the messages into the correct order.

You should consider using reliable messaging if the web service is experiencing the following types of problems:

To help decide whether or not to use reliable messaging, weigh the following advantages and disadvantages:

For instructions on how to use the Reliable Messaging technology, see Using Reliable Messaging.

Until now, web services have relied on transport-based security such as SSL to provide point-to-point security. Metro implements WS-Security so as to provide interoperable message content integrity and confidentiality, even when messages pass through intermediary nodes before reaching their destination endpoint. WS-Security as provided by Metro is in addition to existing transport-level security, which may still be used.

Metro also enhances security by implementing WS-Secure Conversation, which enables a consumer and provider to establish a shared security context when a multiple-message-exchange sequence is first initiated. Subsequent messages use derived session keys that increase the overall security while reducing the security processing overhead for each message.

Further, Metro implements two additional features to improve security in web services:

Metro implements these features in such a way as to ensure that web service binding security requirements, as defined in the WSDL file, can interoperate with and be consumed by Metro and WCF endpoints.

For instructions on how to use the WS-Security technology, see Using WSIT Security.

Bootstrapping and configuring involves a client getting a web service URL (perhaps from a service registry) and obtaining the information needed to build a web services client that is capable of accessing and consuming a web service over the Internet. This information is usually obtained from a WSDL file. Bootstrapping and Configuration Specifications shows the specifications that were implemented to support bootstrapping and configuration.

Figure 1.3. Bootstrapping and Configuration Specifications

In addition to the Core XML specifications, bootstrapping and configuration was implemented using the following specifications:

Message optimization is the process of transmitting web services messages in the most efficient manner. It is achieved in web services communication by encoding messages prior to transmission and then de-encoding them when they reach their final destination.

Message Optimization Specifications shows the specifications that were implemented to optimize communication between two web service endpoints.

Figure 1.4. Message Optimization Specifications

In addition to the Core XML specifications, optimization was implemented using the following specifications:

Reliability (in terms of WS-ReliableMessaging) is measured by a system's ability to deliver messages from point A to point B regardless of network errors. Reliable Messaging Specifications shows the specifications that were implemented to ensure reliable delivery of messages between two web services endpoints.

Figure 1.5. Reliable Messaging Specifications

In addition to the Core XML specifications and supporting standards (Web Services Security and Web Services Policy, which are required building blocks), the reliability feature is implemented using the following specifications:

Web Services Security Specifications shows the specifications implemented to secure communication between two web service endpoints and across intermediate endpoints.

Figure 1.6. Web Services Security Specifications

In addition to the Core XML specifications, the security feature is implemented using the following specifications:

Message optimization ensures that web services messages are transmitted over the Internet in the most efficient manner. Because XML is a textual format, binary files must be represented using character sequences before they can be embedded in an XML document. A popular encoding that permits this embedding is known as base64 encoding, which corresponds to the XML Schema data type xsd:base64Binary. In a web services toolkit that supports a binding framework, a value of this type must be encoded before transmission and decoded before binding. The encoding and decoding process is expensive and the costs increase linearly as the size of the binary object increases.

Message optimization enables web service endpoints to identify large binary message payloads, remove the message payloads from the body of the SOAP message, encode the message payloads using an efficient encoding mechanism (effectively reducing the size of the payloads), re-insert the message payloads into the SOAP message as attachments (the file is linked to the SOAP message body by means of an Include tag). Thus, message optimization is achieved by encoding binary objects prior to transmission and then de-encoding them when they reach there final destination.

The optimization process is really quite simple. To effect optimized message transmissions, the sending endpoint checks the body of the SOAP message for XML encoded binary objects that exceed a predetermined size and encodes those objects for efficient transmission over the Internet.

SOAP MTOM, paired with the XML-binary Optimized Packaging (XOP), addresses the inefficiencies related to the transmission of binary data in SOAP documents. Using MTOM and XOP, XML messages are dissected in order to transmit binary files as MIME attachments in a way that is transparent to the application. This transformation is restricted to base64 content in canonical form as defined in XSD Datatypes as specified in XML Schema Part 2: Datatypes Second Edition, W3C Recommendation 28 October 2004.

Thus, the Metro technology achieves message optimization through an implementation of the MTOM and XOP specifications. With the message optimization feature enabled, small binary objects are sent in-line in the SOAP body. For large binary objects, this becomes quite inefficient, so the binary object is separated from the SOAP body, encoded, sent as an attachment to the SOAP message, and decoded when it reaches its destination endpoint.

When reliable messaging is enabled, messages are grouped into sequences, which are defined by the client's proxies. Each proxy corresponds to a message sequence, which consists of all of the request messages for that proxy. Each message contains a sequence header. The header includes a sequence identifier that identifies the sequence and a unique message number that indicates the order of the message in the sequence. The web service endpoint uses the sequence header information to group the messages and, if the Ordered Delivery option is selected, to process them in the proper order. Additionally, if secure conversation is enabled, each message sequence is assigned its own security context token. The security context token is used to sign the handshake messages that initialize communication between two web service endpoints and subsequent application messages.

Thus, using the Reliable Messaging technology, web service endpoints collaborate to determine which messages in a particular application message sequence arrived at the destination endpoint and which messages require resending. The reliable messaging protocol requires that the destination endpoint return message-receipt acknowledgements that include the sequence identifier and the message number of each message received. If the source determines that a message was not received by the destination, it resends the message and requests an acknowledgement. Once the source has sent all messages for a given sequence and their receipt has been acknowledged by the destination, the source terminates the sequence.

The web service destination endpoint in turn sends the application messages along to the application. If ordered delivery is configured (optional), the destination endpoint reconstructs a complete stream of messages for each sequence in the exact order in which the messages were sent and sends them along to the destination application. Thus, through the use of the reliable messaging protocol, the destination endpoint is able to provide the following delivery assurances to the web service application:

Application Message Exchange Without Reliable Messaging shows a simplified view of client and web service application message exchanges when the Reliable Messaging protocol is not used.

Figure 1.7. Application Message Exchange Without Reliable Messaging

When the Reliable Messaging protocol is not used, application messages flow over the HTTP connection with no delivery assurances. If messages are lost in transit or delivered out of order, the communicating endpoints have no way of knowing.

Application Message Exchange with Reliable Messaging Enabled shows a simplified view of client and web service application message exchanges when reliable messaging is enabled.

Figure 1.8. Application Message Exchange with Reliable Messaging Enabled

With reliable messaging enabled, the Reliable Messaging source module is plugged into the Metro web service client. The source module transmits the application messages and keeps copies of the messages until their receipt is acknowledged by the destination module through the exchange of protocol messages. The destination module acknowledges messages and optionally buffers them for ordered-delivery guarantee. After guaranteeing order, if configured, the destination module allows the messages to proceed through the Metro dispatch for delivery to the endpoint or application destination.

The following sections describe how the Metro security technologies, security policy, trust, and secure conversation work.

1.5.3.1. How Security Policy Works

The Metro Web Service Security Policy implementation builds on the features provided by the Web Service Policy implementation in Metro. It enables users to use XML elements to specify the security requirements of a web service endpoint, that is, how messages are secured on the communication path between the client and the web service. The web service endpoint specifies the security requirements to the client as assertions (see Security Policy Exchange).

Figure 1.9. Security Policy Exchange

The security policy model uses the policy specified in the WSDL file for associating policy assertions with web service communication. As a result, whenever possible, the security policy assertions do not use parameters or attributes. This enables first-level, QName-based assertion matching to be done at the framework level without security domain-specific knowledge. The first-level matching provides a narrowed set of policy alternatives that are shared by the client and web service endpoint when they attempt to establish a secure communication path.

Note

A QName is a qualified name, as specified by the XML Schema Part2: Datatypes specification, Namespaces in XML, and Namespaces in XML Errata. A qualified name is made up of a namespace URI, a local part, and a prefix.

The benefit of representing security requirements as assertions is that QName matching is sufficient to find common security alternatives and that many aspects of security can be factored out and reused. For example, it may be common that the security mechanism is constant for a web service endpoint, but that the message parts that are protected, or secured, may vary by message action.

The following types of assertions are supported:

• Protection assertions: Define the scope of security protection. These assertions identify the message parts that are to be protected and how they are to be protected, that is, whether data integrity and confidentiality mechanisms are to be used.

• Conditional assertions: Define general aspects or preconditions of the security. These assertions define the relationships within and the characteristics of the environment in which security is being applied, such as the tokens that can be used, which tokens are for integrity or confidentiality protection, applicable algorithms to use, and so on.

• Security binding assertions: Define the security mechanism that is used to provide security. These assertions are a logical grouping that defines how the conditional assertions are used to protect the indicated message parts. For example, the assertions might specify that an asymmetric token is to be used with a digital signature to provide integrity protection, and that parts are to be encrypted with a symmetric key, which is then encrypted using the public key of the recipient. In their simplest form, the security binding assertions restrict what can be placed in the wsse:Security header and the associated processing rules.

• Supporting token assertions: Define the token types and usage patterns that can be used to secure individual operations and/or parts of messages.

• Web Services Security and Trust assertions: Define the token referencing and trust options that can be used.

1.5.3.2. How Trust Works

Trust and Secure Conversation shows how the Web Services Trust technology establishes trust.

Figure 1.10. Trust and Secure Conversation

To establish trust between a client, a Security Token Service, and a web service:

1. The client establishes an HTTPS connection with the Secure Token Service using one of the following methods:

   • Username Authentication and Transport Security: The client authenticates to the Security Token Service using a username token. The Security Token Service uses a certificate to authenticate to the Client. Transport security is used for message protection.

   • Mutual Authentication: Both the client-side and server-side use X509 certificates to authenticate to each other. The client request is signed using Client's X509 certificate, then signed using ephemeral key. The web service signs the response using keys derived from the client's key.

2. The client sends a RequestSecurityToken message to the Security Token Service.

3. The Security Token Service sends a Security Assertion Markup Language (SAML) token to the Client.

4. The client uses the SAML token to authenticate itself to the web service and trust is established.

All communication uses SOAP messages.

1.5.3.3. How Secure Conversation Works

Secure Conversation shows how the Web Services Secure Conversation technology establishes a secure conversation when the Trust technology is not used.

Figure 1.11. Secure Conversation

To establish a secure conversation between a Client and a web service:

1. The client sends a X509 Certificate to authenticate itself to the web service.

2. The web service sends a X509 Certificate to authenticate itself to the client.

All communication uses SOAP messages.

Over the years, the Metro team has found the following tools to be useful for our users when working with web services.

If you want to use Metro in a Maven project, you need to declare a dependency on the Metro runtime bundle:

<project>
    ...
    <dependencies>
        ...
        <dependency>
            <groupId>org.glassfish.metro</groupId>
            <artifactId>webservices-rt</artifactId>
            <version>2.1</version>
        </dependency>
        ...
    </dependencies>
    ...
</project>

Specifying this dependency, Maven resolves all the transitive dependencies and gets all the jars that webservices-rt module depends on. Should you want to use OSGi-fied Metro bundle, you need to declare the following dependency instead:

<project>
    ...
    <dependencies>
        ...
        <dependency>
            <groupId>org.glassfish.metro</groupId>
            <artifactId>webservices-osgi</artifactId>
            <version>2.1</version>
        </dependency>
        ...
    </dependencies>
    ...
</project>

Additionally, the following entries need to be added into your project's pom.xml or into your settings.xml configuration file:

<repositories>
    ...
    <repository>
        <id>maven-repository.java.net</id>
        <name>Java.net Repository for Maven 1</name>
        <url>http://download.java.net/maven/1/</url>
        <layout>legacy</layout>
    </repository>
    <repository>
        <id>maven2-repository.java.net</id>
        <name>Java.net Repository for Maven 2</name>
        <url>http://download.java.net/maven/2/</url>
    </repository>
    ...
</repositories>

<pluginRepositories>
    ...
    <pluginRepository>
        <id>maven2-repository.java.net</id>
        <name>Java.net Repository for Maven 2</name>
        <url>http://download.java.net/maven/2/</url>
        <layout>default</layout>
    </pluginRepository>
    ...
</pluginRepositories>

Both repository and pluginRepository sections will need to be added. If you're behind a proxy, check the Maven guide to using proxies to learn about configuring proxy settings in Maven.

Even though Metro is currently Maven-based and fully available from a Maven repository, you can, of course, still use it in a non-Maven project or install it manually to your container. First, you need to go to the Metro Standalone Bundle root in the Maven repository and download and unzip a version of your choice, e.g. Metro 2.1 Standalone Bundle. For further instructions, please consult the readme.html file available under the unzipped metro root directory.

Before you create the web service, make sure GlassFish has been registered with the NetBeans IDE. The registered server list can be viewed from the Tools → Servers menu item.

The starting point for developing a web service with Metro is a Java class file annotated with the javax.jws.WebService annotation. The WebService annotation defines the class as a web service endpoint. The following Java code shows a web service. The IDE will create most of this Java code for you.

package org.me.calculator;

import javax.jws.WebService;
import javax.jws.WebMethod;
import javax.jws.WebParam;

@WebService()
public class Calculator {
    @WebMethod(action="sample_operation")
    public String operation(@WebParam(name="param_name")
            String param) {
        // implement the web service operation here
        return param;
    }

    @WebMethod(action="add")
    public int add(@WebParam(name = "i") int i,
           @WebParam(name = "j") int j) {
        int k = i + j;
        return k;
    }
}

Notice that this web service performs a very simple operation. It takes two integers, adds them, and returns the result.

Now that you have coded a web service, you can configure the web service to use Metro's WSIT technologies.

You have a possibility to choose which .NET / METRO version you want your service to be compatible with. There are two choices:

Choose the version appropriate for your web service development (Note the Metro 2.0 library provided by the latest NetBeans and GlassFish products support either version.) .NET 3.5 / METRO 1.3 is selected by default. There are several differences in between the two versions. For .NET 3.0 / METRO 1.0 documentation please follow this link: Metro 1.0 documentation.

This section describes just how to configure the Reliable Messaging. For a discussion of reliable messaging, see Using Reliable Messaging. To see how to secure the web service, see Using WSIT Security.

Now that you have configured the web service to use Metro's WSIT technologies, you can deploy and test it.

Now that you have built and tested a web service that uses Metro's WSIT technologies, you can create a client that accesses and consumes that web service. The client will use the web service's WSDL to create the functionality necessary to satisfy the interoperability requirements of the web service.

This is one time setup.

See Arun's screen cast, it talks about the above steps.

You can pretty much avoid steps 3 - 5 above by using an Ant build.xml file.

As you may know, Metro creates a tubeline for each WS endpoint and endoint client to process SOAP messages flowing from and to the endpoint and or its client. Each tubeline consist of a set of tube instances chained together. A tube is a basic SOAP message processing unit. Standard Metro tubes are used to implement processing logic for different SOAP processing aspects (validation, Java-XML mapping etc.) and higher-level QoS domains (security, reliable messaging etc.) As an experimental feature, custom tubes are supported as well.

When developing an advanced web service that requires Quality of Service features or adding a custom tube into the default Metro tubeline, the ability to see the SOAP message content at different processing stages as the message flows through the tubeline may be very useful. As Metro tubeline get's dynamically created for each endpoint or client, Metro (since version 2.0) provides a new message logging facility that copes with the dynamics of a tubeline creation by defining a set of templating rules that provide a generic way for constructing system-level properties able to control message content logging before and/or after each tube's processing.

To turn on the logging for any particular tube (or a set of tubes) created by a specific tube factory, the developer needs to set one or more of the following system properties, depending on the target scope:

There is a set of common system properties that control logging for all tubes and take the lowest precedence so that they can be overriden by a tube-specific properties:

The logger root used for message dumping is <tube_factory_class_name>.

Most of the factories create tubes on both client and endpoint side. To narrow down the message dumping scope, following system properties can be used:

<metro xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
       xmlns='http://java.sun.com/xml/ns/metro/config'
       version="1.0">
   <tubelines default="#default-metro-tubeline">
      <tubeline name="default-metro-tubeline">
         <client-side>
            <tube-factory
                    className="com.sun.xml.ws.assembler.jaxws.TerminalTubeFactory"/>
            <tube-factory
                    className="com.sun.xml.ws.assembler.jaxws.HandlerTubeFactory"/>
            <tube-factory
                    className="com.sun.xml.ws.assembler.jaxws.ValidationTubeFactory"/>
            <tube-factory
                    className="com.sun.xml.ws.assembler.jaxws.MustUnderstandTubeFactory"/>
            <tube-factory
                    className="com.sun.xml.ws.assembler.jaxws.MonitoringTubeFactory"/>
            <tube-factory
                    className="com.sun.xml.ws.assembler.jaxws.AddressingTubeFactory"/>
            <tube-factory
                    className="com.sun.xml.ws.tx.runtime.TxTubeFactory"/>
            <tube-factory
                    className="com.sun.xml.ws.rx.rm.runtime.RmTubeFactory"/>
            <tube-factory
                    className="com.sun.xml.ws.rx.mc.runtime.McTubeFactory"/>
            <tube-factory
                    className="com.sun.xml.wss.provider.wsit.SecurityTubeFactory"/>
            <tube-factory
                    className="com.sun.xml.ws.dump.ActionDumpTubeFactory"/>
            <tube-factory
                    className="com.sun.xml.ws.rx.testing.PacketFilteringTubeFactory"/>
            <tube-factory
                    className="com.sun.xml.ws.dump.MessageDumpingTubeFactory"/>
            <tube-factory
                    className="com.sun.xml.ws.assembler.jaxws.TransportTubeFactory"/>
         </client-side>
         <endpoint-side>
            <tube-factory
                    className="com.sun.xml.ws.assembler.jaxws.TransportTubeFactory"/>
            <tube-factory
                    className="com.sun.xml.ws.dump.MessageDumpingTubeFactory"/>
            <tube-factory
                    className="com.sun.xml.ws.rx.testing.PacketFilteringTubeFactory"/>
            <tube-factory
                    className="com.sun.xml.ws.dump.ActionDumpTubeFactory"/>
            <tube-factory
                    className="com.sun.xml.wss.provider.wsit.SecurityTubeFactory"/>
            <tube-factory
                    className="com.sun.xml.ws.rx.mc.runtime.McTubeFactory"/>
            <tube-factory
                    className="com.sun.xml.ws.assembler.jaxws.AddressingTubeFactory"/>
            <tube-factory
                    className="com.sun.xml.ws.rx.rm.runtime.RmTubeFactory"/>
            <tube-factory
                    className="com.sun.xml.ws.tx.runtime.TxTubeFactory"/>
            <tube-factory
                    className="com.sun.xml.ws.assembler.jaxws.MonitoringTubeFactory"/>
            <tube-factory
                    className="com.sun.xml.ws.assembler.jaxws.MustUnderstandTubeFactory"/>
            <tube-factory
                    className="com.sun.xml.ws.assembler.jaxws.HandlerTubeFactory"/>
            <tube-factory
                    className="com.sun.xml.ws.assembler.jaxws.ValidationTubeFactory"/>
            <tube-factory
                    className="com.sun.xml.ws.assembler.jaxws.TerminalTubeFactory"/>
         </endpoint-side>
      </tubeline>
   </tubelines>
</metro>

com.sun.xml.wss.provider.wsit.SecurityTubeFactory.dump=true
com.sun.xml.wss.provider.wsit.SecurityTubeFactory.dump=true

com.sun.xml.wss.provider.wsit.SecurityTubeFactory.dump.after=true
com.sun.xml.wss.provider.wsit.SecurityTubeFactory.dump.after=true

com.sun.xml.wss.provider.wsit.SecurityTubeFactory.dump.client.after=true
com.sun.xml.wss.provider.wsit.SecurityTubeFactory.dump.client.after=true

com.sun.xml.wss.provider.wsit.SecurityTubeFactory.dump=true
com.sun.xml.wss.provider.wsit.SecurityTubeFactory.dump.endpoint.before=false
com.sun.xml.wss.provider.wsit.SecurityTubeFactory.dump.level=FINE

You can dump incoming HTTP requests and responses to System.out on the server side by using the system property com.sun.xml.ws.transport.http.HttpAdapter.dump=true. This works exactly like above (except that this works on server, not client.) You can also set this property programatically by executing com.sun.xml.ws.transport.http.HttpAdapter.dump=true; as Java progrma.

The transport agnostic dump as explained above also works on the server for incoming messages and responses.

Java SE 6 up to Update Release 3 ships with the JAX-WS 2.0 API, and release 4 and later contains the JAX-WS 2.1 API. (At the time of writing Update Release 3 has long been obsolete and multiple Update Releases have been published with security fixes. It is strongly recommended to upgrade to the latest Update Release of Java SE 6.) Unless you are taking precautions, applications that use the JAX-WS API will run with the JAX-WS API version built into Java SE 6 and not a newer version of JAX-WS on the application classpath. Applications that use new functions of the JAX-WS 2.2 API will therefore fail to run. This section discusses how to work around this issue by using the endorsed standards override mechanism.

Java SE 5 does not include the JAX-WS API at all and does not suffer from the issues discussed in this chapter.

All 1.x releases of WSIT and Metro contain JAX-WS 2.1 and most what has been said in Using JAX-WS 2.x with Java SE 6 applies to Metro 1.x. The only difference are the jar files that need to be copied into the endorsed directory. The one file that needs to be copied to $JRE_HOME/lib/endorsed is webservices-api.jar.

Do not install jaxws-api.jar and jaxb-api.jar into the endorsed directory at the same time. There is a good chance that the versions of these files differ and that may yield very difficult to track application errors. Do not install any other Metro libraries into the endorsed directory, otherwise Metro code may not be able to load classes from the application classpath.

If you are using the metro-on-glassfish.xml or metro-on-tomcat.xml scripts to install Metro, they will take care of installing webservices-api.jar into the Java SE endorsed directory. Note that only with Metro 1.4 or 1.5 will the installation scripts check the Java SE 6 Update Release version.

If you are deploying an application using Metro to GlassFish or Tomcat, it is essential that you are installing Metro with the metro-on-glassfish.xml or metro-on-tomcat.xml scripts. That makes sure that the Metro libraries are getting copied into the GlassFish/Tomcat specific endorsed directories. Without that step, web applications and EJBs will not be able to pick up the JAX-WS 2.1 API. In other words, including the Metro libraries in the WEB-INF/lib of a web application does not make use of the endorsed mechanism and the JAX-WS 2.1 API cannot be used by the web application. Keep in mind that all of the above is only relevant for Java SE 6 Update Release 3 and older.

Metro 2.0 ships with the JAX-WS 2.2 API while Java SE 6 Update Release 4 and later contain the JAX-WS 2.1 API and older Java SE 6 releases contain JAX-WS 2.0. Unless you are taking precautions, applications that use the JAX-WS API will run with the JAX-WS API version built into Java SE 6 and not with the JAX-WS 2.2 API built into Metro on the application classpath. Applications that use new functions of the JAX-WS 2.2 API or other Metro 2.0 functionality will therefore fail to run.

Do not install any other JAX-WS or Metro libraries than the ones discussed below into an endorsed directory at the same time, otherwise Metro code may not be able to load classes from the application classpath.

Typically, one creates the WAR file with a GUI development tool or with the ant war task from the generated artifacts from wsimport, wsgen, or apt tools.

For example, a sample WAR file starting from a WSDL file:

WEB-INF/classes/hello/HelloIF.class SEI
WEB-INF/classes/hello/HelloImpl.class Endpoint
WEB-INF/sun-jaxws.xml JAX-WS RI deployment descriptor
WEB-INF/web.xml Web deployment descriptor
WEB-INF/wsdl/HelloService.wsdl WSDL
WEB-INF/wsdl/schema.xsd WSDL imports this Schema

Metro defines its own deployment descriptor, which is also known as JAX-WS RI deployment descriptor - sun-jaxws.xml.

Here is the schema for sun-jaxws.xml:

<?xml version="1.0" encoding="UTF-8"?>

<!--

  DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

  Copyright (c) 2011 Oracle and/or its affiliates. All rights reserved.

  The contents of this file are subject to the terms of either the GNU
  General Public License Version 2 only ("GPL") or the Common Development
  and Distribution License("CDDL") (collectively, the "License").  You
  may not use this file except in compliance with the License.  You can
  obtain a copy of the License at
  http://glassfish.java.net/public/CDDL+GPL_1_1.html
  or packager/legal/LICENSE.txt.  See the License for the specific
  language governing permissions and limitations under the License.

  When distributing the software, include this License Header Notice in each
  file and include the License file at packager/legal/LICENSE.txt.

  GPL Classpath Exception:
  Oracle designates this particular file as subject to the "Classpath"
  exception as provided by Oracle in the GPL Version 2 section of the License
  file that accompanied this code.

  Modifications:
  If applicable, add the following below the License Header, with the fields
  enclosed by brackets [] replaced by your own identifying information:
  "Portions Copyright [year] [name of copyright owner]"

  Contributor(s):
  If you wish your version of this file to be governed by only the CDDL or
  only the GPL Version 2, indicate your decision by adding "[Contributor]
  elects to include this software in this distribution under the [CDDL or GPL
  Version 2] license."  If you don't indicate a single choice of license, a
  recipient has the option to distribute your version of this file under
  either the CDDL, the GPL Version 2 or to extend the choice of license to
  its licensees as provided above.  However, if you add GPL Version 2 code
  and therefore, elected the GPL Version 2 license, then the option applies
  only if the new code is made subject to such option by the copyright
  holder.

-->

<xsd:schema
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:tns="http://java.sun.com/xml/ns/jax-ws/ri/runtime"
        xmlns:javaee="http://java.sun.com/xml/ns/javaee"
        targetNamespace="http://java.sun.com/xml/ns/jax-ws/ri/runtime"
        elementFormDefault="qualified"
        attributeFormDefault="unqualified"
        version="1.0">

   <xsd:import
       namespace="http://java.sun.com/xml/ns/javaee"
       schemaLocation="http://java.sun.com/xml/ns/javaee/javaee_web_services_1_2.xsd"/>

   <xsd:element name="endpoints">
      <xsd:complexType>
         <xsd:sequence>
            <xsd:element name="endpoint" type="tns:endpointType"
                         minOccurs="0" maxOccurs="unbounded"/>
         </xsd:sequence>
         <xsd:attribute name="version" type="xsd:string" use="required"/>
      </xsd:complexType>
   </xsd:element>

   <xsd:complexType name="endpointType">
      <xsd:annotation>
         <xsd:documentation>
            An endpoint definition has several attributes:
            "name" - the endpoint name
            "implementation" - the name of the endpoint implementation class
            "wsdl" - the name of a resource corresponding to the WSDL
            document for the endpoint
            "service" - the QName of the WSDL service that owns this
            endpoint;
            "port" - the QName of the WSDL port for this endpoint;
            "url-pattern" - the URL pattern this endpoint is mapped to.
            "binding" - specify binding id for SOAP1.1 or SOAP1.2
            "enable-mtom" - Enables MTOM optimization
            "wsdl", "service", "port" attributes are required for provider
            based endpoints
         </xsd:documentation>
      </xsd:annotation>

      <xsd:sequence>
         <xsd:element ref="handler-chains" minOccurs="0"/>
      </xsd:sequence>
      <xsd:attribute name="name" type="xsd:string" use="required"/>
      <xsd:attribute name="implementation" type="xsd:string"
                     use="required"/>
      <xsd:attribute name="wsdl" type="xsd:anyURI"/>
      <xsd:attribute name="service" type="xsd:anyURI"/>
      <xsd:attribute name="port" type="xsd:anyURI"/>
      <xsd:attribute name="url-pattern" type="xsd:anyURI" use="required"/>
      <xsd:attribute name="binding" type="xsd:string"/>
      <xsd:attribute name="enable-mtom" type="xsd:boolean"/>
   </xsd:complexType>

</xsd:schema>

The <endpoints> element contain one or more <endpoint> elements. Each endpoint represents a port in the WSDL and it contains all information about implementation class, servlet url-pattern, binding, WSDL, service, port QNames. The following shows a sun-jaxws.xml file for a simple HelloWorld service. sun-jaxws.xml is the schema instance of sun-jaxws.xml.

<?xml version="1.0" encoding="UTF-8"?>
<endpoints
        xmlns="http://java.sun.com/xml/ns/jax-ws/ri/runtime"
        version="2.0">
    <endpoint
            name="MyHello"
            implementation="hello.HelloImpl"
            url-pattern="/hello"/>
</endpoints>

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE web-app PUBLIC
        "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
        "http://java.sun.com/j2ee/dtds/web-app_2_3.dtd">

<web-app>
   <listener>
      <listener-class>
         com.sun.xml.ws.transport.http.servlet.WSServletContextListener
      </listener-class>
   </listener>
   <servlet>
      <servlet-name>hello</servlet-name>
      <servlet-class>com.sun.xml.ws.transport.http.servlet.WSServlet
      </servlet-class>
      <load-on-startup>1</load-on-startup>
   </servlet>
   <servlet-mapping>
      <servlet-name>hello</servlet-name>
      <url-pattern>/hello</url-pattern>
   </servlet-mapping>
   <session-config>
      <session-timeout>60</session-timeout>
   </session-config>
</web-app>

TODO

See Using Metro With Spring.

A little bit about Message Context in JAX-WS :This article explains about the context that is available to Client application, Handlers and Service that can be used to access/propagate additional contextual information.

Introduction to Handlers in JAX-WS: This article introduces to Handler framework in JAX-WS.

Extend your Web Service applications with the new efficient Handlers in JAX-WS RI : Use this RI extension to take advantage of the JAX-WS RI Message API for efficient access to message and other contextual information.

See this thread for information. If anyone can confirm/deny that this works, that would be great.

This works well but requires some work, such as composing the right catalog file then package it appropriately.

There is another easy way to do it - just run wsimport with -wsdlLocation switch and provide the WSDL location value which is relative to the generated Service class and provide the WSDL location value which is relative to the generated Service class and you need to put this WSDL file at this relative location.

Let us try to create a client for the NET 3.0 MTOM endpoint. I am using Metro 1.0.

First I save the .NET 3.0 MTOM WSDL locally then run wsimport giving the relative location to where you will package the wsdl with your application

wsimport -keep -d build/classes -p client etc/Soap11MtomUtf8.svc.xml -wsdlLocation ../Soap11MtomUtf8.svc.xml

Here is excerpt from the generated MtomService class. You can see how the wsdlLocation value is generated inside it and is used internally to create the Service.

/**
 * This class was generated by the JAX-WS RI.
 * JAX-WS RI 2.1.2-hudson-53-SNAPSHOT
 * Generated source version: 2.1
 */
@WebServiceClient(name = "MtomService",
        targetNamespace = "http://tempuri.org/",
        "../Soap11MtomUtf8.svc.xml")
public class MtomService extends Service {

    private final static URL MTOMSERVICE_WSDL_LOCATION;
    private final static Logger logger = Logger.getLogger(client
            .MtomService.class.getName());

    static {
        URLurl = null;
        try {
            URLbaseUrl;

            baseUrl = client.MtomService.class.getResource(".");
            url = new URL(baseUrl, "../Soap11MtomUtf8.svc.xml");
        } catch (MalformedURLException e) {
            logger.warning("Failed to create URL for the wsdl Location: ." +
                    "./Soap11MtomUtf8.svc.xml");
            logger.warning(e.getMessage());
        }
        MTOMSERVICE_WSDL_LOCATION = url;
    }

    public MtomService() {
        super(MTOMSERVICE_WSDL_LOCATION,
                new QName("http://tempuri.org/", "MtomService"));
    }

    ...
    

See Client.java below it invokes the .NET 3.0 service. You may notice here that you dont need to enable MTOM explicitly. Metro bring in .NET 3.0 interop thru WSIT and due to this the MTOM policy assertions in the .NET 3.0 WSDL, it correctly interpreted and the IMtomTest port is configured with MTOM enabled.

package client;

import com.sun.xml.ws.transport.http.client.HttpTransportPipe;

/**
 * Client that invokes .NET 3.0 MTOM endpoint using a local wsdl
 */
public class Client {

    public static void main(String[] args) {

        //enble SOAP Message logging
        HttpTransportPipe.dump = true;

        //Create IMtomTest proxy to invoke .NET 3.0 MTOM service
        IMtomTest proxy = new MtomService().getBasicHttpBindingIMtomTest();
        String input = "Hello World";
        byte[] response = proxy.echoStringAsBinary(input);
        System.out.println("Sent: " + input + ", Received: " + new String
                (response));
    }
}

Get the complete client bundle from here and see the enclosed Readme.txt for instructions on how to run it.

You can use BindingProvider.ENDPOINT_ADDRESS_PROPERTY to set the endpoint address in your client application code.

//Create service and proxy from the generated Service class.
HelloService service = new HelloService();
HelloPort proxy = service.getHelloPort();

((BindingProvider) proxy).getRequestContext().put(BindingProvider
        .ENDPOINT_ADDRESS_PROPERTY, "http://new/endpointaddress");

proxy.sayHello("Hello World!");           

In case you have access to the updated WSDL which has the right endpoint address, you can simply create the Service using this WSDL and there will be no need to set the BindingProvider.ENDPOINT_ADDRESS property.

//Create service and proxy from the generated Service class.
HelloService service = new HelloService(serviceName,
        "http://new/endpointaddress?wsdl");
HelloPort proxy = service.getHelloPort();

proxy.sayHello("Hello World!");

Content negotiation is completely driven by the client and uses the standard HTTP headers Accept and Content-Type. The initial request is always encoded in XML, but the client has the option of including the MIME type application/fastinfoset as part of the HTTP Accept header list. If the request is received by a Fast Infoset-enabled service, the reply will be encoded in Fast Infoset. The remainder of the conversation between the client and the service will also be encoded in Fast Infoset as long as the client continues to use the same client object (e.g., the same stub instance) to converse with the server. We call this form of negotiation pessimistic, in contrast to the optimistic case in which a client directly initiates a message exchange using the more efficient encoding.

Content negotiation can be enabled in two different ways: (i) by setting a system property on the VM used to run the client, and (ii) by setting a property on the proxy object. In either case, both the property name and its value are identical. For JAX-WS, the name of the property is com.sun.xml.ws.client.ContentNegotiation. In either case, the accepted property values are none (the default) and pessimistic, optimistic.

// Enabling FI in pessimistic mode
Map<String, Object> ctxt = ((BindingProvider)proxy).getRequestContext();
ctxt.put(JAXWSProperties.CONTENT_NEGOTIATION_PROPERTY, "pessimistic");

java -Dcom.sun.xml.ws.client.ContentNegotiation=pessimistic ...

wsimport uses JAXB RI's XJC tool internally to achive XML Schema to Java binding. The default behaviour is strictly as per JAXB 2.x specification. However it does not work for everyone, for example if you want to map xs:anyURI to java.net.URI instead of java.lang.String (default mapping).

There is a JAXB global customization that can help you achieve these tasks:

<?xml version="1.0" encoding="UTF-8"?>
<jaxb:bindings
  xmlns:jaxb="http://java.sun.com/xml/ns/jaxb" jaxb:version="2.0"
  xmlns:xjc= "http://java.sun.com/xml/ns/jaxb/xjc" jaxb:extensionBindingPrefixes="xjc">

  <jaxb:globalBindings>
    <xjc:simple />
  </jaxb:globalBindings>
</jaxb:bindings>

Then simply run your wsimport and pass this binding customization file

wsimport -p mypackage -keep -b simple.xjb myservice.wsdl

See Kohsuke's blog for more details.

The portable way of doing this is that you creaate a SOAPHandler and mess with SAAJ, but the RI provides a better way of doing this.

When you create a proxy or dispatch object, they implement BindingProvider interface. When you use the JAX-WS RI, you can downcast to WSBindingProvider which defines a few more methods provided only by the JAX-WS RI.

This interface lets you set an arbitrary number of Header object, each representing a SOAP header. You can implement it on your own if you want, but most likely you'd use one of the factory methods defined on Headers class to create one.

import com.sun.xml.ws.developer.WSBindingProvider;

HelloPort port = helloService.getHelloPort();  // or something like that...
WSBindingProvider bp = (WSBindingProvider) port;

bp.setOutboundHeader(
        // simple string value as a header, 
        // like <simpleHeader>stringValue</simpleHeader>
        Headers.create(new QName("simpleHeader"), "stringValue"),
        // create a header from JAXB object
        Headers.create(jaxbContext, myJaxbObject)
);

Once set, it will take effect on all the successive methods. If you'd like to see more factory methods on Headers, please let us know.

Server can access all the SOAP headers of the incoming messages by using the JAXWSProperties#INBOUND_HEADER_LIST_PROPERTY property like this:

@WebService
public class FooService {
    @Resource
    WebServiceContext context;

    @WebMethod
    public void sayHelloTo(String name) {
        HeaderList hl = context.getMessageContext().get(JAXWSProperties
                .INBOUND_HEADER_LIST_PROPERTY);
        Header h = hl.get(MYHEADER);
    }

    private static final QName MYHEADER = new QName("myNsUri", "myHeader");
}

Clients can similarly access all the SOAP headers of the incoming messages:

HelloPort port = helloService.getHelloPort();  // or something like that...
port.sayHelloTo("duke");
HeaderList hl = port.getResponseContext().get(JAXWSProperties
        .INBOUND_HEADER_LIST_PROPERTY);
Header h = hl.get(MYHEADER);

See the Header interface for more details about how to access the header values.

Servers tend to be developed "from-Java" style, so we feel the necessity of adding out-of-band headers is smaller (you can just define headers as method @WebParam(mode=OUT,header=true) parameters.) Therefore, currently there's no support for adding out-of-band SOAP headers into response messages.

If you'd like us to improve on this front, please let us know.

Sometimes WSDLs in the binding section reference soap:header messages that are not part of the input or output contract defined in the portType operation. For example:

<message name="additionalHeader">
   <part name="additionalHeader" element="types:additionalHeader"/>
</message>

<wsdl:portType name="HelloPortType">
   <wsdl:operation name="echo">
      <wsdl:input message="tns:echoRequest"/>
      <wsdl:output message="tns:echoResponse"/>
   </wsdl:operation>
</wsdl:portType>

<wsdl:binding name="HelloBinding" type="tns:HelloPortType">
   <soap:binding style="document"
                 transport="http://schemas.xmlsoap.org/soap/http"/>
   <wsdl:operation name="echo">
      <soap:operation/>
      <wsdl:input>
         <soap:body message="tns:echoRequest"/>
         <soap:header message="tns:additionalHeader"
                      part="additionalHeader"/>
      </wsdl:input>
      <wsdl:output>
         <soap:body message="tns:echoResponse"/>
      </wsdl:output>
   </wsdl:operation>
</wsdl:binding>

In the above schema in the wsdl:binding section tns:additionalHeader is bound but if you see this header is not part of the echo abstract contract (i.e., the wsdl:portType section). According to JAX-WS 2.1 specification only the wsdl:part's from the abstract portion are mapped to Java method parameters.

Running wsimport on this wsdl will generate this method signature:

wsimport sample.wsdl

public String echo(String request);

wsimport -XadditionalHeaders sample.wsdl

public String echo(String request, String additionalHeader);

The @SchemaValidation annotation needs to be specified on the endpoint implementation to enable server side validation. Both the incoming SOAP request and outgoing SOAP response will be validated, with exceptions returned to the client for any validation errors that occur.

import com.sun.xml.ws.developer.SchemaValidation;
...

@SchemaValidation
@WebService
public class HelloImpl {
}

If a application wants to have complete control over validation error handling, it can set up a ValidationErrorHandler to receive notification of errors. The handler has access to the Packet and can store any information in its invocationProperties. These properties are accessible from the endpoint's MessageContext.

@SchemaValidation(handler = MyErrorHandler.class)
@WebService
public class HelloImpl {
}

import com.sun.xml.ws.developer.ValidationErrorHandler;
import org.xml.sax.SAXParseException;
import org.xml.sax.SAXException;

public class MyErrorHandler extends ValidationErrorHandler {
    public void warning(SAXParseException e) throws SAXException {
        // Store warnings in the packet so that they can be retrieved 
        // from the endpoint
        packet.invocationProperties.put("error", e);
    }

    public void error(SAXParseException e) throws SAXException {
        throw e;
    }

    public void fatalError(SAXParseException e) throws SAXException {
        ; // noop
    }
}

Proxy needs to be created with SchemaValidationFeature to enable client side validation. Both the outgoing SOAP request and incoming SOAP response will be validated.

import com.sun.xml.ws.developer.SchemaValidationFeature;
...

SchemaValidationFeature feature = new SchemaValidationFeature();
HelloPort port = new HelloService.getHelloPort(feature);
// All invocations on this port are validated

If a client application wants to have complete control over validation error handling, it can set up a ValidationErrorHandler to receive notification of errors. The handler has access to the Packet and can store any information in its invocationProperties. These properties are accessible from proxy's response context.

SchemaValidationFeature feature =
        new SchemaValidationFeature(MyErrorHandler.class);
HelloPort port = new HelloService.getHelloPort(feature);
// All invocations on this port will be validated

Client can set additional HTTP headers for making a requests by using MessageContext.HTTP_REQUEST_HEADERS. See the following code for an example:

import java.util.Collections;
import javax.xml.ws.BindingProvider;
import javax.xml.ws.handler.MessageContext; 

HelloPort port =...;
((BindingProvider) port).getRequestContext().put(MessageContext
        .HTTP_REQUEST_HEADERS, Collections.singletonMap
        ("X-Client-Version", Collections.singletonList("1.0-RC")));

// the header will be sent to all successive invocations
port.sayHelloTo("duke");
port.sayHelloTo("duke");

Note that the property takes Map<String,List<String>> as the type.

Clients can access the HTTP headers of the response by using MessageContext.HTTP_RESPONSE_HEADERS. See the following code for example:

HelloPort port = ...;
port.sayHelloTo("duke");

headers = (Map<String, List<String>>) ((BindingProvider) port)
        .getResponseContext().get(MessageContext.HTTP_RESPONSE_HEADERS);

To enable cookie support, you need to enable the session property. This causes requests sent via the port to use the same cookie jar, so if the server responds with a cookie, the next request will go out with those cookies. This allows the server to use the normal session tracking mechanism like HttpSession.

HelloPort port = ...;
port.getRequestContext().put(BindingProvider.SESSION_MAINTAIN_PROPERTY,true);

TODO

When the web service is using servlets as the transport mechanism, you can use servlet's native support for cookies. See the following code to how to access javax.servlet.http.HttpServletRequest from your service.

class MyService {
    @Resource
    WebServiceContext context;

    public void foo() {
        HttpServletRequest rq = (HttpServletRequest) context
                .getMessageContext().get(MessageContext.SERVLET_REQUEST);
        HttpServletResponse rs = (HttpServletResponse) context
                .getMessageContext().get(MessageContext.SERVLET_RESPONSE);
    }
}

HTTP headers can be accessed in a client side Handler in an incoming response. Here is Handler code that demonstrates how to do this:

public class ClientHandler implements SOAPHandler<SOAPMessageContext> {
    public boolean handleMessage(SOAPMessageContext context) {
        if (!(Boolean) context.get(MessageContext
                .MESSAGE_OUTBOUND_PROPERTY)) {
            
            Map<String, List<String>> map = (Map<String, 
                    List<String>>) context.get(MessageContext
                    .HTTP_RESPONSE_HEADERS);
            
            List<String> contentType = getHTTPHeader(map, "Content-Type");
            if (contentType != null) {
                StringBuffer strBuf = new StringBuffer();
                for (String type : contentType) {
                    strBuf.append(type);
                }
                System.out.println("Content-Type:" + strBuf.toString());
            }
        }
        return true;
    }


    private
    @Nullable
    List<String> getHTTPHeader(Map<String, List<String>> headers, 
                               String header) {
        for (Map.Entry<String, List<String>> entry : headers.entrySet()) {
            String name = entry.getKey();
            if (name.equalsIgnoreCase(header))
                return entry.getValue();
        }
        return null;
    }
}

HTTP headers can be accessed in a server side Handler on an incoming request. Here is Handler code that demonstrates how to do this:

public class ServerHandler implements SOAPHandler<SOAPMessageContext> {
    public boolean handleMessage(SOAPMessageContext context) {

        if (!(Boolean) context.get(MessageContext
                .MESSAGE_OUTBOUND_PROPERTY)) {
            
            Map<String, List<String>> map = (Map<String, 
                    List<String>>) context.get(MessageContext
                    .HTTP_REQUEST_HEADERS);
            
            List<String> contentType = getHTTPHeader(map, "Content-Type");
            if (contentType != null) {
                StringBuffer strBuf = new StringBuffer();
                for (String type : contentType) {
                    strBuf.append(type);
                }
                System.out.println("Content-Type:" + strBuf.toString());
            }
        }

        return true;
    }

    private
    @Nullable
    List<String> getHTTPHeader(@NotNull Map<String, 
            List<String>> headers, @NotNull String header) {
        
        for (Map.Entry<String, List<String>> entry : headers.entrySet()) {
            String name = entry.getKey();
            if (name.equalsIgnoreCase(header))
                return entry.getValue();
        }
        return null;
    }
}

JAX-WS RI extension Provider<Message> can be used to read an incoming SOAP message by using XMLStreamReader (among other things.) This allows you to read the SOAP message on-demand lazily, without needing to buffer the whole message in memory.

See the relevant JAXB users guide section for how to combine JAXB with such streaming processing.

MTOM (and XOP) allows you to send and receive binary attachments (such as files and images) efficiently and in an interoperable manner.

Content-Type: Multipart/Related; start-info="text/xml"; type="application/xop+xml"; boundary="----=_Part_0_1744155.1118953559416"
Content-Length: 3453
SOAPAction: ""

------=_Part_1_4558657.1118953559446
Content-Type: application/xop+xml; type="text/xml"; charset=utf-8

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <Detail xmlns="http://example.org/mtom/data">
      <image>
        <xop:Include xmlns:xop="http://www.w3.org/2004/08/xop/include" href="cid:5aeaa450-17f0-4484-b845-a8480c363444@example.org" />
      </image>
    </Detail>
  </S:Body>
</S:Envelope>


------=_Part_1_4558657.1118953559446
Content-Type: image/jpeg
Content-ID: <5aeaa450-17f0-4484-b845-a8480c363444@example.org>


... binary data ...

<element name="Detail" type="types:DetailType"/>
<complexType name="DetailType">
  <sequence>
    <element name="image" type="base64Binary" />
  </sequence>
</complexType>

<element name="TestMtomXmimeContentType" type="types:PictureType"/>

<complexType name="PictureType">
  <simpleContent>
    <restriction base="xmime:base64Binary">
      <attribute ref="xmime:contentType" use="required" />
    </restriction>
  </simpleContent>
</complexType>

PictureType req = new PictureType();
req.setValue(name.getBytes());
req.setContentType("application/xml");

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:ns1="http://example.org/mtom/data"
  xmlns:ns2="http://www.w3.org/2005/05/xmlmime">
  <S:Body>
    <ns1:TestMtomXmimeContentTypeResponse ns2:contentType="application/xml">
      <xop:Include
          xmlns:xop="http://www.w3.org/2004/08/xop/include"
          href="cid:193ed174-d313-4325-8eed-16cc25595e4e@example.org"/>
    </ns1:TestMtomXmimeContentTypeResponse>
  </S:Body>
</S:Envelope>

There are several ways to enable MTOM.

There are several ways to enable MTOM.

As discussed above, in rare situations where you have a lot of tiny attachments, the overhead of MTOM may outweigh the benefit of binary transfer. To cope with this situation, the JAX-WS RI supports the notion of "threshold" --- if an attachment is smaller than the size specified in threshold, it will simply inline the binary data as base64 binary instead of making it an attachment. Because of the way MTOM spec is designed, such inline vs attachment decision is handled by the toolkits of both ends and will not harm the application running on both sides.

There are two ways to control the threshold:

RI uses Java SE's HttpURLConnection for web service invocations. HttpURLConnection buffers the request data by default. So the client applications need to enable streaming explicitly, see http client streaming. The following sample show how to send and receive large data.

import com.sun.xml.ws.developer.JAXWSProperties;
import com.sun.xml.ws.developer.StreamingDataHandler;

MTOMFeature feature = new MTOMFeature();
MyService service = new MyService();
MyProxy proxy = service.getProxyPort(feature);
Map<String, Object> ctxt = ((BindingProvider)proxy).getRequestContext();
// Enable HTTP chunking mode, otherwise HttpURLConnection buffers
ctxt.put(JAXWSProperties.HTTP_CLIENT_STREAMING_CHUNK_SIZE, 8192); 
DataHandler dh = proxy.fileUpload(...);
StreamingDataHandler sdh = (StreamingDataHandler)dh;
InputStream in = sdh.readOnce();
...
in.close();
sdh.close();

Use @MTOM feature for a service and DataHandler parameter for large data. If the WSDL contains xmime:expectedContentTypes="application/octet-stream", it would be mapped to DataHandler in the generated SEI. If the service is starting from java, @XmlMimeType("application/octet-stream") can be used to generate an appropriate schema type in the generated WSDL.

The following sample shows how to upload files. It uses StreamingDataHandler.moveTo(File) convenient method to store the contents of the attachment to a file.

import com.sun.xml.ws.developer.StreamingDataHandler;
...

@MTOM
@WebService
public class UploadImpl {

    // Use @XmlMimeType to map to DataHandler on the client side
    public void fileUpload(String name, 
                           @XmlMimeType("application/octet-stream") 
                           DataHandler data) {
        try {
            StreamingDataHandler dh = (StreamingDataHandler) data;
            File file = File.createTempFile(name, "");
            dh.moveTo(file);
            dh.close();
        } catch (Exception e) {
            throw new WebServiceException(e);
        }
    }
}

You can configure streaming attachments behaviour using @StreamingAttachment on the server side, and using StreamingAttachmentFeature on the client side. Using this feature, you can configure only certain sized attachments are written to a file.

import com.sun.xml.ws.developer.StreamingAttachment;

// Configure such that whole MIME message is parsed eagerly,
// Attachments under 4MB are kept in memory
@MTOM
@StreamingAttachment(parseEagerly=true, memoryThreshold=4000000L)
@WebService
public class UploadImpl {
}

import com.sun.xml.ws.developer.StreamingAttachmentFeature;

MTOMFeature mtom = new MTOMFeature();
// Configure such that whole MIME message is parsed eagerly,
// Attachments under 4MB are kept in memory
StreamingAttachmentFeature stf =
        new StreamingAttachmentFeature(null, true, 4000000L);
MyService service = new MyService();
MyProxy proxy = service.getProxyPort(feature, stf);

As all other WS-* features, WS-MakeConnection can be enabled using a WS-Policy assertion. Unfortunately, unlike many other WS-* features, NetBeans IDE in it's current version 6.8 don't provide a nice GUI-based support for enabling/disabling WS-MakeConnection feature on an endpoint. This means that in order to enable WS-MakeConnection, you need to manually put the assertion into your endpoint's WSIT config file. Here are the steps:

In addition to using WS-Policy expression as discussed in Configuration via an WS-Policy expression, you may as well configure WS-MakeConnection support using a @MakeConnectionSupported Java annotation provided by Metro. Please note, that this annotation is meant to annotate whole classes only. The resulting Java code for a sample web service would look like this:

package com.sun.metro.mc.service;

import com.sun.xml.ws.rx.mc.MakeConnectionSupported;
import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebService;

@WebService()
@MakeConnectionSupported
public class McTestEcho {

    /**
     * Web service operation
     */
    @WebMethod(operationName = "echo")
    public String echo(@WebParam(name = "message")
    final String message) {
        return "Received: " + message;
    }

}

Summary of Service-Side Configuration Requirements summarizes the options that need to be configured for each security mechanism. Each of the columns is briefly discussed after the table.

Summary of Client-Side Configuration Requirements summarizes the options that need to be configured for each of the security mechanisms on the client-side. Each of the columns is briefly discussed after the table.

if (callbacks[i] instanceof SAMLCallback) {
    try {

        SAMLCallback samlCallback = (SAMLCallback) callbacks[i];

        /*
         Set confirmation Method to SV [SenderVouches] or
         HOK[Holder of Key]
        */
        samlCallback.setConfirmationMethod(samlCallback
                .SV_ASSERTION_TYPE);

        if (samlCallback.getConfirmationMethod().equals
                (samlCallback.SV_ASSERTION_TYPE)) {
            
            samlCallback.setAssertionElement
                    (createSVSAMLAssertion());

            svAssertion_saml10 = samlCallback.getAssertionElement();
            /*
            samlCallback.setAssertionElement
                (createSVSAMLAssertion20());
            svAssertion_saml20 =
                 samlCallback.getAssertionElement();
            */
        } else if (samlCallback.getConfirmationMethod().equals
                (samlCallback.HOK_ASSERTION_TYPE)) {
            
            samlCallback.setAssertionElement
                    (createHOKSAMLAssertion());
            hokAssertion_saml10 = samlCallback
                    .getAssertionElement();
            /*
            samlCallback.setAssertionElement
                (createHOKSAMLAssertion20());
            hokAssertion_saml20 =
                 samlCallback.getAssertionElement();
            */
        }
    } catch (Exception e) {
        e.printStackTrace();
    }
} else {
    throw unsupportedCallback;
}

The Username Authentication with Symmetric Key mechanism protects your application for integrity and confidentiality. Symmetric key cryptography relies on a single, shared secret key that is used to both sign and encrypt a message. Symmetric keys are usually faster than public key cryptography.

For this mechanism, the client does not possess any certificate/key of his own, but instead sends its username/password for authentication. The client shares a secret key with the server. The shared, symmetric key is generated at runtime and encrypted using the service's certificate. The client must specify the alias in the truststore by identifying the server's certificate alias.

See Also: Example: Username Authentication with Symmetric Key (UA).

This feature is same as "Username Authentication with Symmetric Key", except that the protection token is Username Token.This feature relies on a single, shared secret key that is derived using password, salt(a 16 byte random array),iterations(an int value).This key will be used for signing and encrypting a message.

For this mechanism, the client does not need to have any certificate/key of his own.A 160 bit secret key will be generated using password,salt and iterations. This secret key will be used for signature/encryption. In the request the username,salt and iterations will be send to the server.The server generates the same key using the password(which it already has),salt and iterations. Using this key the server is able to decrypt the message and verify the signature.The default value for iterations is 1000.Current Netbeans versions doesn't show this feature in the security features list.So for a detailed explanation about this feature and to know how to configure this , please visit the blog: http://blogs.sun.com/SureshMandalapu/entry/passwordderivedkeys_support_in_metro

The Mutual Certificates Security mechanism adds security through authentication and message protection that ensures integrity and confidentiality. When using mutual certificates, a keystore and truststore file must be configured for both the client and server sides of the application.

See Also: Example: Mutual Certificates Security (MCS).

Symmetric Binding with Kerberos Tokens does client authentication using Kerberos Tokens and integrity and confidentiality protection using symmetric keys generated with Kerberos V5 Protocol. This profile assumes that Kerberos authentication is supported by the underlying platform and a KDC is configured. When using Kerberos Tokens Profile, a Login Module must be configured for the service, and a Login Module and Service Principal must be specified for the client.

See Also: Example: Kerberos Token (Kerb).

The Transport Security mechanism protects your application during transport using SSL for authentication and confidentiality. Transport-layer security is provided by the transport mechanisms used to transmit information over the wire between clients and providers, thus transport-layer security relies on secure HTTP transport (HTTPS) using Secure Sockets Layer (SSL). Transport security is a point-to-point security mechanism that can be used for authentication, message integrity, and confidentiality. When running over an SSL-protected session, the server and client can authenticate one another and negotiate an encryption algorithm and cryptographic keys before the application protocol transmits or receives its first byte of data. Security is "live" from the time it leaves the consumer until it arrives at the provider, or vice versa. The problem is that it is not protected once it gets to its destination. For protection of data after it reaches its destination, use one of the security mechanisms that uses SSL and also secures data at the message level.

Digital certificates are necessary when running secure HTTP transport (HTTPS) using Secure Sockets Layer (SSL). The HTTPS service of most web servers will not run unless a digital certificate has been installed. Digital certificates have already been created for GlassFish, and the default certificates are sufficient for running this mechanism, and are required when using Atomic Transactions (see Using Atomic Transactions ). However, the message security mechanisms require a newer version of certificates than is available with GlassFish. You can download valid keystore and truststore files for the client and server as described in To Manually Update GlassFish Certificates.

To use this mechanism, follow the steps in Configuring SSL For Your Applications.

See Also: Example: Transport Security (SSL).

javax.xml.ws.WebServiceException: java.io.IOException:
HTTPS hostname wrong: should be <hostname as in the certificate>

static {
    //WORKAROUND. TO BE REMOVED.
    javax.net.ssl.HttpsURLConnection.setDefaultHostnameVerifier(
            new javax.net.ssl.HostnameVerifier(){
                public boolean verify(String hostname,
                                      javax.net.ssl.SSLSession sslSession) {
                    if (hostname.equals("mytargethostname")) {
                        return true;
                    }
                    return false;
                }
            });
}             

The Message Authentication over SSL mechanism attaches a cryptographically secured identity or authentication token with the message and use SSL for confidentiality protection.

By default, a Username Supporting Token will be used for message authentication. To use an X.509 Supporting Token instead, click the Configure button and select X509. Under this scenario, you will need to configure your system for using SSL as described in Configuring SSL For Your Applications.

The SAML Authorization over SSL mechanism attaches an authorization token with the message and uses SSL for confidentiality protection. In this mechanism, the SAML token is expected to carry some authorization information about an end user. The sender of the token is actually vouching for the credentials in the SAML token.

To use this mechanism, configure SSL on the server, as described in Configuring SSL For Your Applications, and, on the clients side, configure a SAMLCallbackHandler as described in Example SAML Callback Handlers.

See Also: Example: SAML Authorization over SSL (SA).

This mechanism uses secure messages using symmetric key for integrity and confidentiality protection, and uses an endorsing client certificate to augment the claims provided by the token associated with the message signature. For this mechanism, the client knows the service's certificate, and requests need to be endorsed/authorized by a special identity. For example, all requests to a vendor must be endorsed by a purchase manager, so the certificate of the purchase manager should be used to endorse (or counter sign) the original request.

This mechanism protects messages with mutual certificates for integrity and confidentiality and with a Sender Vouches SAML token for authorization. The Sender Vouches method establishes the correspondence between a SOAP message and the SAML assertions added to the SOAP message. The attesting entity provides the confirmation evidence that will be used to establish the correspondence between the subject of the SAML subject statements (in SAML assertions) and SOAP message content. The attesting entity, presumed to be different from the subject, vouches for the verification of the subject. The receiver has an existing trust relationship with the attesting entity. The attesting entity protects the assertions (containing the subject statements) in combination with the message content against modification by another party. For more information about the Sender Vouches method, read the SAML Token Profile document at http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.0.pdf .

For this mechanism, the SAML token is included as part of the message signature as an authorization token and is sent only to the recipient. The message payload needs to be signed and encrypted. The requestor is vouching for the credentials (present in the SAML assertion) of the entity on behalf of which the requestor is acting.

The initiator token, which is an X.509 token, is used for signature. The recipient token, which is also an X.509 token, is used for encryption. For the server, this is reversed, the recipient token is the signature token and the initiator token is the encryption token. A SAML token is used for authorization.

See Also: Example: SAML Sender Vouches with Certificates (SV).

This mechanism protects messages with a signed SAML assertion (issued by a trusted authority) carrying client public key and authorization information with integrity and confidentiality protection using mutual certificates. The Holder-of-Key (HOK) method establishes the correspondence between a SOAP message and the SAML assertions added to the SOAP message. The attesting entity includes a signature that can be verified with the key information in the confirmation method of the subject statements of the SAML assertion referenced for key info for the signature. For more information about the Holder of Key method, read the SAML Token Profile document at http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.0.pdf .

Under this scenario, the service does not trust the client directly, but requires the client to send a SAML assertion issued by a particular SAML authority. The client knows the recipient's public key, but does not share a direct trust relationship with the recipient. The recipient has a trust relationship with the authority that issues the SAML token. The request is signed with the client's private key and encrypted with the server certificate. The response is signed using the server's private key and encrypted using the key provided within the HOK SAML assertion.

This security mechanism protects messages using a token issued by a trusted Secure Token Service (STS) for message integrity and confidentiality protection.

An STS is a service that implements the protocol defined in the WS-Trust specification (you can find a link to this specification at http://wsit.java.net/ ). This protocol defines message formats and message exchange patterns for issuing, renewing, canceling, and validating security tokens.

Service providers and consumers are in potentially different managed environments but use a single STS to establish a chain of trust. The service does not trust the client directly, but instead trusts tokens issued by a designated STS. In other words, the STS is taking on the role of a second service with which the client has to securely authenticate. The issued tokens contain a key, which is encrypted for the server and which is used for deriving new keys for signing and encrypting.

To use this mechanism for the web service, you simply select this option as your security mechanism. However, you must have a Security Token Service that can be referenced by the service. An example of an STS can be found in the section To Create and Secure the STS (STS) . In this section, you select a security mechanism for the STS. The security configuration for the client-side of this application is dependent upon the security mechanism selected for the STS, and not on the security mechanism selected for the application. The client truststore must contain the certificate of the STS, which has the alias of wssip if you are using the updated GlassFish certificates.

See Also: Example: STS Issued Token (STS).

This security mechanism is similar to the one discussed in STS Issued Token , with the difference being that in addition to the service requiring the client to authenticate using a SAML token issued by a designated STS, confidentiality protection is achieved using a service certificate. A service certificate is Unhandled tag caution used by a client to authenticate the service and provide message protection. For GlassFish, a default certificate of s1as is installed.

To use this mechanism for the web service, you simply select this option as your security mechanism. However, you must have a Security Token Service that can be referenced by the service. An example of an STS can be found in the section To Create and Secure the STS (STS) . In this section, you select a security mechanism for the STS. The security configuration for the client-side of this application is dependent upon the security mechanism selected for the STS, and not on the security mechanism selected for the application. The client truststore must contain the certificate of the STS, which has the alias of wssip if you are using the updated GlassFish certificates.

This security mechanism is similar to the one discussed in STS Issued Token , with the difference being that the client authenticates using a SAML token that is issued by a designated STS. An endorsing token is used to sign the message signature.

In this mechanism, message integrity and confidentiality are protected using ephemeral keys encrypted for the service. Ephemeral keys use an algorithm where the exchange key value is purged from the cryptographic service provider (CSP) when the key handle is destroyed. The service requires messages to be endorsed by a SAML token issued by a designated STS.

Service providers and consumers are in potentially different managed environments. For this mechanism, the service requires that secure communications be endorsed by a trusted STS. The service does not trust the client directly, but instead trusts tokens issued by a designated STS. In other words, the STS is taking on the role of a second service with which the client has to securely authenticate.

For this mechanism, authentication of the client is achieved in this way:

To use this mechanism for the web service, you simply select this option as your security mechanism. However, you must have a Security Token Service that can be referenced by the service. An example of an STS can be found in the section To Create and Secure the STS (STS) . In this section, you select a security mechanism for the STS. The security configuration for the client-side of this application is dependent upon the security mechanism selected for the STS, and not on the security mechanism selected for the application. The client truststore must contain the certificate of the STS, which has the alias of wssip if you are using the updated GlassFish certificates.

This section describes adding the steps to configure your application for SSL. These steps will need to be accomplished for any application that uses one of the mechanisms:

This section describes the following tasks: