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

WAS v8.5 > Develop 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 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. WAS v8.5 provides interfaces for you to create endpoint references 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 created using the JAX-WS API with the IBM proprietary WS-Addressing SPI.
We can overcome these restrictions 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.
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 to use.

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.
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 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 we can set, see the API documentation.
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
We created an endpoint reference for use by the application.

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 you might want to set the FaultTo message addressing property for outbound messages. We cannot set this property using the JAX-WS API, so you must 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.
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

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

Related information:

Additional Application Programming Interfaces (APIs)

+
Search Tips | Advanced Search