Message (Policy Manager Scripting API)

```
public interface Message
```
A message variable. A message can hold content of a specified mime type, i.e., application/json, application/xml, text/plain. A message may also have transport headers, protocol headers, and in-memory properties associated with it. Depending on the context in which a script is run it will be different how to gain access to a message variable. For example from a script run from a process you may use the ProcessContext as follows:
```
 msg = processContext.getVariable("messageVariableName");
 
```
A message can be either normalized or raw. A raw message will have content that is exactly what was received or will be sent over the wire. Its format will be protocol specific based on the endpoint the message was received on or will be sent to. It may be XML, JSON, HTML, text, etc. The format of the message can be determined by it's mime type as returned by the getContentType() method. Messages received from the Receive activity of a process or returned in the response of an Invoke activity are in wire format. They can be manipulated in that format or they can be normalized.
A normalized message has content in XML format. The content will adhere to the definition of a message element in a WSDL document. For example, say the process implements a virtual service operation name Op1. In Op1's WSDL document Op1 will reference a wsdl:message element as it's input. That wsdl:message element will describe the format of the message received in the Receive activity of the process once it is normalized. It does not matter what protocol was used to deliver the message. Once normalized it will be in XML according to that WSDL definition. If a service supports multiple endpoints each supporting different protocols, SOAP, REST, etc., messages received from any of those endpoints once normalized will all be in the same format. The following is an example of how to normalize a message:
```
 normalMsg = msg.normalize();
 
```
The original message, msg in this case, is left in it's original wire format. The returned normalized message, normalMsg in this case, is a normalized copy of the original. The Reply activity and Invoke activity can accept both wire format messages and normalized messages. If a wire format message is used it is the developer's responsibility to make sure it is in the correct format with respect to the endpoint the message is being sent to. If a normalized message is used, the system will bind the message to the correct protocol format based on the endpoint the message is being sent to.
A message may have transport headers. A transport header is specific to the transport layer, for example HTTP or JMS. To read and/or manipulate the transport headers you use the Headers object. The following shows how to get the Headers:
```
 headers = msg.getTransportHeaders();
 
```
Changes made to the returned Headers are reflected in the message. If there are no transport headers associated with the message and you would like to add some you first create a Headers object, add the headers, and then set the headers on the message object as follows:
```
 headers = msg.createTransportHeaders();
 headers.add("myHeaderName", "myHeaderValue");
 msg.setTransportHeaders(headers);
 
```
A message may also have protocol headers. A protocol header is specific to the protocol layer above the transport layer, i.e., SOAP. If the message is not normalized the protocol headers (if any) are embedded in the content as the content is in the protocol specific format already. If the message is normalized then the protocol headers will be separate from the content and can be read and/or manipulated using methods on the Message object. These methods expect the protocol headers to be in XML format just as a normalized message is. The protocol headers and normalized message content are converted to the appropriate protocol when the message is sent over the wire. The following will read a protocol header from a normalized message. It returns the XML formatted header as a string variable:
```
 header = msg.getProtocolHeader("{http://myns}MyHeaderName");
 
```
And to change a protocol header:
```
  msg.setProtocolHeader("{http://myns}MyHeaderName", "<h:MyHeaderName xmlns:h=\"http://myns\"/>");
 
```
A message can have properties associated with it that are not part of the message sent over the wire. They are possibly pieces of information extracted from the wire content or they are pieces of information added and read from policy handlers in the container framework. The values of the properties can be any Java object. Trying to read or manipulate a property that is not documented is not supported. You can add and read your own properties for use in processes or your own policy handlers. The following shows how to read a property:
```
 myProp = msg.getProperty("MyProp");
 
```
And to add/change a property:
```
 msg.setProperty("myProp", "myValue");
 
```

Method Summary

