Supported message types for SCA JMS binding wire formats

For a Service Component Architecture (SCA) application that has a Java Message Service (JMS) binding to send and receive messages, the application must use a message type and data format that the JMS binding supports. Supported message types include JMS BytesMessage, ObjectMessage, and TextMessage. The message type to use depends on whether you are configuring an SCA service or reference and whether the JMS wire format of the service or reference is already determined.

The supported message types apply to applications coded to both the OSOA and OASIS specifications. Unless otherwise specified, the information in this topic pertains to both OSOA and OASIS applications.

The following sections describe supported message types:

• Message types for SCA services when the JMS binding wire format is predetermined

• Message types for SCA references when the JMS binding wire format is predetermined

• Message types for SCA services and references when the JMS binding wire format is not predetermined

Message types for SCA services when the JMS binding wire format is predetermined

For an SCA service to consume messages that are produced in a predetermined JMS binding wire format, use the following message types:

• TextMessage or BytesMessage with serialized XML wire format that maps data using JAXB

  The TextMessage or BytesMessage wire format uses JAXB technology to marshal and unmarshal data into XML. This wire format is the default wire format. Thus, this wire format applies if no wire format element is specified in the composite definition file. To specify this wire format, add the following wire format element to the composite definition file:

  OSOA

  {http://tuscany.apache.org/xmlns/sca/1.0}wireFormat.jmsdefault

  OASIS

  {http://docs.oasis-open.org/ns/opencsa/sca/200912}wireFormat.jmsDefault

  • Mapping a request message payload to input arguments

    The TextMessage or BytesMessage payload contains XML data that represents serialized input arguments. The format of the service is described by a WSDL interface specified by either a interface.wsdl element from the component service definition, or by a WSDL that is generated by the Java interface of the SCA service if the interface.wsdl element is not explicitly defined.

    This runtime environment Java-to-WSDL mapping is based on the JAXB and JAX-WS specifications. The default behavior results in a document-literal wrapped WSDL interface, except when there is a single parameter method. A single argument input parameter is not wrapped by a "wrapper" element corresponding to the operation name.

    JAXB unmarshalling is used to deserialize incoming XML payloads into the service arguments that are passed to the component implementation.

  • Mapping an output return value to a response message payload

    The return value of the service method is marshalled in a similar manner to the unmarshalling of the request message input. The marshalling uses JAXB and JAX-WS technology to map to XML in a WSDL defined format such that the WSDL is specified explicitly or the runtime environment generates the WSDL from the Java interface. The resulting serialized XML is never wrapped by the operation name, even if the WSDL defines a wrapper element.

    If the request payload is a BytesMessage, the non-wrapped XML is set as the payload of a response BytesMessage. If the request payload received is a TextMessage, the non-wrapped XML is set as a TextMessage. The response format is always the same as the request message format.

  • Mapping exceptions to a response message payload

    If we have a checked exception, the runtime environment will not marshall the exception. Instead, the runtime environment serializes the fault, as defined by JAX-WS, into an XML payload of a response TextMessage. If we have an unchecked exception, an instance of RuntimeException is set as the payload of a response ObjectMessage. In both cases, a Boolean message property with the name, org_apache_tuscany_sca_fault, is set totrue on the response message. To learn more about exceptions and faults, see the documentation on using business exceptions with SCA interfaces.

• TextMessage with serialized XML wire format that maps data using JAXB

  The TextMessage wire format uses JAXB technology to marshal and unmarshal data into XML. To specify this wire format, add the following wire format element to the composite definition file:

  OSOA

  {http://tuscany.apache.org/xmlns/sca/1.0}wireFormat.jmsTextXML

  OASIS

  {http://tuscany.apache.org/xmlns/sca/1.1}wireFormat.jmsTextXML

  • Mapping a request message payload to input arguments

    The TextMessage payload contains XML data that represents serialized input arguments. The format of the service is described by a WSDL interface specified by either a interface.wsdl element from the component service definition, or by a WSDL that is generated by the Java interface of the SCA service if the interface.wsdl element is not explicitly defined. This runtime environment Java-to-WSDL mapping is based on the JAXB and JAX-WS specifications. This mapping results in a document-literal wrapped WSDL interface; however, the presence of the operation-level wrapper does not impact operation selection for the messages. JAXB unmarshalling is used to deserialize incoming XML payloads into the service arguments that are passed to the component implementation.

  • Mapping an output return value to a response message payload

    The return value of the service method is marshalled in a similar manner to the unmarshalling of the request message input. The marshalling uses JAXB and JAX-WS technology to map to XML in a WSDL defined format such that the WSDL is specified explicitly or the runtime environment generates the WSDL from the Java interface. The resulting serialized XML is the payload of a TextMessage response message.

  • Mapping exceptions to a response message payload

    If we have a checked exception, the runtime environment will not marshall the exception. Instead, the runtime environment serializes the fault, as defined by JAX-WS, into an XML payload of a response TextMessage. If we have an unchecked exception, an instance of RuntimeException is set as the payload of a response ObjectMessage. In both cases, a Boolean message property with the name, org_apache_tuscany_sca_fault, is set totrue on the response message. To learn more about exceptions and faults, see the documentation on using business exceptions with SCA interfaces.

• ObjectMessage wire format that maps to the java.lang.Object class

  The ObjectMessage wire format uses serialized Java objects. To specify this wire format, add the following wire format element to the composition definition file:

  OSOA

  {http://tuscany.apache.org/xmlns/sca/1.0}wireFormat.jmsObject

  OASIS

  {http://tuscany.apache.org/xmlns/sca/1.1}wireFormat.jmsObject

  • Mapping a request message payload to input arguments

    The ObjectMessage payload returned by a getObject() method is typically an array that maps to the input parameters of the service method. In the case of a single non-array object, the object is mapped to the single argument of a method with only one parameter. The parameter type must be serializable by Java and implement the Java serialization interface, java.io.Serializable.

    For a method with exactly one parameter, the payload returned from getObject() can either be unwrapped, as described in the previous special case, or wrapped in an array of size one that maps to the single input parameter. When the runtime cannot determine if the payload array is a wrapper array that maps to the input parameters of the service method or if the payload array is the actual argument itself, the default behavior is to map the payload directly to the single argument of the method. We can override this behavior by setting the wrapSingle attribute on the wireFormat.jmsObject element to true. When wrapSingle is set to true, the content of the payload array, which is a single element because the size of the array is one, is mapped to the single argument of the method. The payload array itself is not mapped to the method argument.

  • Mapping an output return value to a response message payload

    The return value of the service method is set as the ObjectMessage payload. The return type must also be Java-serializable and implement the Java serialization interface, java.io.Serializable. In the case of a void return type, the response payload is set to the value, null.

  • Mapping exceptions to a response message payload

    If we have a checked exception, the runtime environment sets the exception as the ObjectMessage payload. For an unchecked exception, an instance of RuntimeException is set as the payload of a response ObjectMessage. In both cases, a Boolean message property with name org_apache_tuscany_sca_fault is set to true on the response message.

• TextMessage wire format that maps to single String messages

  Use the wireFormat.jmsText format to map between the payload of a TextMessage and a single String argument or return value. To specify this wire format, add the following wire format element to the composition definition file:

  OSOA

  {http://tuscany.apache.org/xmlns/sca/1.0}wireFormat.jmsText

  OASIS

  {http://tuscany.apache.org/xmlns/sca/1.1}wireFormat.jmsText

  • Mapping a request message payload to input arguments

    When using this wire format, the service interface method must contain a single parameter of type String; for example: void myMethod(String str). The TextMessage payload returned by the getText() method is mapped to this single parameter.

  • Mapping an output return value to a response message payload

    The return type of the service method is typically either String or void. If the return type is String, the return value is set as the response TextMessage payload. If the return type is void, a null value is set as the payload. For a return value of type other than String, the payload is defined by setting a String.valueOf() on the return value.

  • Mapping exceptions to a response message payload

    Rather than defining a convention for mapping exceptions to a TextMessage, ObjectMessage messages are used to map exceptions. If we have a checked exception, the runtime environment sets the exception as the ObjectMessage payload. For an unchecked exception, an instance of RuntimeException is set as the payload of a response ObjectMessage message. In both cases, a Boolean message property with name org_apache_tuscany_sca_fault is set to true on the response message.

• BytesMessage with XML wire format that maps data using JAXB

  The BytesMessage wire format uses JAXB technology to marshal and unmarshal data into XML. To specify this wire format, add the following wire format element to the composite definition file:

  OSOA

  {http://tuscany.apache.org/xmlns/sca/1.0}wireFormat.jmsBytesXML

  OASIS

  {http://tuscany.apache.org/xmlns/sca/1.1}wireFormat.jmsBytesXML

  • Mapping a request message payload to input arguments

    The input arguments are marshalled into an XML payload, and added to a request BytesMessage. The format of the service is described by a WSDL interface specified by either a interface.wsdl element from the component service definition, or by a WSDL that is generated by the Java interface of the SCA service if the interface.wsdl element is not explicitly defined. This runtime environment Java-to-WSDL mapping is based on the JAXB and JAX-WS specifications. This mapping results in a document-literal wrapped WSDL interface; however, the presence of the operation-level wrapper does not impact operation selection for the messages. The product uses JAXB marshalling to serialize the Java client input argument into the XML payload.

  • Mapping exceptions to a response message payload

    The runtime environment first determines whether the response message represents an unchecked exception condition by looking for the org_apache_tuscany_sca_fault Boolean message property. If true on the response message, the runtime environment expects an ObjectMessage as the response. When this condition occurs, a ServiceRuntimeException error is returned to the client. If not set, or set to false, the message is a BytesMessage that can represent either a checked exception or normal output data. If a checked exception, the BytesMessage payload contains a fault in XML serialized form. The runtime environment deserializes the fault using JAXB unmarshalling, and returns the corresponding checked exception back to the client, wrappering the fault data. For more information about exceptions and faults, see the topic on using business exceptions with SCA interfaces.

  • Mapping an output return value to a response message payload

    The return value of the service method is marshalled in a similar manner to the unmarshalling of the request message input. The marshalling uses JAXB and JAX-WS technology to map to XML in a WSDL defined format such that the WSDL is specified explicitly or the runtime environment generates the WSDL from the Java interface. The resulting XML of the response BytesMessage is deserialized using JAXB unmarshalling and returned to the client.

• BytesMessage wire format that maps to single byte array messages

  Use the wireFormat.jmsBytes format to map between the payload of a BytesMessage and a byte[] argument or return value. To specify this wire format, add the following wire format element to the composition definition file:

  OSOA

  {http://tuscany.apache.org/xmlns/sca/1.0}wireFormat.jmsBytes

  OASIS

  {http://tuscany.apache.org/xmlns/sca/1.1}wireFormat.jmsBytes

  • Mapping a request message payload to input arguments

    When using this wire format, the service interface method must contain a single parameter of type byte[]; for example: void myMethod(byte[] bytes);. The BytesMessage payload that is obtained using the readBytes() method is mapped to this single parameter.

  • Mapping an output return value to a response message payload

    The return type of the service method must be byte[] or void. If the return type is byte[], the return value is set as the response BytesMessage payload.

  • Mapping exceptions to a response message payload

    When using this wire format, ObjectMessage messages are used to map exceptions, as in the ObjectMessage wire format case. If we have a checked exception, the runtime environment sets the exception as the ObjectMessage payload. For an unchecked exception, an instance of RuntimeException is set as the payload of a response ObjectMessage message. In both cases, a Boolean message property with name org_apache_tuscany_sca_fault is set to true on the response message.

• JMS message wire format that does not extract the message payload and maps to the javax.jms.Message class

  We can use a wire format mechanism that instructs the JMS binding to provide the raw JMS message to the service implementation without extracting the payload out of the message. To use this wire format, the service interface must consist of a single method with one input parameter of javax.jms.Message, such as:

  void methodA(javax.jms.Message msg);

  The method name is not important; only the input parameter type is relevant. This method is similar to the javax.jms.MessageListener interface. The support for this method enables existing message-driven beans logic to be reused in SCA component implementations.

  Use the default wire format to enable this mechanism to obtain the raw JMS message. To specify the default wire format, add the following wire format element to the composition definition file:

  OSOA

  {http://tuscany.apache.org/xmlns/sca/1.0}wireFormat.jmsdefault

  OASIS

  {http://docs.oasis-open.org/ns/opencsa/sca/200912}wireFormat.jmsDefault

  Because this wire format is the default, the same result is achieved by not specifying a wire format element.

  This wire format is not the same as the TextMessage JAXB XML format. In this scenario, the wire format selection does not describe a specific format of data on the wire. Instead, the specification of this wire format indicates to the runtime environment to identify this specialty case to obtain the raw JMS message and handle the incoming data by passing the raw JMS message to the application.

  The response message is a TextMessage with a null payload. The response message is sent unless the onMessage method is annotated as a one-way operation.

Message types for SCA references when the JMS binding wire format is predetermined

For an SCA reference to produce messages that are consumed in a predetermined JMS binding wire format, use the following message types:

• TextMessage with serialized XML wire format that maps data using JAXB

  The TextMessage wire format uses JAXB technology to marshal and unmarshal data into XML. To specify this wire format, add the following wire format element to the composite definition file:

  OSOA

  {http://tuscany.apache.org/xmlns/sca/1.0}wireFormat.jmsTextXML

  OASIS

  {http://tuscany.apache.org/xmlns/sca/1.1}wireFormat.jmsTextXML

  • Mapping input arguments to a request message payload

    Using this wire format, the input arguments are marshalled into an XML payload, and added to a request TextMessage. The format of the service is described by a WSDL file interface specified by either a interface.wsdl element from the component service definition, or by a WSDL that is generated from the Java interface of the SCA service if the interface.wsdl element is not explicitly defined. The Java-to-WSDL mapping is based on the JAXB and JAX-WS specifications. This mapping results in a document-literal wrapped WSDL file, and the wrapper element corresponds to the operation name. JAXB marshalling is used to serialize the Java client input arguments into the XML payload.

  • Mapping a response message payload to output return value and exceptions

    The runtime environment first determines whether the response message represents an unchecked exception condition by checking for the org_apache_tuscany_sca_fault Boolean message property. If true on the response message, the runtime environment expects an ObjectMessage as the response. When this condition occurs, a ServiceRuntimeException error is returned to the client. If not set, or set to false, the message is a TextMessage that can represent either a checked exception or output data.

    The return value of the service method is unmarshalled in a similar manner to the marshalling of the request message input. The marshalling uses JAXB and JAX-WS technology to map to XML in a WSDL defined format such that the WSDL is specified explicitly or the runtime environment generates the WSDL from the Java interface. The XML payload of the response TextMessage message is deserialized using JAXB unmarshalling and returned to the client.

    If we have a checked exception, the TextMessage payload contains a fault in XML serialized form. The runtime environment deserializes the fault using JAXB unmarshalling and the corresponding checked exception is sent back to the client, wrappering the fault data. To learn more about exceptions and faults, see the documentation on using business exceptions with SCA interfaces.

• The BytesMessage or TextMessage with serialized XML wire format that maps data using JAXB

  The BytesMessage or TextMessage wire format uses JAXB technology to marshal and unmarshal data into XML. This wire format is the default wire format. Thus, this wire format applies if no wire format element is specified in the composite definition file. To specify this wire format, add the following wire format element to the composite definition file:

  OSOA

  {http://tuscany.apache.org/xmlns/sca/1.0}wireFormat.jmsdefault

  OASIS

  {http://docs.oasis-open.org/ns/opencsa/sca/200912}wireFormat.jmsDefault

  • Mapping input arguments to a request message payload

    Using this wire format, the input arguments are marshalled into an XML payload, and added to a request BytesMessage. The format of the service is described by a WSDL file interface specified by either a interface.wsdl element from the component reference definition, or by a WSDL that is generated from the Java interface of the SCA service if an interface.wsdl element is not defined.

    The runtime Java-to-WSDL mapping is based on the JAXB and JAX-WS specifications. This mapping results in a document-literal wrapped WSDL file, and the wrapper element corresponds to the operation name, except when there is a single parameter method. A single argument input parameter is never wrapped by a wrapper element corresponding to the operation name. JAXB marshalling is used to serialize the Java client input arguments into the XML payload.

  • Mapping a response message payload to output return value and exceptions

    The runtime environment first determines whether the response message represents an unchecked exception condition by checking for the org_apache_tuscany_sca_fault Boolean message property. If true on the response message, the runtime environment expects an ObjectMessage as the response. When this condition occurs, a ServiceRuntimeException error is returned to the client. If not set, or set to false, the message is a BytesMessage or TextMessage that can represent either a checked exception or output data.

    If we have a checked exception, the BytesMessage or TextMessage payload contains a fault in XML serialized form. The runtime environment deserializes the fault using JAXB unmarshalling and the corresponding checked exception is sent back to the client, wrappering the fault data. To learn more about exceptions and faults, see the topic on using business exceptions with SCA interfaces.

    For non-exception output data, the return value of the service method is unmarshalled in a similar manner to the marshalling of the request message input. The unmarshalling uses JAXB and JAX-WS technology to map to XML in a WSDL defined format such that the WSDL is specified explicitly or the runtime environment generates the WSDL from the Java interface. The XML payload is always expected to be in unwrapped format even if the WSDL defines a wrapper with an operation name. The XML payload of the response BytesMessage or TextMessage is deserialized using JAXB unmarshalling and returned to the client.

• ObjectMessage wire format that maps to the java.lang.Object class

  The ObjectMessage wire format uses serialized Java objects. To specify this wire format, add the following wire format element to the composition definition file:

  OSOA

  {http://tuscany.apache.org/xmlns/sca/1.0}wireFormat.jmsObject

  OASIS

  {http://tuscany.apache.org/xmlns/sca/1.1}wireFormat.jmsObject

  • Mapping input arguments to a request message payload

    The arguments that are passed to the SCA reference are wrapped in an array and are set into the request ObjectMessage payload using the setObject() method, except for methods with exactly one parameter. By default, arguments are not wrapped in an array for methods with a single argument unless the wrapSingle attribute is set to true on the wireFormat.jmsObject element.

  • Mapping a response message payload to output return value and exceptions

    The runtime environment obtains the response ObjectMessage payload using the getObject() method. If the payload object is an unchecked exception, a ServiceRuntimeException error is returned to the client. If the payload object is an instance of a checked exception, the checked exception is returned to the client If the payload object represents non-exception output data, that payload object is returned back to the client application.

• TextMessage wire format that maps to single string messages

  Use the wireFormat.jmsText format to map between the payload of a TextMessage and a single String argument or return value. To specify this wire format, add the following wire format element to the composition definition file:

  OSOA

  {http://tuscany.apache.org/xmlns/sca/1.0}wireFormat.jmsText

  OASIS

  {http://tuscany.apache.org/xmlns/sca/1.1}wireFormat.jmsText

  • Mapping input arguments to a request message payload

    When using this wire format, the service interface method typically has a single parameter of type String ; for example: void myMethod(String str). The single String passed to the SCA reference is set into the request TextMessage payload by the setText() method.

    For method signatures with different input parameters, the result of performing a String.valueOf() method on the first argument is set as the payload, regardless of how many arguments are present.

  • Mapping a response message payload to output return value and exceptions

    The return type of the service method is must be either String or void; for example: String myMethod(String str).

    The runtime environment first determines whether the response message represents an exception condition by checking for the org_apache_tuscany_sca_fault Boolean message property. If true on the response message, the runtime environment expects an ObjectMessage message as the response, and the message payload is obtained by the getObject() method. If the payload object is an unchecked exception, a ServiceRuntimeException is returned back to the client. If the payload object is an instance of a checked exception, that checked exception is returned to the client.

    If not set, or set to false, the runtime environment expects non-exception output data and a TextMessage response. In this case, if the return type is String, a getText() method used to obtain the payload object that will be returned to the client application as a String value.

• The BytesMessage with XML wire format that maps data using JAXB

  The BytesMessage wire format uses JAXB technology to marshal and unmarshal data into XML. To specify this wire format, add the following wire format element to the composite definition file:

  OSOA

  {http://tuscany.apache.org/xmlns/sca/1.0}wireFormat.jmsBytesXML

  OASIS

  {http://tuscany.apache.org/xmlns/sca/1.1}wireFormat.jmsBytesXML

  • Mapping input arguments to a request message payload

    Using this wire format, the input arguments are marshalled into an XML payload, and added to a request BytesMessage. The format of the service is described by a WSDL file interface specified by either a interface.wsdl element from the component reference definition, or by a WSDL that is generated from the Java interface of the SCA service if an interface.wsdl element is not defined.

    The runtime Java-to-WSDL mapping is based on the JAXB and JAX-WS specifications. By default, this mapping results in a document-literal wrapped WSDL file, and the wrapper element corresponds to the operation name. JAXB marshalling is used to serialize the Java client input arguments into the XML payload.

  • Mapping a response message payload to output return value and exceptions

    The runtime environment first determines whether the response message represents an unchecked exception condition by checking for the org_apache_tuscany_sca_fault Boolean message property. If true on the response message, the runtime environment expects an ObjectMessage as the response. When this condition occurs, a ServiceRuntimeException error is returned to the client. If not set, or set to false, the message is a BytesMessage that can represent either a checked exception or normal output data.

    If we have a checked exception, the BytesMessage payload contains a fault in XML serialized form. The runtime environment deserializes the fault using JAXB unmarshalling and the corresponding checked exception is sent back to the client, wrappering the fault data. To learn more about exceptions and faults, see the topic on using business exceptions with SCA interfaces.

    For non-exception output data, the return value of the service method is unmarshalled in a similar manner to the marshalling of the request message input. The unmarshalling uses JAXB and JAX-WS technology to map to XML in a WSDL defined format such that the WSDL is specified explicitly or the runtime environment generates the WSDL from the Java interface. The XML payload of the response BytesMessage is deserialized using JAXB unmarshalling and returned to the client.

• BytesMessage wire format that maps to single byte array messages

  Use the wireFormat.jmsBytes format to map between the payload of a BytesMessage and a single byte[] argument or return value. To specify this wire format, add the following wire format element to the composition definition file:

  OSOA

  {http://tuscany.apache.org/xmlns/sca/1.0}wireFormat.jmsBytes

  OASIS

  {http://tuscany.apache.org/xmlns/sca/1.1}wireFormat.jmsBytes

  • Mapping input arguments to a request message payload

    When using this wire format, the service interface method must contain a single parameter of type byte[]; for example: void myMethod(byte[] bytes);. The single argument is mapped to a BytesMessage payload using the writeBytes() method.

  • Mapping a response message payload to output return value and exceptions

    The return type of the service method must be byte[] or void.

    The runtime environment first determines whether the response message represents an exception condition by checking for the org_apache_tuscany_sca_fault Boolean message property. If true on the response message, the runtime environment expects an ObjectMessage message as the response, and the message payload is obtained by the getObject() method. If the payload object is an unchecked exception, a ServiceRuntimeException error is returned to the client. If the payload object is an instance of a checked exception, that checked exception is returned to the client

    If not set, or set to false, the runtime environment expects non-exception output data and a BytesMessage response message. In this case, a readBytes() method is used to obtain the payload object that will be returned to the client application as a byte[] value.

Message types for SCA services and references when the JMS binding wire format is not predetermined

Suppose you are adding a JMS binding to an SCA service or reference to produce messages that will be consumed at a future time by a JMS producer or consumer, and there is not a predetermined wire format.

It is a best practice to use the default wire format when starting with the SCA application. Use the JAXB programming model with the top-down approach to developing SCA applications as these service implementations and clients easily used with the SCA default binding, the SCA web service binding, and the SCA JMS binding. Adopting an XML-centric view of the business data provides maximum portability across diverse platforms and technologies, and takes advantage of the design goals of a typical SOA environment. To learn more about top-down development of SCA applications, see the developing SCA applications from existing WSDL files documentation.

If we have business data described within Java classes that implement the Java serialization interface, java.io.Serializable, but the JAXB marshalling and unmarshalling does not satisfactorily preserve the data over the wire, we can use the ObjectMessage wire format.

Related tasks

Develop SCA services from existing WSDL files

Configure SCA JMS binding wire formats