com.sun.xml.ws.client
Class Stub

java.lang.Object
  extended by com.sun.xml.ws.client.Stub
All Implemented Interfaces:
ResponseContextReceiver, WSBindingProvider, Closeable, javax.xml.ws.BindingProvider
Direct Known Subclasses:
DispatchImpl, SEIStub

public abstract class Stub
extends Object
implements WSBindingProvider, ResponseContextReceiver

Base class for stubs, which accept method invocations from client applications and pass the message to a Tube for processing.

This class implements the management of pipe instances, and most of the BindingProvider methods.


Field Summary
protected  AddressingVersion addrVersion
          represents AddressingVersion on binding if enabled, otherwise null;
protected  BindingImpl binding
           
protected  WSEndpointReference endpointReference
          Non-null if this stub is configured to talk to an EPR.
protected  WSServiceDelegate owner
          The WSServiceDelegate object that owns us.
 RequestContext requestContext
           
protected  WSDLPort wsdlPort
           
 
Fields inherited from interface javax.xml.ws.BindingProvider
ENDPOINT_ADDRESS_PROPERTY, PASSWORD_PROPERTY, SESSION_MAINTAIN_PROPERTY, SOAPACTION_URI_PROPERTY, SOAPACTION_USE_PROPERTY, USERNAME_PROPERTY
 
Constructor Summary
protected Stub(WSServiceDelegate owner, Tube master, BindingImpl binding, WSDLPort wsdlPort, EndpointAddress defaultEndPointAddress, WSEndpointReference epr)
           
 
Method Summary
 void close()
           
 WSBinding getBinding()
           
 javax.xml.ws.wsaddressing.W3CEndpointReference getEndpointReference()
           
<T extends javax.xml.ws.EndpointReference>
T
getEndpointReference(Class<T> clazz)
           
 Executor getExecutor()
          Gets the Executor to be used for asynchronous method invocations.
 List<Header> getInboundHeaders()
           
protected abstract  QName getPortName()
          Gets the port name that this stub is configured to talk to.
 Map<String,Object> getRequestContext()
           
 ResponseContext getResponseContext()
           
protected  QName getServiceName()
          Gets the service name that this stub is configured to talk to.
protected  Packet process(Packet packet, RequestContext requestContext, ResponseContextReceiver receiver)
          Passes a message to a pipe for processing.
protected  void processAsync(Packet request, RequestContext requestContext, Fiber.CompletionCallback completionCallback)
          Passes a message through a Tubeline for processing.
 void setAddress(String address)
          Sets the endpoint address for all the invocations that happen from BindingProvider.
 void setOutboundHeaders(Header... headers)
          Sets the out-bound headers to be added to messages sent from this BindingProvider.
 void setOutboundHeaders(List<Header> headers)
          Sets the out-bound headers to be added to messages sent from this BindingProvider.
 void setResponseContext(ResponseContext rc)
          Called upon the completion of the invocation to set a ResponseContext.
 String toString()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface com.sun.xml.ws.developer.WSBindingProvider
setOutboundHeaders
 

Field Detail

owner

protected final WSServiceDelegate owner
The WSServiceDelegate object that owns us.


endpointReference

@Nullable
protected final WSEndpointReference endpointReference
Non-null if this stub is configured to talk to an EPR.

When this field is non-null, its reference parameters are sent as out-bound headers. This field can be null even when addressing is enabled, but if the addressing is not enabled, this field must be null.

Unlike endpoint address, we are not letting users to change the EPR, as it contains references to services and so on that we don't want to change.


binding

protected final BindingImpl binding

addrVersion

protected final AddressingVersion addrVersion
represents AddressingVersion on binding if enabled, otherwise null;


requestContext

public final RequestContext requestContext

wsdlPort

@Nullable
protected final WSDLPort wsdlPort
Constructor Detail

Stub

protected Stub(WSServiceDelegate owner,
               Tube master,
               BindingImpl binding,
               WSDLPort wsdlPort,
               EndpointAddress defaultEndPointAddress,
               @Nullable
               WSEndpointReference epr)
Parameters:
master - The created stub will send messages to this pipe.
binding - As a BindingProvider, this object will return this binding from BindingProvider.getBinding().
defaultEndPointAddress - The destination of the message. The actual destination could be overridden by RequestContext.
epr - To create a stub that sends out reference parameters of a specific EPR, give that instance. Otherwise null. Its address field will not be used, and that should be given separately as the defaultEndPointAddress.
Method Detail

getPortName

@NotNull
protected abstract QName getPortName()
Gets the port name that this stub is configured to talk to.