All Methods Instance Methods Abstract Methods Deprecated Methods
Modifier and Type	Method and Description
`void`	`addPart(java.lang.String name, java.lang.Object part)` Adds a value for a part (parameter) with the given name.
`boolean`	`canNormalize()` Returns whether the message can be normalized or not.
`Headers`	`createTransportHeaders()` Creates a new Headers set and associates it with the message.
`byte[]`	`getContent()` Returns the content of the message.
`byte[]`	`getContent(javax.xml.transform.Source src)` Deprecated. For internal use. Returns the content of the message.
`java.lang.String`	`getContentAsString()` Returns the content of the message as a string.
`java.lang.String`	`getContentPartName()` When using parts in a message one of those parts can be considered the content of the message (see `getContent()`).
`java.lang.String`	`getContentType()` Returns the type of content of the message, i.e., application/xml, application/json.
`java.lang.String`	`getCorrelationID()` Returns a correlation identifier (if any) that can be used to correlate this message with another.
`java.lang.String`	`getID()` Returns the ID of the message (if any).
`java.lang.Object`	`getPart(java.lang.String name)` Returns the message part (parameter) with the given name.
`java.lang.String[]`	`getPartNames()` Returns the names of all parts (parameters) that have been assigned a value.
`java.lang.Object`	`getProperty(java.lang.String name)` Returns the property with the given name.
`java.util.Set`	`getPropertyNames()` Returns the names of the properties associated with the message.
`java.lang.String`	`getProtocolHeader(java.lang.String headerName)` Returns the protocol header with the given name associated with a normalized message.
`SubjectMap`	`getSecuritySubjects()` Map of categories to `com.soa.security.script.Subject`s.
`SubjectMap`	`getSecuritySubjects(boolean createIfNotExist)` Map of categories to `com.soa.security.script.Subject`s.
`Headers`	`getTransportHeaders()` Returns the transport headers associated with the message (if any).
`boolean`	`isNormalized()` Returns whether the message is normalized or not.
`Message`	`normalize()` Normalizes the message.
`Message`	`normalizeToXML()` Normalizes the message to an XML format.
`void`	`removePart(java.lang.String name)` Removes the value for the part (parameter) with the given name.
`void`	`setContent(byte[] content)` Changes the message content.
`void`	`setContentPartName(java.lang.String name)` When using parts in a message one of those parts can be considered the content of the message (see `getContent()`).
`void`	`setContentType(java.lang.String contentType)` Changes the type of content of the message, i.e., application/xml, application/json.
`void`	`setCorrelationID(java.lang.String id)` Changes the correlation ID of the message.
`void`	`setProperty(java.lang.String name, java.lang.Object property)` Associates a property with the message.
`void`	`setProtocolHeader(java.lang.String headerName, org.w3c.dom.Node headerValue)` Creates or changes a protocol header with the given name associated with a normalized message.
`void`	`setProtocolHeader(java.lang.String headerName, java.lang.String headerValue)` Creates or changes a protocol header with the given name associated with a normalized message.
`void`	`setStringContent(java.lang.String content)` Changes the message content with a String.
`void`	`setTransportHeaders(Headers headers)` Replaces the set of transport headers associated with the message.

- Method Detail
  - getID
```
java.lang.String getID()
```
    Returns the ID of the message (if any). An ID is typically used when the message is part of an asynchronous exchange. It may not be available for synchronous exchanges. If present, the ID will be unique between the producer and consumer of the messsage while the exchange it is part of is active.
    
    Returns:
    
    String identifier of the message, null if none available.
  - getCorrelationID
```
java.lang.String getCorrelationID()
```
    Returns a correlation identifier (if any) that can be used to correlate this message with another. The most common example is for correlating an asynchronous response to a request message. This would be done by using the request message's ID as the response message's correlation ID.
    
    Returns:
    
    String correlation identifier, null if none available.
  - setCorrelationID
```
void setCorrelationID(java.lang.String id)
```
    Changes the correlation ID of the message. The most common use is for asynchronous messaging. The request message ID would be set as the response message's correlation ID.
    
    Parameters:
    
    id - String correlation identifier.
  - getContent
```
byte[] getContent()
           throws GException
```
    Returns the content of the message.
    
    Returns:
    
    byte[] holding the message content.
    
    Throws:
    
    GException - Thrown if unable to retrieve message content. Possibly caused by badly formed content.
  - getProtocolHeader
```
java.lang.String getProtocolHeader(java.lang.String headerName)
                            throws GException
```
    Returns the protocol header with the given name associated with a normalized message. The message must be normalized for this method to apply. The header will be described using XML. The most common example of a protocol header is a SOAP header.
    
    Parameters:
    
    headerName - Qualified name of the header in string format ({namespace}localPart).
    
    Returns:
    
    String representation of the protocol header, null if not found or the message is not normalized.
    
    Throws:
    
    GException - Thrown if an error was encountered trying to find the header.
  - setProtocolHeader
