Create endpoint references using the IBM proprietary 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 IBM proprietary implementation of the WS-Addressing standard.

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

Complete this task if you are writing an application that uses the IBM proprietary WS-Addressing API. Such applications require endpoint references to target web service endpoints. When you are writing the application, you might not know the address of the endpoint, because the address can change when the application is deployed. By using the IBM proprietary API, we can either specify the endpoint address, or allow the product to generate it for you at run time.

We can also specify the behavior of endpoint references in a cluster environment.

To use endpoint reference objects from the standard JAX-WS API instead of the IBM proprietary equivalents, but want the extra functions provided by the IBM proprietary API, create the endpoint references by using the methods described in this task and then convert them by using the supplied converter classes. For example, you might want to undertake such a conversion if we have a JAX-WS service application and you are creating endpoint references that represent stateful session beans, or that have an affinity to a particular server, or are workload managed. We cannot create such endpoint references using the JAX-WS API.

• To create an endpoint reference with an address specified directly, use the WS-Addressing EndpointReferenceManager.createEndpointReference(URI address) method of the system programming interface (SPI) provided. This method is useful in test scenarios, where the address of the service does not change.

• To create an endpoint reference with an address that is automatically generated by the product...

  1. If we created the web service deployment descriptor file, webservices.xml, manually, ensure that the webservice-description-name in the file is the same as the local part of the Web Services Description Language (WSDL) service name. If we generated the webservices.xml file using the tools provided, the names match by default. This match is required for the generation of the correct URI for the endpoint reference.

  2. Create the endpoint reference using the method that is appropriate for the object that the reference will represent.

     • For an endpoint reference to represent a stateful session bean that maintains in-memory state, create the endpoint reference using the EndpointReferenceManager.createEndpointReference(QName serviceName, String endpointName, Remote statefulSessionBean) method of the (API) provided. This method ensures that requests are targeted at the specific server that hosts the stateful session bean instance, and are not workload-managed.

       Also, if high availability for stateful session beans is specified, the endpoint reference remains valid even if the stateful session bean is failed over.

       If the statefulSessionBean parameter is null, requests are targeted directly at the server that hosts the endpoint and are not workload-managed, but there is no stateful session bean failover capability.

       Note: Affinity to stateful session beans that use this method is not supported on the z/OS operating system. If a highly available stateful session bean fails over to another control region, or is passivated from one servant region and reactivated on another servant region in the same control region, the endpoint reference is no longer valid. To achieve affinity with a stateful session bean, run the application in a transaction to use transactional context affinity, or use HTTP session affinity.

     • For an endpoint reference to represent any other object, create the endpoint reference using the EndpointReferenceManager.createEndpointReference(QName serviceName, String endpointName) method of the API. The combination of service name and endpoint name must be unique in the server. If there is more than one web service application with the same service name and endpoint name, the application server cannot generate a unique URI object for the endpoint. If we cannot ensure that the combination of service name and endpoint name is unique, use an SPI method to create the endpoint reference.

       Because the endpoint reference might be workload-managed at a later date, ensure that the endpoint does not contain any in-memory state. For JAX-WS applications, we can prevent the endpoint reference from being workload-managed by attaching a WS-Addressing policy set to the application and configuring the policy set binding to prevent the workload management of referenced endpoints in clusters.

       We can use the EndpointReferenceManager.createEndpointReference(QName serviceName, String endpointName) method to create an endpoint reference for any endpoint reference in the application server. This behavior differs from that of the JAX-WS API, where creating an endpoint reference using the service name and endpoint name is restricted to endpoints within the same Java EE application.

     When the application invokes either of the previous two methods, the product generates the address URI for the endpoint reference, and puts the service name and endpoint name into the metadata of the newly created endpoint reference.

     If you configured a virtual host for the server on which the endpoint is created, the URI of the endpoint reference refers to the virtual host of the HTTP server configuration. We can use the administrative console to override this setting and provide our own HTTP endpoint URL information. The methods described previously will use the overridden value to generate the address URI for the endpoint reference.

Results

We created an endpoint reference for use by the application.

What to do next

1. To convert the endpoint references from IBM proprietary WS-Addressing objects to standard JAX-WS WS-Addressing objects, use one of the following methods of the com.ibm.websphere.wsaddressing.jaxws21.EndpointReferenceConverter class, depending on the namespace of the endpoint reference:

   • createW3CEndpointReference(EndpointReference epr): use this method if the EndpointReference object uses the 2005/08 specification. This method creates a W3CEndpointReference object.

   • createSubmissionEndpointReference(EndpointReference epr): use this method if the EndpointReference object uses the 2004/08 specification. This method creates a SubmissionEndpointReference object.

2. Continue with Create a JAX-RPC web service application that uses Web Services Addressing, or if you converted the endpoint reference to the standard JAX-WS API, continue with Create a JAX-WS web service application that uses Web Services Addressing.

Related concepts

Web Services Addressing: firewalls and intermediary nodes

Memory-to-memory replication

Related tasks

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

Manage policy sets using the administrative console

Stateful session beans failover settings (applications)

Stateful session beans failover settings (EJB modules)

Provide HTTP endpoint URL information

Related information:

Web Services Addressing policy set binding