The Web Services binding is based on Metro, the JAX-WS RI. When developing web services, the service contract can be a plan Java interface or decorated with JAX-WS annotations. If a plain Java interface is used, Fabric3 will map it to WSDL using JAX-WS defaults. If default behavior is not desired, standard JAX-WS annotations may be used to customize the service WSDL.

Note that when creating a web service that uses JAX-WS annotations, it is NOT necessary to import the JAX-WS, JAXB, and javax.soap packages into the contribution as the runtime makes these available to applications automatically.

Interoperability with .NET

Fabric3 provides out-of-the-box interoperability with .NET and Windows Communication Foundation (WCF). To assist with interoperability, Fabric3 will automatically generate a WSDL for deployed services. This WSDL will include schemas for message types, service contract information (portType), and all necessary endpoint information (service and bindings). In addition, the WSDL will also contain attached policy if the service is deployed with intents or policy sets. For example, if a service is configured with a security intent, Fabric3 will merge the corresponding policy (based on WS-SecurityPolicy) into the generated WSDL. This merging process is performed according to the rules laid out by the WS-PolicyAttachement and WS-SecurityPolicy specifications. Fortunately, WSDL generation is transparent to end-users so in most cases you will not need to be concerned with the details of how it is performed.

Generated service WSDL can be accessed by appending "?wsdl" to the service URL, as in:

http://www.foo.com/someService?wsdl

The generated WSDL can be used to create client proxies. In most cases, Microsoft web services tooling, including Visual Studio and SvcUtil, will be able to consume a Fabric3 generated WSDL and create a proxy that can be used directly without manual configuration changes. This out-of-the-box interoperability extends to Fabric3 provided security intents and policy sets (detailed below), which have been designed specifically to work with .NET clients.

Asynchronous Web Services

Fabric3 supports asynchronous web service invocations. To enable a one-way (asynchronous) operation, annotate a method with the SCA @OneWay annotation. Note that the JAX-WS @Oneway annotation is also supported. It is important to note that asynchronous web services are fully interoperable with .NET: Fabric3 services may invoke .NET asynchronous services via a reference and WCF clients may invoke Fabric3 asynchronous services via a .NET "service reference".

Standard Web Services Policies

Fabric3 includes support for the following intents when configuring a service with the web services binding. Note, these intents are designed for interoperability with .NET (and other web services-based) clients:

The "sca:" prefix denotes the OASIS namespace, http://docs.oasis-open.org/ns/opencsa/sca/200903 and indicates the intent is part of the standard OASIS SCA intents. The "f3" intent denotes the Fabric3 policy namespace, "urn:fabric3.org".
At deployment, the intents will be mapped to Fabric3 defined policy sets, which will then be enabled on the deployed service. In addition, the policy sets will be attached to the generated service WSDL. The policy sets are defined using WS-Policy/WS-SecurityPolicy and are based on the Web Service Interoperability Group policy definitions (http://mssoapinterop.org/ilab/).

Configuring Policy on Services and References

Policy is configured on services or references (or on the containing component) using the SCA "requires" attribute to specify one or more intents (or policy sets). At deployment, Fabric3 will match configured intents to policy sets.

One important consideration when configuring policy is to account for interoperable attachment on services. Fabric3 will attach policy to a service WSDL based on where it is configured in a composite file or Java annotation. Specifically, if the "requires" attribute is specified on a service operation, it will be attached to the WSDL operation subject. However, if the WSDL is attached to the binding, service, or component definition, it will be attached to the WSDL binding subject. .NET (specifically Visual Studio and SvcUtil) follow WS-SecurityPolicy closely and will not recognize security policy attached to the WSDL operation subject. Consequently, for interoperability, it is import security intents and policy sets be configured on the binding, service or component.

Username/password Authentication

The following is an example of enabling username/password authentication on a service:

<component name="SecureService">
   <implementation.java class="..."/>
   <service name="SecureService">
      <binding.ws uri="/authenticationService" requires="sca:clientAuthentication.message"/>
   </service>
</component>

The above example will secure the web services endpoint with username/password authentication. During an invocation, Fabric3 will compare the username and password credentials against users configured through the security framework (see the security chapter for details on configuring users). It is also possible to perform authorization where only users with specific roles gain access to a service. To configure authorization, the @RolesAllowed intent attribute can be used on the SecureService implementation:

public class SecureServiceImpl implements SecureService {

    @RolesAllowed({"role1", "role2"})
    public void call() {
        //....
    }
}

References are configured to pass username/password information using the <configuration> element:

<binding.ws uri="https://www.foo.com/authenticationService" requires="sca:clientAuthentication.message">
   <configuration>
      <username>foo</username>
      <password>bar</password>
   </configuration>
</binding.ws>

X.509 Certificate-based Authentication

Using X.509-based authentication is similar to configuring username/password authentication:

<component name="SecureService">
   <implementation.java class="..."/>
   <service name="SecureService">
      *<binding.ws uri="/authenticationService" requires="f3:clientAuthentication.X509"/>*
   </service>
</component>

The above assumes a certificate store has been configured for Fabric3. For details on how to do this, see Chapter 8 on security. During an invocation, Fabric3 will match the certificate credential with one in the configured trust store.
References are configured to pass a certificate using the <configuration> element and the certificate alias:

<binding.ws uri="https://www.foo.com/authenticationService" requires="sca:clientAuthentication.message">
   <configuration>
      <alias>certAlias</alias>
    </configuration>
</binding.ws>

If no alias is specified, Fabric3 will attempt to use the default certificate, assuming the key store has only one certificate.

Configuring Connections

Outgoing reference connections can be configured for timeouts and chunking using the <configuration> element and the following sub-elements:

• connectTimeout - the time in milliseconds to wait when attempting to open a connection.
• requestTimeout - the time in milliseconds to wait for an HTTP response when making an invocation.
• clientStreamingChunkSize the chunking size to use in bytes

The following shows how to configure connection open and request timeouts:

<binding.ws uri="...">
   <configuration>
      <connectTimeout>10000</connectTimeout>
      <requestTimeout>10000</requestTimeout>
    </configuration>
</binding.ws>

The number of retries when a service is unavailable can be configured using the retries attribute:

<binding.ws uri="..." retries="1">
   <configuration>
      <connectTimeout>10000</connectTimeout>
      <requestTimeout>10000</requestTimeout>
    </configuration>
</binding.ws>

The above example will retry a request once if the first fails due to a connection timeout or service unavailable condition.

Debugging Options

To dump HTTP traffic to the console, set the following variable when starting the Fabric3 JVM:

-Dcom.sun.xml.ws.transport.http.client.HttpTransportPipe.dump=true