```
void setProtocolHeader(java.lang.String headerName,
                       org.w3c.dom.Node headerValue)
                throws GException
```
    Creates or changes a protocol header with the given name associated with a normalized message. A protocol header is a header of the protocol layer independent of the transport. Not all protocols (REST) have this layer. Others like SOAP do. The header must be described using XML. The message must be normalized for this method to apply.
    
    Parameters:
    
    headerName - Qualified name of the header in string format ({namespace}localPart).
    
    headerValue - DOM Node holding the header content.
    
    Throws:
    
    GException - Thrown if an error is encountered trying to create the header or if the message is not normalized.
  - setProtocolHeader
```
void setProtocolHeader(java.lang.String headerName,
                       java.lang.String headerValue)
                throws GException
```
    Creates or changes a protocol header with the given name associated with a normalized message. A protocol header is a header of the protocol layer independent of the transport. Not all protocols (REST) have this layer. Others like SOAP do. The header must be described using XML. The message must be normalized for this method to apply.
    
    Parameters:
    
    headerName - Qualified name of the header in string format ({namespace}localPart).
    
    headerValue - String holding the header content.
    
    Throws:
    
    GException - Thrown if an error is encountered trying to create the header or if the message is not normalized.
  - getTransportHeaders
```
Headers getTransportHeaders()
```
    Returns the transport headers associated with the message (if any).
    
    Returns:
    
    Headers holding transport headers for the message, null if none present.
  - createTransportHeaders
```
Headers createTransportHeaders()
                        throws GException
```
    Creates a new Headers set and associates it with the message.
    
    Returns:
    
    Headers to hold transport headers for the message.
    
    Throws:
    
    GException - Thrown if unable to create the Headers.
  - setTransportHeaders
```
void setTransportHeaders(Headers headers)
```
    Replaces the set of transport headers associated with the message.
    
    Parameters:
    
    headers - Headers holding transport headers for the message.
  - getContentAsString
```
java.lang.String getContentAsString()
                             throws GException
```
    Returns the content of the message as a string.
    
    Returns:
    
    String holding the message content.
    
    Throws:
    
    GException - Thrown if unable to retrieve message content. Possibly caused by badly formed content or unsupported charset.
  - getContent
```
byte[] getContent(javax.xml.transform.Source src)
           throws GException
```
    Deprecated. For internal use. Returns the content of the message.
    
    Parameters:
    
    src - Source holding content to transform to byte[].
    
    Returns:
    
    byte[] holding the message content.
    
    Throws:
    
    GException - Thrown if unable to retrieve message content. Possibly caused by badly formed content.
  - setStringContent
```
void setStringContent(java.lang.String content)
               throws GException
```
    Changes the message content with a String.
    
    Parameters:
    
    content - String holding the message content.
    
    Throws:
    
    GException - Thrown if unable to change the content. Possibly caused by passing in badly formed content.
  - setContent
```
void setContent(byte[] content)
         throws GException
```
    Changes the message content.
    
    Parameters:
    
    content - byte[] holding the message content.
    
    Throws:
    
    GException - Thrown if unable to change the content. Possibly caused by passing in badly formed content.
  - getProperty
```
java.lang.Object getProperty(java.lang.String name)
```
    Returns the property with the given name.
    
    Parameters:
    
    name - Name of the property.
    
    Returns:
    
    Object value of the property, null if not found.
  - setProperty
```
void setProperty(java.lang.String name,
                 java.lang.Object property)
```
    Associates a property with the message.
    
    Parameters:
    
    name - Name of the property.
    
    property - Value of the property.
  - getPropertyNames
```
java.util.Set getPropertyNames()
```
    Returns the names of the properties associated with the message. Changes made to the Set are reflected in the message, so if a name is removed from the Set, the property is removed from the message. Names cannot be added however.
    
    Returns:
    
    Set of String property names.
  - isNormalized
```
boolean isNormalized()
```
    Returns whether the message is normalized or not.
    
    Returns:
    
    True if normalized, false if not.
  - canNormalize
```
boolean canNormalize()
```
    Returns whether the message can be normalized or not. Some types of messages may not support normalization. Only messages that originate from external sources such as those originating from a receive activity or an invoke invoke activity can be normalized. If one creates a message from within a process normalization must be performed manually.
    
    Returns:
    
    True if can be normalized, false if not.
  - normalize
