com.sun.xml.ws.api.message
Class Packet

java.lang.Object
  extended by com.sun.xml.ws.api.PropertySet
      extended by com.sun.xml.ws.api.DistributedPropertySet
          extended by com.sun.xml.ws.api.message.Packet

public final class Packet
extends DistributedPropertySet

Represents a container of a Message.

What is a Packet?

A packet can be thought of as a frame/envelope/package that wraps a Message. A packet keeps track of optional metadata (properties) about a Message that doesn't go across the wire. This roughly corresponds to MessageContext in the JAX-WS API.

Usually a packet contains a Message in it, but sometimes (such as for a reply of an one-way operation), a packet may float around without a Message in it.

Properties

Information frequently used inside the JAX-WS RI is stored in the strongly-typed fields. Other information is stored in terms of a generic Map (see invocationProperties.)

Some properties need to be retained between request and response, some don't. For strongly typed fields, this characteristic is statically known for each of them, and propagation happens accordingly. For generic information stored in Map, invocationProperties stores per-invocation scope information (which carries over to the response.)

This object is used as the backing store of MessageContext, and LogicalMessageContext and SOAPMessageContext will be delegating to this object for storing/retrieving values.

Relationship to request/response context

Request context is used to seed the initial values of Packet. Some of those values go to strongly-typed fields, and others go to invocationProperties, as they need to be retained in the reply message.

