Package com.sun.xml.ws.api.message

Class Packet

java.lang.Object
com.oracle.webservices.api.message.BasePropertySet
com.oracle.webservices.api.message.BaseDistributedPropertySet
com.sun.xml.ws.api.message.Packet
All Implemented Interfaces:
DistributedPropertySet, MessageContext, PropertySet, MessageMetadata
public final class Packet extends BaseDistributedPropertySet implements MessageContext, MessageMetadata
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 copyable.
  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. PropertySet.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

  • Field Details

    • 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:

    • 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:

    • HA_INFO

      public static final String HA_INFO
      See Also:

    • 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 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?

    • isAdapterDeliversNonAnonymousResponse

      public boolean isAdapterDeliversNonAnonymousResponse
      Determines if the governing Adapter or Fiber.CompletionCallback will handle delivering response messages targeted at non-anonymous endpoint addresses. Prior to the introduction of this flag the WsaServerTube would deliver non-anonymous responses.

    • packetTakesPriorityOverRequestContext

      public boolean packetTakesPriorityOverRequestContext
      During invocation of a client Stub or Dispatch a Packet is created then the Stub's RequestContext is copied into the Packet. On certain internal cases the Packet is created *before* the invocation. In those cases we want the contents of the Packet to take precedence when ever any key/value pairs collide : if the Packet contains a value for a key use it, otherwise copy as usual from Stub.

    • 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(com.sun.xml.ws.api.message.Packet, com.sun.xml.ws.api.server.WebServiceContextDelegate, com.sun.xml.ws.api.server.TransportBackChannel).

    • 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 (see keepTransportBackChannelOpen())

      This property is set from the parameter of WSEndpoint.PipeHead.process(com.sun.xml.ws.api.message.Packet, com.sun.xml.ws.api.server.WebServiceContextDelegate, com.sun.xml.ws.api.server.TransportBackChannel).

    • component

      public Component component
      The governing owner of this packet. On the service-side this is the Adapter and on the client it is the Stub.

    • 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 BP R2744 and BP R2745.) 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.FALSE, 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.TRUE, 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!!

    • isSynchronousMEP

      public Boolean isSynchronousMEP
      Indicates whether is invoking a synchronous pattern. If true, no async client programming model (e.g. AsyncResponse or AsyncHandler) were used to make the request that created this packet.

    • nonNullAsyncHandlerGiven

      public Boolean nonNullAsyncHandlerGiven
      Indicates whether a non-null AsyncHandler was given at the point of making the request that created this packet. This flag can be used by Tube implementations to decide how to react when isSynchronousMEP is false. If true, the client gave a non-null AsyncHandler instance at the point of request, and will be expecting a response on that handler when this request has been processed.

    • 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:

    • codec

      public Codec codec

  • Constructor Details

  • Method Details

    • copy

      public Packet copy(boolean copyMessage)
      Creates a copy of this Packet.
      Parameters:
      copyMessage - determines whether the Message from the original Packet should be copied as well, or not. If the value is false, the Message in the copy of the Packet is null.
      Returns:
      copy of the original packet

    • getMessage

      public Message getMessage()
      Gets the last Message set through setMessage(Message).
      Returns:
      may null. See the class javadoc for when it's null.

    • getInternalMessage

      public Message getInternalMessage()

    • getBinding

      public WSBinding getBinding()

    • setMessage

      public void setMessage(Message message)
      Sets a Message to this packet.
      Parameters:
      message - Can be null.

    • isProtocolMessage

      public boolean isProtocolMessage()

    • setIsProtocolMessage

      public void setIsProtocolMessage()

    • getUserStateId

      public String getUserStateId()

    • setUserStateId

      public void setUserStateId(String x)

    • getWSDLOperation

      @Nullable public QName getWSDLOperation()
      Returns the QName of the wsdl operation associated with this packet.
      Information such as Payload QName, wsa:Action header, SOAPAction HTTP header are used depending on the features enabled on the particular port.
      Returns:
      null if there is no WSDL model or runtime cannot uniquely identify the wsdl operation from the information in the packet.

    • getWSDLOperationMapping

      public WSDLOperationMapping getWSDLOperationMapping()
      Specified by:
      getWSDLOperationMapping in interface MessageMetadata

    • setWSDLOperation

      public void setWSDLOperation(QName wsdlOp)
      Set the wsdl operation to avoid lookup from other data. This is useful in SEI based clients, where the WSDL operation can be known from the associated JavaMethod
      Parameters:
      wsdlOp - QName

    • getEndPointAddressString

      @Deprecated 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.

    • keepTransportBackChannelOpen

      public TransportBackChannel keepTransportBackChannelOpen()
      Keeps the transport back channel open (by seeting transportBackChannel to null.)
      Returns:
      The previous value of transportBackChannel.

    • isRequestReplyMEP

      public Boolean isRequestReplyMEP()

    • setRequestReplyMEP

      public void setRequestReplyMEP(Boolean x)

    • getHandlerScopePropertyNames

      public 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

      @Deprecated public 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.

    • relateClientResponse

      public Packet relateClientResponse(Packet response)
      For use cases that start with an existing Packet.

    • 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

    • copyPropertiesTo

      public void copyPropertiesTo(@Nullable Packet response)
      Copy all properties from (this) packet into a input Packet
      Parameters:
      response - packet

    • relateServerResponse

      public Packet relateServerResponse(@Nullable Packet r, @Nullable WSDLPort wsdlPort, @Nullable SEIModel seiModel, @NotNull WSBinding binding)

    • 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

    • setResponseMessage

      public void setResponseMessage(@NotNull Packet request, @Nullable Message responseMessage, @NotNull AddressingVersion addressingVersion, @NotNull SOAPVersion soapVersion, @NotNull String action)
      Overwrites the Message of the response packet (this) by the given Message. Unlike setMessage(Message), fill in the addressing headers correctly, and this process requires the access to the request packet.

      This method is useful when the caller needs to swap a response message completely to a new one.

      See Also:

    • toShortString

      public String toShortString()

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getPropertyMap

      protected BasePropertySet.PropertyMap getPropertyMap()
      Description copied from class: BasePropertySet
      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;
 }
      or if the implementation is in different Java module. 
       private static final PropertyMap model;
 static {
   model = parse(MyDerivedClass.class, MethodHandles.lookup());
 }
 protected PropertyMap getPropertyMap() {
   return model;
 }
      Specified by:
      getPropertyMap in class BasePropertySet
      Returns:
      the map of strongly-typed known properties keyed by property names

    • asMapIncludingInvocationProperties

      public Map<String,Object> asMapIncludingInvocationProperties()

    • getAsSOAPMessage

      public SOAPMessage getAsSOAPMessage() throws SOAPException
      Description copied from interface: MessageContext
      Gets the SAAJ SOAPMessage representation of the SOAP message.
      Specified by:
      getAsSOAPMessage in interface MessageContext
      Returns:
      The SOAPMessage
      Throws:
      SOAPException

    • getCodec

      public Codec getCodec()

    • writeTo

      public ContentType writeTo(OutputStream out) throws IOException
      Description copied from interface: MessageContext
      Writes the XML infoset portion of this MessageContext (from <soap:Envelope> to </soap:Envelope>).
      Specified by:
      writeTo in interface MessageContext
      Parameters:
      out - Must not be null. The caller is responsible for closing the stream, not the callee.
      Returns:
      The MIME content type of the encoded message (such as "application/xml"). This information is often ncessary by transport.
      Throws:
      IOException - if a OutputStream throws IOException.

    • writeTo

      public ContentType writeTo(WritableByteChannel buffer)

    • getMtomRequest

      public Boolean getMtomRequest()

    • setMtomRequest

      public void setMtomRequest(Boolean mtomRequest)

    • getMtomAcceptable

      public Boolean getMtomAcceptable()

    • checkMtomAcceptable

      public void checkMtomAcceptable()

    • getFastInfosetAcceptable

      public Boolean getFastInfosetAcceptable(String fiMimeType)

    • setMtomFeature

      public void setMtomFeature(MTOMFeature mtomFeature)

    • getMtomFeature

      public MTOMFeature getMtomFeature()

    • getContentType

      public ContentType getContentType()
      Description copied from interface: MessageContext
      Gets the Content-type of this message. For an out-bound message that this getContentType() method returns a null, the Content-Type can be determined only by calling the writeTo method to write the MessageContext to an OutputStream.
      Specified by:
      getContentType in interface MessageContext
      Returns:
      The MIME content type of this message

    • getInternalContentType

      public ContentType getInternalContentType()

    • setContentType

      public void setContentType(ContentType contentType)

    • getState

      public Packet.State getState()

    • setState

      public void setState(Packet.State state)

    • shouldUseMtom

      public boolean shouldUseMtom()

    • setFastInfosetDisabled

      public void setFastInfosetDisabled(boolean b)

    • getSAAJFactory

      public SAAJFactory getSAAJFactory()

    • setSAAJFactory

      public void setSAAJFactory(SAAJFactory saajFactory)