Network Deployment (Distributed operating systems), v8.0 > Reference > Developer best practices
Map of SDO data graphs for web services messages
The structure of web services messages is described by the Service Data Objects (SDO) v1 data graphs for web services messages.
Overall layout of a web services message
A web services message is described by a format string and three metadata fields: operationName, messageName, and messageType. The payload of the message is split across three other sections: headers, attachments and the body.
The Info node is the top of the SDO data graph for all web services messages. The following table describes the Info node properties and associated types.
Property name Property type Property description operationName java.lang.String Identifies the WSDL operation that is associated with the message. If the data access service cannot identify the message, this field is null. See Identify web services messages. messageName java.lang.String Identifies the WSDL message that is associated with the message. If the data access service cannot identify the message, this field is null. See Identify web services messages. messageType java.lang.String Identifies WebService type of message instance. This field can have the values: input, output, fault, ambiguous. If the data access service cannot identify the message, this field is null. See Identify web services messages. headers java.util.List of data objects. Contains a list of header entry data objects. Each SOAP header in the message results in a header entry in this list. See Message header layout. attachments java.util.List of data objects. Contains a list of attachment entry data objects. For SOAP messages with attachments, each MIME part in the message (except the MIME part containing the SOAP envelope) is mapped to an entry in this list. See Message attachment layout. body commonj.sdo.DataObject A nested data object, which represents the body of the SOAP envelope. See Message body layout.
Identify web services messages
Process of messages depends on whether the messages have WSDL definitions. The minimum amount of information required for processing without WSDL is "SOAP:". The minimum amount of information required for processing with WSDL is: "SOAP:location,namespace,service,port". If the format string does not include all five of these fields, the SOAP data access service attempts to process the message without WSDL.
- Process messages without WSDL definitions:
If the format string does not include full WSDL information, the SOAP data access service processes the message without attempting to match the message against definitions in WSDL. As a result, operationName and messageName are set to null, and messageType is set only when processing a fault message.
- Process messages with WSDL definitions:
If the format string includes <WSDL location>, <Service namespace>, <Service name>, and <Port name>, the SOAP and Beans data access services process the message by using the WSDL definitions of the service.In either of the following circumstances, SOAP message processing fails after supplying all the required WSDL information:
- the SOAP data access service fails to locate the WSDL
- the WSDL fails to corroborate the message
When the SOAP data access service processes a SOAP request or reply message, it tries to match it against the message definitions in the WSDL. Usually there is one matching definition, and the operationName, messageName, and messageType are filled in appropriately. If there is more than one matching definition, the data access service selects a message definition, fills in the operationName and messageName. and sets the messageType to ambiguous.
When processing fault messages, identification is slightly different. In all cases the messageType is set to fault. If the message matches a unique fault definition in the WSDL, the operationName and messageName properties are also set.
Message header layout
The list of headers has two types of entry, header entry or bound header entry, depending on whether the header is based on part of the message or not.
The header entry type is used to handle headers that meet either of the following criteria:
- the header is part of the message that is modeled in WSDL
- the header is part of the message that is not modeled in WSDL, but is based on a part of the message
For a model of this header, see Header entry.
The bound header entry type is used when the SOAP binding for the message has bound a part of the body into a MIME attachment. (This occurs when you use a <MIME:content> element to bind a part of the message to an attachment.) For consistent mediation programming, all of the body data is stored in the body node in the graph. Unlike the normal attachment entry, a bound attachment entry is placed into the attachments list. The bound attachment entry contains the MIME meta-data for the attachment and the name of the message part that contains the data taken from this attachment. This allows mediations designed to process attachments to locate the data in the body part of the data graph. For a model of this attachment see Bound header entry.
Header entry
Property name Property type Property description mustUnderstand java.lang.Boolean Carries the value from the mustUnderstand attribute on the SOAP header, if present. actor java.lang.String Carries the value from the actor attribute on the SOAP header, if present. any commonj.sdo.Sequence Container for the contents of the SOAP header.
Bound header entry
Property name Property type Property description mustUnderstand java.lang.Boolean Carries the value from the mustUnderstand attribute on the SOAP header, if present. actor java.lang.String Carries the value from the actor attribute on the SOAP header, if present. messagePart java.lang.String Contains the name of the message part that carries the data from this message header.
Message attachment layout
Message attachments are handled in a similar way to headers, and instances of them populate the attachments list in the Info node.
There are two types of attachment entry to handle MIME attachments: attachment entry and bound attachment entry.
Attachment entry is for general attachments: see Attachment entry.
Bound attachment entry includes <MIME:content> elements that bind a part of the body into a MIME attachment. If you are programming a mediation, know how to locate the data within the graph. For consistent mediation programming, the attachment data is placed in the message body, referred to by the part name in the header entry, which includes the other MIME metadata. For a model of this attachment, see Bound attachment entry.
Attachment entry
Property name Property type Property description contentType java.lang.String Carries the contentType from the MIME part that is represented by the attachment entry. contentTransferEncoding java.lang.String Carries the contentTransferEncoding from the MIME part that is represented by the attachment entry. contentId java.lang.String Carries the contentId from the MIME part that is represented by the attachment entry. data byte[] Carries the content of the MIME element as a byte array.
Bound attachment entry
Property name Property type Property description contentType java.lang.String Carries the contentType from the MIME part that is represented by the attachment entry. contentTransferEncoding java.lang.String Carries the contentTransferEncoding from the MIME part that is represented by the attachment entry. contentId java.lang.String Carries the contentId from the MIME part that is represented by the attachment entry. messagePart java.lang.String Contains the name of the message part that carries the data from this attachment.
Message body layout
The layout of the data object in the body is defined by the service WSDL. The type of the data object is derived from the message definition in the WSDL. The data object has one property for each part in the message definition. The layout of each message part follows the convention for mapping XML Schema into SDO. See Web Services code example for more information.
Web services fault message
If the message is a fault message, the messageType field in the Info node of the graph is set to "fault", and the message body has the following properties:
Property name Property type Property description faultcode javax.xml.namespace.QName Carries the faultcode value from the SOAP Fault element faultstring java.lang.String Carries the faultstring value from the SOAP Fault element faultactor java.lang.String Carries the faultactor value from the SOAP Fault element detail commonj.sdo.DataObject Carries the content within the detail child of the SOAP Fault element The detail element definition uses element and attribute wildcards, so the content of the detail data object contains a Sequence. See Web Services code example for more information.
SDO data graphs
Include SOAP header schemas in the SDO repository
Write a mediation that maps between attachment encoding styles