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.
About this task
This
task is a subtask of Creating 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:
- You cannot create highly available or workload
managed endpoint
references.
- You cannot create endpoint references that represent
stateful
session beans.
- You cannot use classes that are created by
using the JAX-WS API
with the IBM proprietary WS-Addressing SPI.
You 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. If you want 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.
- Create
an instance of the appropriate builder class. Use the W3CEndpointReferenceBuilder
class if you want to create
an endpoint reference that complies with the 2005/08 WS-Addressing
specification. Use the SubmissionEndpointReferenceBuilder class if
you want 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.
You 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.
Note: 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.
- 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 your application.
What to do next
- 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. You cannot set this property by 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 Creating a JAX-WS web service application that uses Web Services Addressing.