Similarly, response context is constructed from Packet (or rather it's just a view of Packet.) by using properties from invocationProperties, modulo properties named explicitly in getHandlerScopePropertyNames(boolean). IOW, properties added to invocationProperties are exposed to the response context by default.

TODO

  1. this class needs to be cloneable since Message is copiable.
  2. The three live views aren't implemented correctly. It will be more work to do so, although I'm sure it's possible.
  3. Property annotation is to make it easy for MessageContext to export properties on this object, but it probably needs some clean up.


Nested Class Summary
 
Nested classes/interfaces inherited from class com.sun.xml.ws.api.PropertySet
PropertySet.Accessor, PropertySet.Property, PropertySet.PropertyMap
 
Field Summary
 String acceptableMimeTypes
          The list of MIME types that are acceptable to a receiver of an outbound message.
 ContentNegotiation contentNegotiation
          The value of ContentNegotiation.PROPERTY property.
 WSEndpoint endpoint
          The governing WSEndpoint in which this message is floating.
 EndpointAddress endpointAddress
          The endpoint address to which this message is sent to.
 Boolean expectReply
          A hint indicating that whether a transport should expect a reply back from the server.
 HandlerConfiguration handlerConfig
          This property holds the snapshot of HandlerConfiguration at the time of invocation.
static String INBOUND_TRANSPORT_HEADERS
          Inbound transport headers are captured in a transport neutral way.
 Map<String,Object> invocationProperties
          Bag to capture properties that are available for the whole message invocation (namely on both requests and responses.)
 Boolean isOneWay
          Deprecated. 
static String OUTBOUND_TRANSPORT_HEADERS
          Outbound transport headers are captured in a transport neutral way.
 javax.xml.ws.BindingProvider proxy
          If a message originates from a proxy stub that implements a port interface, this field is set to point to that object.
 String soapAction
          The value of the SOAPAction header associated with the message.
 TransportBackChannel transportBackChannel
          Used only on the server side so that the transport can close the connection early.
 boolean wasTransportSecure
          True if this message came from a transport (IOW inbound), and in paricular from a "secure" transport.
 WebServiceContextDelegate webServiceContextDelegate
          When non-null, this object is consulted to implement WebServiceContext methods exposed to the user application.
 
Constructor Summary
Packet()
          Creates an empty Packet that doesn't have any Message.
Packet(Message request)
          Creates a Packet that wraps a given Message.
 
Method Summary
 Packet createClientResponse(Message msg)
          Creates a response Packet from a request packet (this).
 Packet createResponse(Message msg)
          Deprecated. Use createClientResponse(Message) for client side and createServerResponse(Message, String) for server side response creation.
 Packet createServerResponse(Message responseMessage, AddressingVersion addressingVersion, SOAPVersion soapVersion, String action)
          Creates a server-side response Packet from a request packet (this).
 Packet createServerResponse(Message responseMessage, WSDLPort wsdlPort, SEIModel seiModel, WSBinding binding)
          Creates a server-side response Packet from a request packet (this).
 Set<String> getApplicationScopePropertyNames(boolean readOnly)
          Deprecated. Use getHandlerScopePropertyNames(boolean). To be removed once Tango components are updated.
 String getContentNegotiationString()
           
 String getEndPointAddressString()
          Deprecated. The programatic acccess should be done via endpointAddress. This is for JAX-WS client applications that access this property via BindingProvider.ENDPOINT_ADDRESS_PROPERTY.
 Set<String> getHandlerScopePropertyNames(boolean readOnly)
          Gets a Set that stores handler-scope properties.
(package private)  HeaderList getHeaderList()
          Deprecated. This method is for exposing header list through PropertySet.get(Object), for user applications, and should never be invoked directly from within the JAX-WS RI.
 Message getMessage()
          Gets the last Message set through setMessage(Message).
protected  PropertySet.PropertyMap getPropertyMap()
          Map representing the Fields and Methods annotated with PropertySet.Property.
 List<Element> getReferenceParameters()
          Gives a list of Reference Parameters in the Message
 void setContentNegotiationString(String s)
           
 void setEndPointAddressString(String s)
           
 void setMessage(Message message)
          Sets a Message to this packet.
 
Methods inherited from class com.sun.xml.ws.api.DistributedPropertySet
addSatellite, copySatelliteInto, get, put, remove, removeSatellite, supports
 
Methods inherited from class com.sun.xml.ws.api.PropertySet
containsKey, createMapView, parse
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

wasTransportSecure

public boolean wasTransportSecure
True if this message came from a transport (IOW inbound), and in paricular from a "secure" transport. A transport needs to set this flag appropriately.

This is a requirement from the security team.


INBOUND_TRANSPORT_HEADERS

public static final String INBOUND_TRANSPORT_HEADERS
Inbound transport headers are captured in a transport neutral way. Transports are expected to fill this data after creating a Packet.

SOAPMessage.getMimeHeaders() would return these headers.

See Also:
Constant Field Values

OUTBOUND_TRANSPORT_HEADERS

public static final String OUTBOUND_TRANSPORT_HEADERS
Outbound transport headers are captured in a transport neutral way.

Transports may choose to ignore certain headers that interfere with its correct operation, such as Content-Type and Content-Length.

See Also:
Constant Field Values

handlerConfig

public HandlerConfiguration handlerConfig
This property holds the snapshot of HandlerConfiguration at the time of invocation. This property is used by MUPipe and HandlerPipe implementations.


proxy

public javax.xml.ws.BindingProvider proxy
If a message originates from a proxy stub that implements a port interface, this field is set to point to that object. TODO: who's using this property?


endpointAddress

public EndpointAddress endpointAddress
The endpoint address to which this message is sent to.

The JAX-WS spec allows this to be changed for each message, so it's designed to be a property.

Must not be null for a request message on the client. Otherwise it's null.


contentNegotiation

public ContentNegotiation contentNegotiation
The value of ContentNegotiation.PROPERTY property. This property is used only on the client side.


acceptableMimeTypes

public String acceptableMimeTypes
The list of MIME types that are acceptable to a receiver of an outbound message. This property is used only on the server side.

The representation shall be that specified by the HTTP Accept request-header field.

The list of content types will be obtained from the transport meta-data of a inbound message in a request/response message exchange. Hence this property will be set by the service-side transport pipe.


webServiceContextDelegate

public WebServiceContextDelegate webServiceContextDelegate
When non-null, this object is consulted to implement WebServiceContext methods exposed to the user application. Used only on the server side.

This property is set from the parameter of WSEndpoint.PipeHead#process.


transportBackChannel

@Nullable
public TransportBackChannel transportBackChannel
Used only on the server side so that the transport can close the connection early.

This field can be null. While a message is being processed, this field can be set explicitly to null, to prevent future pipes from closing a transport.

This property is set from the parameter of WSEndpoint.PipeHead#process.


endpoint

public WSEndpoint endpoint
The governing WSEndpoint in which this message is floating.

This property is set if and only if this is on the server side.


soapAction

public String soapAction
The value of the SOAPAction header associated with the message.

For outgoing messages, the transport may sends out this value. If this field is null, the transport may choose to send "" (quoted empty string.) For incoming messages, the transport will set this field. If the incoming message did not contain the SOAPAction header, the transport sets this field to null.

If the value is non-null, it must be always in the quoted form. The value can be null.

Note that the way the transport sends this value out depends on transport and SOAP version. For HTTP transport and SOAP 1.1, BP requires that SOAPAction header is present (See and .) For SOAP 1.2, this is moved to the parameter of the "application/soap+xml".


expectReply

public Boolean expectReply
A hint indicating that whether a transport should expect a reply back from the server.

This property is used on the client-side for outbound messages, so that a pipeline can communicate to the terminal (or intermediate) Tubes about this knowledge.

This property MUST NOT be used by 2-way transports that have the transport back channel. Those transports must always check a reply coming through the transport back channel regardless of this value, and act accordingly. (This is because the expectation of the client and that of the server can be different, for example because of a bug in user's configuration.)

This property is for one-way transports, and more specifically for the coordinator that correlates sent requests and incoming replies, to decide whether to block until a response is received.

Also note that this property is related to WSDLOperation.isOneWay() but not the same thing. In fact in general, they are completely orthogonal. For example, the calling application can choose to invoke Dispatch.invoke(Object) or Dispatch.invokeOneWay(Object) with an operation (which determines the value of this property), regardless of whether WSDL actually says it's one way or not. So these two booleans can take any combinations.

When this property is Boolean.TRUE, it means that the pipeline does not expect a reply from a server (and therefore the correlator should not block for a reply message -- if such a reply does arrive, it can be just ignored.)

When this property is Boolean.FALSE, it means that the pipeline expects a reply from a server (and therefore the correlator should block to see if a reply message is received,

This property is always set to Boolean.TRUE or Boolean.FALSE when used on the request message on the client side. No other Boolean instances are allowed.

In all other situations, this property is null.


isOneWay

@Deprecated
public Boolean isOneWay
Deprecated. 
This property will be removed in a near future.

A part of what this flag represented moved to expectReply and the other part was moved to Message.isOneWay(WSDLPort). Please update your code soon, or risk breaking your build!!


invocationProperties

public final Map<String,Object> invocationProperties
Bag to capture properties that are available for the whole message invocation (namely on both requests and responses.)

These properties are copied from a request to a response. This is where we keep properties that are set by handlers.

See class javadoc for more discussion.

See Also:
getHandlerScopePropertyNames(boolean)
Constructor Detail

Packet

public Packet(Message request)
Creates a Packet that wraps a given Message.

This method should be only used to create a fresh Packet. To create a Packet for a reply, use createResponse(Message).

Parameters:
request - The request Message. Can be null.

Packet

public Packet()
Creates an empty Packet that doesn't have any Message.

Method Detail

getMessage

public Message getMessage()
Gets the last Message set through setMessage(Message).

Returns:
may null. See the class javadoc for when it's null.

setMessage

public void setMessage(Message message)
Sets a Message to this packet.

Parameters:
message - Can be null.

getEndPointAddressString

public String getEndPointAddressString()
Deprecated. The programatic acccess should be done via endpointAddress. This is for JAX-WS client applications that access this property via BindingProvider.ENDPOINT_ADDRESS_PROPERTY.


setEndPointAddressString

public void setEndPointAddressString(String s)

getContentNegotiationString

public String getContentNegotiationString()

setContentNegotiationString

public void setContentNegotiationString(String s)

getReferenceParameters

@NotNull
public List<Element> getReferenceParameters()
Gives a list of Reference Parameters in the Message

Headers which have attribute wsa:IsReferenceParameter="true" This is not cached as one may reset the Message.


getHeaderList

HeaderList getHeaderList()
Deprecated. This method is for exposing header list through PropertySet.get(Object), for user applications, and should never be invoked directly from within the JAX-WS RI.


getHandlerScopePropertyNames

public final Set<String> getHandlerScopePropertyNames(boolean readOnly)
Gets a Set that stores handler-scope properties.

These properties will not be exposed to the response context. Consequently, if a Tube wishes to hide a property to ResponseContext, it needs to add the property name to this set.

Parameters:
readOnly - Return true if the caller only intends to read the value of this set. Internally, the Set is allocated lazily, and this flag helps optimizing the strategy.
Returns:
always non-null, possibly empty set that stores property names.

getApplicationScopePropertyNames

public final Set<String> getApplicationScopePropertyNames(boolean readOnly)
Deprecated. Use getHandlerScopePropertyNames(boolean). To be removed once Tango components are updated.

This method no longer works.


createResponse

@Deprecated
public Packet createResponse(Message msg)
Deprecated. Use createClientResponse(Message) for client side and createServerResponse(Message, String) for server side response creation.

Creates a response Packet from a request packet (this).

When a Packet for a reply is created, some properties need to be copied over from a request to a response, and this method handles it correctly.

Parameters:
msg - The Message that represents a reply. Can be null.

createClientResponse

public Packet createClientResponse(Message msg)
Creates a response Packet from a request packet (this).

When a Packet for a reply is created, some properties need to be copied over from a request to a response, and this method handles it correctly.

Parameters:
msg - The Message that represents a reply. Can be null.

createServerResponse

public Packet createServerResponse(@Nullable
                                   Message responseMessage,
                                   @Nullable
                                   WSDLPort wsdlPort,
                                   @Nullable
                                   SEIModel seiModel,
                                   @NotNull
                                   WSBinding binding)
Creates a server-side response Packet from a request packet (this). If WS-Addressing is enabled, a default Action Message Addressing Property is obtained using wsdlPort WSDLPort and binding WSBinding.

This method should be called to create application response messages since they are associated with a WSBinding and WSDLPort. For creating protocol messages that require a non-default Action, use createServerResponse(Message, com.sun.xml.ws.api.addressing.AddressingVersion, com.sun.xml.ws.api.SOAPVersion, String).

Parameters:
responseMessage - The Message that represents a reply. Can be null.
wsdlPort - The response WSDL port.
binding - The response Binding. Cannot be null.
Returns:
response packet

createServerResponse

public Packet createServerResponse(@Nullable
                                   Message responseMessage,
                                   @NotNull
                                   AddressingVersion addressingVersion,
                                   @NotNull
                                   SOAPVersion soapVersion,
                                   @NotNull
                                   String action)
Creates a server-side response Packet from a request packet (this). If WS-Addressing is enabled, action is used as Action Message Addressing Property.

This method should be called only for creating protocol response messages that require a particular value of Action since they are not associated with a WSBinding and WSDLPort but do know the AddressingVersion and SOAPVersion.

Parameters:
responseMessage - The Message that represents a reply. Can be null.
addressingVersion - The WS-Addressing version of the response message.
soapVersion - The SOAP version of the response message.
action - The response Action Message Addressing Property value.
Returns:
response packet

getPropertyMap

protected PropertySet.PropertyMap getPropertyMap()
Description copied from class: PropertySet
Map representing the Fields and Methods annotated with PropertySet.Property. Model of PropertySet class.

At the end of the derivation chain this method just needs to be implemented as:

 private static final PropertyMap model;
 static {
   model = parse(MyDerivedClass.class);
 }
 protected PropertyMap getPropertyMap() {
   return model;
 }
 

Specified by:
getPropertyMap in class PropertySet