Create endpoint references using the JAX-WS 2.1 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 using the standard JAX-WS 2.1 API.

This task is a subtask of Create a JAX-WS Web service application that uses Web Services Addressing. Perform this task if we are writing an application that uses the standard JAX-WS 2.1 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 created using the JAX-WS 2.1 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 2.1 endpoint references that can be used by the rest of the application. Refer to Create endpoint references using the JAX-WS 2.1 Web Services Addressing API for instructions.

Endpoint references that are created using this API contain metadata that complies with the WS-Addressing 1.0 Metadata specification. This behavior is not a requirement of the JAX-WS 2.1 specification, so endpoint references created using vendor software might contain metadata that complies with a different specification. This difference could cause problems if we are interoperating with an application created using vendor software.

 

• 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 we 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 that you want 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 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. 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 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.

  3. 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.

     See on the properties that we can set, see the API documentation.

  4. 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 module in this 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(calculatorServiceURI);
  
          
  // 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 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.

 

Next steps

1. If required, convert the endpoint reference to an instance of the com.ibm.websphere.wsaddressing.EndpointReference class, using the createIBMEndpointReference method. For example, on a client we might want to set the FaultTo message addressing property for outbound messages. We cannot set this property using the JAX-WS 2.1 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.

 

Related concepts

Web Services Addressing: firewalls and intermediary nodes
IBM proprietary Web Services Addressing SPIs

 

Related tasks

Create endpoint references using the JAX-WS 2.1 Web Services Addressing API
Create a JAX-WS Web service application that uses Web Services Addressing

 

Related information

Additional Application Programming Interfaces (APIs)