```
Message normalize()
           throws GException
```
    Normalizes the message. All defined message parts are taken from their bound encodings and placed in the message's parts map. A new normalized version of the message is returned. Due to the possibility of this original object using InputStreams to hold its content, after normalization this object's InputStreams will most likely be exhausted making this object unusable.
    
    Returns:
    
    Normalized Message.
    
    Throws:
    
    GException - Thrown if unable to normalize.
  - normalizeToXML
```
Message normalizeToXML()
                throws GException
```
    Normalizes the message to an XML format. All defined message parts are taken from their bound encodings and placed in the message's parts map. The part identified as the content part (see getContentPartName()) will be translated into an XML representation. A new normalized version of the message is returned. Due to the possibility of this original object using InputStreams to hold its content, after normalization this object's InputStreams will most likely be exhausted making this object unusable.
    
    Returns:
    
    Normalized Message.
    
    Throws:
    
    GException - Thrown if unable to normalize.
  - getContentType
```
java.lang.String getContentType()
```
    Returns the type of content of the message, i.e., application/xml, application/json.
    
    Returns:
    
    Type of message content.
  - setContentType
```
void setContentType(java.lang.String contentType)
```
    Changes the type of content of the message, i.e., application/xml, application/json.
    
    Parameters:
    
    contentType - Type of message content.
  - getSecuritySubjects
```
SubjectMap getSecuritySubjects()
```
    Map of categories to com.soa.security.script.Subjects. Changes to the returned map are reflected in the message.
    
    Returns:
    
    SubjectMap of category URI's to subjects, null if it does not exist.
  - getSecuritySubjects
```
SubjectMap getSecuritySubjects(boolean createIfNotExist)
```
    Map of categories to com.soa.security.script.Subjects. Changes to the returned map are reflected in the message. If the createIfNotExist flag is true then a map will be created if it does not already exist. If the flag is false and there is no map then null will be returned.
    
    Parameters:
    
    createIfNotExist - If not map currently exists and this flag is true one will be created and returned.
    
    Returns:
    
    SubjectMap of category URI's to subjects, null if it does not exist and createIfNotExist is false.
  - getPart
```
java.lang.Object getPart(java.lang.String name)
```
    Returns the message part (parameter) with the given name.
    
    Parameters:
    
    name - Name of the requested part.
    
    Returns:
    
    Value of the part, null if not present.
  - addPart
```
void addPart(java.lang.String name,
             java.lang.Object part)
```
    Adds a value for a part (parameter) with the given name.
    
    Parameters:
    
    name - Name of the part.
    
    part - Value of the part.
  - removePart
```
void removePart(java.lang.String name)
```
    Removes the value for the part (parameter) with the given name.
    
    Parameters:
    
    name - Name of the part.
  - getPartNames
```
java.lang.String[] getPartNames()
```
    Returns the names of all parts (parameters) that have been assigned a value.
    
    Returns:
    
    Array of part names. Empty array if none assigned.
  - getContentPartName
```
java.lang.String getContentPartName()
```
    When using parts in a message one of those parts can be considered the content of the message (see getContent()). This method will return the name of the part that holds the content.
    
    Returns:
    
    Part name holding the message content.
  - setContentPartName
```
void setContentPartName(java.lang.String name)
```
    When using parts in a message one of those parts can be considered the content of the message (see getContent()). This method can be used to specify the name of the part that should be considered the message content.
    
    Parameters:
    
    name - Name of the part holding the message content.

This software is the confidential and proprietary information of Perforce, Inc. and is subject to copyright protection under laws of the United States of America and other countries. The use of this software should be in accordance with the license agreement terms you entered into with Perforce, Inc.

Interface Message

Method Summary

Method Detail

getID

getCorrelationID

setCorrelationID

getContent

getProtocolHeader

setProtocolHeader

setProtocolHeader

getTransportHeaders

createTransportHeaders

setTransportHeaders

getContentAsString

getContent

setStringContent

setContent

getProperty

setProperty

getPropertyNames

isNormalized

canNormalize

normalize

normalizeToXML

getContentType

setContentType

getSecuritySubjects

getSecuritySubjects

getPart

addPart

removePart

getPartNames

getContentPartName

setContentPartName