| java.lang.Object
 com.sun.xml.ws.api.PropertySet
com.sun.xml.ws.api.DistributedPropertySet
com.sun.xml.ws.api.message.Packet
| Packet | | final public class Packet extends DistributedPropertySet (Code) | | Represents a container of a
Message .
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
Packet.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 ,
Packet.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
BindingProvider.getRequestContext Request context is used to
seed the initial values of
Packet .
Some of those values go to strongly-typed fields, and others go to
Packet.invocationProperties , as they need to be retained in the reply message.
Similarly,
BindingProvider.getResponseContext response context is constructed from
Packet (or rather it's just a view of
Packet .)
by using properties from
Packet.invocationProperties ,
modulo properties named explicitly in
Packet.getHandlerScopePropertyNames(boolean) .
IOW, properties added to
Packet.invocationProperties are exposed to the response context by default.
TODO
- this class needs to be cloneable since Message is copiable.
- The three live views aren't implemented correctly. It will be
more work to do so, although I'm sure it's possible.
-
Property annotation is to make it easy
for
MessageContext to export properties on this object,
but it probably needs some clean up.
author:
Kohsuke Kawaguchi |
| Method Summary | |
| 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. | | public Packet | createResponse(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. | | public Packet | createServerResponse(Message responseMessage, WSDLPort wsdlPort, SEIModel seiModel, WSBinding binding)
Creates a server-side response
Packet from a request
packet (
this ). | | public Packet | createServerResponse(Message responseMessage, AddressingVersion addressingVersion, SOAPVersion soapVersion, String action)
Creates a server-side response
Packet from a request
packet (
this ). | | final public Set<String> | getApplicationScopePropertyNames(boolean readOnly)
This method no longer works. | | public String | getContentNegotiationString()
| | public String | getEndPointAddressString()
| | final public Set<String> | getHandlerScopePropertyNames(boolean readOnly)
Gets a
Set that stores handler-scope properties. | | HeaderList | getHeaderList()
| | public Message | getMessage()
Gets the last
Message set through
Packet.setMessage(Message) .
may null. | | protected PropertyMap | getPropertyMap()
| | 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. | | public void | setContentNegotiationString(String s)
| | public void | setEndPointAddressString(String s)
| | public void | setMessage(Message message)
Sets a
Message to this packet. |
| INBOUND_TRANSPORT_HEADERS | | final public static String INBOUND_TRANSPORT_HEADERS(Code) | | 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.
|
| OUTBOUND_TRANSPORT_HEADERS | | final public static String OUTBOUND_TRANSPORT_HEADERS(Code) | | 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.
|
| acceptableMimeTypes | | public String acceptableMimeTypes(Code) | | 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.
|
| endpoint | | public WSEndpoint endpoint(Code) | | The governing
WSEndpoint in which this message is floating.
This property is set if and only if this is on the server side.
|
| endpointAddress | | public EndpointAddress endpointAddress(Code) | | 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.
|
| expectReply | | public Boolean expectReply(Code) | | 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)
Tube s
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.
|
| handlerConfig | | public HandlerConfiguration handlerConfig(Code) | | This property holds the snapshot of HandlerConfiguration
at the time of invocation.
This property is used by MUPipe and HandlerPipe implementations.
|
| invocationProperties | | final public Map<String, Object> invocationProperties(Code) | | 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: Packet.getHandlerScopePropertyNames(boolean) |
| proxy | | public BindingProvider proxy(Code) | | 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?
|
| soapAction | | public String soapAction(Code) | | 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".
|
| transportBackChannel | | public TransportBackChannel transportBackChannel(Code) | | 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 .
|
| wasTransportSecure | | public boolean wasTransportSecure(Code) | | 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.
|
| createClientResponse | | public Packet createClientResponse(Message msg)(Code) | | 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. |
| createResponse | | public Packet createResponse(Message msg)(Code) | | 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(Message responseMessage, AddressingVersion addressingVersion, SOAPVersion soapVersion, String action)(Code) | | 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.
Parameters:
addressingVersion - The WS-Addressing version of the response message.
Parameters:
soapVersion - The SOAP version of the response message.
Parameters:
action - The response Action Message Addressing Property value. response packet |
| getContentNegotiationString | | public String getContentNegotiationString()(Code) | | |
| getHandlerScopePropertyNames | | final public Set<String> getHandlerScopePropertyNames(boolean readOnly)(Code) | | 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 helpsoptimizing the strategy.always non-null, possibly empty set that stores property names. |
| getPropertyMap | | protected PropertyMap getPropertyMap()(Code) | | |
| getReferenceParameters | | public List<Element> getReferenceParameters()(Code) | | 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.
|
| setContentNegotiationString | | public void setContentNegotiationString(String s)(Code) | | |
| setEndPointAddressString | | public void setEndPointAddressString(String s)(Code) | | |
| setMessage | | public void setMessage(Message message)(Code) | | Sets a
Message to this packet.
Parameters:
message - Can be null. |
|
|