When wsdlPort is non-null, the port name is always the same as WSDLPort.getName(), but this method returns a port name even if no WSDL is available for this stub.


getServiceName

@NotNull
protected final QName getServiceName()
Gets the service name that this stub is configured to talk to.

When wsdlPort is non-null, the service name is always the same as the one that's inferred from WSDLPort.getOwner(), but this method returns a port name even if no WSDL is available for this stub.


getExecutor

public final Executor getExecutor()
Gets the Executor to be used for asynchronous method invocations.

Note that the value this method returns may different from invocations to invocations. The caller must not cache.

Returns:
always non-null.

process

protected final Packet process(Packet packet,
                               RequestContext requestContext,
                               ResponseContextReceiver receiver)
Passes a message to a pipe for processing.

Unlike Tube instances, this method is thread-safe and can be invoked from multiple threads concurrently.

Parameters:
packet - The message to be sent to the server
requestContext - The RequestContext when this invocation is originally scheduled. This must be the same object as requestContext for synchronous invocations, but for asynchronous invocations, it needs to be a snapshot captured at the point of invocation, to correctly satisfy the spec requirement.
receiver - Receives the ResponseContext. Since the spec requires that the asynchronous invocations must not update response context, depending on the mode of invocation they have to go to different places. So we take a setter that abstracts that away.

processAsync

protected final void processAsync(Packet request,
                                  RequestContext requestContext,
                                  Fiber.CompletionCallback completionCallback)
Passes a message through a Tubeline for processing. The processing happens asynchronously and when the response is available, Fiber.CompletionCallback is called. The processing could happen on multiple threads.

Unlike Tube instances, this method is thread-safe and can be invoked from multiple threads concurrently.

Parameters:
request - The message to be sent to the server
requestContext - The RequestContext when this invocation is originally scheduled. This must be the same object as requestContext for synchronous invocations, but for asynchronous invocations, it needs to be a snapshot captured at the point of invocation, to correctly satisfy the spec requirement.
completionCallback - Once the processing is done, the callback is invoked.

close

public void close()
Specified by:
close in interface Closeable

getBinding

public final WSBinding getBinding()
Specified by:
getBinding in interface javax.xml.ws.BindingProvider

getRequestContext

public final Map<String,Object> getRequestContext()
Specified by:
getRequestContext in interface javax.xml.ws.BindingProvider

getResponseContext

public final ResponseContext getResponseContext()
Specified by:
getResponseContext in interface javax.xml.ws.BindingProvider

setResponseContext

public void setResponseContext(ResponseContext rc)
Description copied from interface: ResponseContextReceiver
Called upon the completion of the invocation to set a ResponseContext.

This method is invoked even when the invocation fails.

Specified by:
setResponseContext in interface ResponseContextReceiver

toString

public String toString()
Overrides:
toString in class Object

getEndpointReference

public final javax.xml.ws.wsaddressing.W3CEndpointReference getEndpointReference()
Specified by:
getEndpointReference in interface javax.xml.ws.BindingProvider

getEndpointReference

public final <T extends javax.xml.ws.EndpointReference> T getEndpointReference(Class<T> clazz)
Specified by:
getEndpointReference in interface javax.xml.ws.BindingProvider

setOutboundHeaders

public final void setOutboundHeaders(List<Header> headers)
Description copied from interface: WSBindingProvider
Sets the out-bound headers to be added to messages sent from this BindingProvider.

Calling this method would discard any out-bound headers that were previously set.

A new Header object can be created by using one of the methods on Headers.

Specified by:
setOutboundHeaders in interface WSBindingProvider
Parameters:
headers - The headers to be added to the future request messages. To clear the outbound headers, pass in either null or empty list.

setOutboundHeaders

public final void setOutboundHeaders(Header... headers)
Description copied from interface: WSBindingProvider
Sets the out-bound headers to be added to messages sent from this BindingProvider.

Works like WSBindingProvider.setOutboundHeaders(List) except that it accepts a var arg array.

Specified by:
setOutboundHeaders in interface WSBindingProvider
Parameters:
headers - Can be null or empty.

getInboundHeaders

public final List<Header> getInboundHeaders()
Specified by:
getInboundHeaders in interface WSBindingProvider

setAddress

public final void setAddress(String address)
Description copied from interface: WSBindingProvider
Sets the endpoint address for all the invocations that happen from BindingProvider. Instead of doing the following

((BindingProvider)proxy).getRequestContext().put( BindingProvider.ENDPOINT_ADDRESS_PROPERTY, "...")

you could do this:

((WSBindingProvider)proxy).setAddress("...");

Specified by:
setAddress in interface WSBindingProvider
Parameters:
address - Address of the service