Network Deployment (Distributed operating systems), v8.0 > Develop and deploying applications > Develop web services - Addressing (WS-Addressing) > Use the Web Services Addressing APIs: Creating an application that uses endpoint references > Create a JAX-WS web service application that uses Web Services Addressing

Create endpoint references by using the JAX-WS Web Services Addressing API

Endpoint references are a primary concept of the Web Services Addressing (WS-Addressing) interoperability protocol, and provide a standard mechanism to encapsulate information about specific web service endpoints. This product provides interfaces for you to create endpoint references by using the standard JAX-WS API.

This task is a subtask of Create a JAX-WS web service application that uses Web Services Addressing.

Complete this task if you are writing an application that uses the standard JAX-WS WS-Addressing API. Such applications require endpoint references to target web service endpoints. The standard JAX-WS API is designed to create only simple endpoint references, and therefore has the following restrictions:

• We cannot create highly available or workload managed endpoint references.
• We cannot create endpoint references that represent stateful session beans.
• We cannot use classes that are created by using the JAX-WS API with the IBM proprietary WS-Addressing SPI.

We can overcome these restrictions by using the IBM proprietary WS-Addressing API to create the endpoint references and then converting them into standard JAX-WS endpoint references that can be used by the rest of the application.

Procedure

• If an endpoint needs to create an endpoint reference that represents itself, use the getEndpointReference method of the web service context object, passing in an Element object representing the reference parameters to be associated with the endpoint reference (or a null object if you do not want to specify any reference parameters).

  By default, this method creates a W3CEndpointReference object. To create a SubmissionEndpointReference object, representing an endpoint that conforms to the 2004/08 WS-Addressing specification, pass the endpoint reference type as a parameter. For example, the following code fragment uses the getEndpointReference method to return a W3CEndpointRerence object that has a ticket ID associated with it:

  ...
  @WebService(name="Calculator",
              targetNamespace="http://calculator.org")
  
  public class Calculator {
      @Resource
      WebServiceContext wsc;
  
      ...
      // Create the ticket id
      element = document.createElementNS(
                         "http://calculator.jaxws.axis2.apache.org", "TicketId");
      element.appendChild( document.createTextNode("123456789") );
      ...
  
      public W3CEndpointReference getEPR() {
          // Get the endpoint reference and associate the ticket id
          // with it as a reference parameter
  W3CEndpointReference epr = (W3CEndpointReference)wsc.getEndpointReference(element);
  
          return epr;
      }
  ...
  
  

  The following line of code shows how to create a 2004/08 endpoint reference for the preceding sample:

  SubmissionEndpointReference epr = (SubmissionEndpointReference)
          wsc.getEndpointReference(SubmissionEndpointReference.class, element);
  

• If an endpoint needs to create an endpoint reference that represents a different endpoint, use either the W3CEndpointReferenceBuilder class or the SubmissionEndpointReferenceBuilder class, depending on the namespace to use.

  1. Create an instance of the appropriate builder class. Use the W3CEndpointReferenceBuilder class to create an endpoint reference that complies with the 2005/08 WS-Addressing specification. Use the SubmissionEndpointReferenceBuilder class if to create an endpoint reference that complies with the 2004/08 WS-Addressing specification.

  2. Set the following property or properties of the builder instance according to the location of the endpoint.

     • If the endpoint is in another module in this application, set the serviceName and endpointName properties to appropriate values. We must set the serviceName property before you set the endpointName property, otherwise the application throws an error. The endpoint reference that is returned contains a suitable address for the endpoint, as determined by the implementation.

       This behavior differs from the IBM WS-Addressing API, in that creating an endpoint reference using the com.ibm.websphere.wsaddressing.EndpointReferenceManager.createEndpointReference(QName serviceName, String endpointName) method is not restricted to endpoints in the same application.

     • If the endpoint is in another Java EE application, set the address property to point to the endpoint.

     Optional. Set other properties of the builder instance as required. For example, if the web service is used to access a resource instance, use the referenceParameter property to associate the identifier of the resource with the endpoint reference. For more information on the properties that you can set, see the API documentation.

  3. Invoke the build method on the builder instance to obtain the endpoint reference.

  For example, the following code fragment uses the W3CEndpointReferenceBuilder class to obtain an endpoint reference that complies with the 2005/08 specification, and points to an endpoint that is in another application:

  ...
  @WebService(name="Calculator", targetNamespace="http://calculator.org")
  public class Calculator {
  
      public W3CEndpointReference getEPR() {
          ...
          // Create the builder object
  W3CEndpointReferenceBuilder builder = new
                                 W3CEndpointReferenceBuilder();
  
          // Modify builder properties
  builder.address(otherServiceURI);
  
          // Create the endpoint reference from the builder object
  W3CEndpointReference epr = builder.build();
          return epr;
      }
  ...
  
  

  The following code fragment uses the SubmissionEndpointReferenceBuilder class to obtain an endpoint reference that complies with the 2004/08 specification, and points to an endpoint that is in another module in this application:

  ...
  @WebService(name="Calculator", targetNamespace="http://calculator.org")
  public class Calculator {
  
      public W3CEndpointReference getEPR() {
          ...
          // Create the builder object
  SubmissionEndpointReferenceBuilder builder = new
                             SubmissionEndpointReferenceBuilder();
  
          // Modify builder properties
  builder.serviceName(calculatorService);
          builder.endpointName(calculatorPort);
  
          // Create the endpoint reference from the builder object
  SubmissionEndpointReference epr = builder.build();
          return epr;
      }
  ...
  
  

Results

You created an endpoint reference for use by the application.

What to do next

1. If required, convert the endpoint reference to an instance of the com.ibm.websphere.wsaddressing.EndpointReference class, by using the createIBMEndpointReference method. For example, on a client you might want to set the FaultTo message addressing property for outbound messages. We cannot set this property by using the JAX-WS API, so convert the endpoint reference representing the FaultTo endpoint to an instance of the com.ibm.websphere.wsaddressing.EndpointReference class, before setting it as a property on the BindingProvider object.
2. Continue with Create a JAX-WS web service application that uses Web Services Addressing.

Web Services Addressing: firewalls and intermediary nodes
IBM proprietary Web Services Addressing SPIs
Create endpoint references by using the JAX-WS Web Services Addressing API
Create a JAX-WS web service application that uses Web Services Addressing
Additional Application Programming Interfaces (APIs)

+

Search Tips   |   Advanced Search