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

Class 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 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 jakarta.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?

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

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

      • 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:
        getHandlerScopePropertyNames(boolean)

      • codec

        public Codec codec

    • Method Detail

      • 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

      • getInternalMessage

        public Message getInternalMessage()

      • 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 final 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.

      • 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

        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.

      • isRequestReplyMEP

        public Boolean isRequestReplyMEP()

      • setRequestReplyMEP

        public void setRequestReplyMEP​(Boolean x)

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

      • relateClientResponse

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

      • copyPropertiesTo

        public void copyPropertiesTo​(@Nullable
                             Packet response)
        Copy all properties from (this) packet into a input Packet
        Parameters:
        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

      • toShortString

        public String toShortString()

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

      • getSOAPMessage

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

      • getAsSOAPMessage

        public jakarta.xml.soap.SOAPMessage getAsSOAPMessage()
                                              throws jakarta.xml.soap.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:
        jakarta.xml.soap.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.

      • 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​(jakarta.xml.ws.soap.MTOMFeature mtomFeature)

      • getMtomFeature

        public jakarta.xml.ws.soap.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)

      • shouldUseMtom

        public boolean shouldUseMtom()

      • addSatellite

        public void addSatellite​(@NotNull
                         PropertySet satellite)
        Deprecated.

      • addSatellite

        public void addSatellite​(@NotNull
                         Class keyClass,
                         @NotNull
                         PropertySet satellite)
        Deprecated.

      • removeSatellite

        public void removeSatellite​(PropertySet satellite)
        Deprecated.

      • setFastInfosetDisabled

        public void setFastInfosetDisabled​(boolean b)

      • setSAAJFactory

        public void setSAAJFactory​(SAAJFactory saajFactory)