D Transport SDK Interfaces and Classes

This appendix lists and summarizes the classes and interfaces provided in the Service Bus Transport SDK.

For information on which interfaces are required to develop a custom transport provider, see Developing Custom Transport Providers.

This appendix includes the following sections:

D.1 Introduction

The Transport SDK classes and interfaces discussed in this chapter are located in OSB_ORACLE_HOME/lib/modules/oracle.servicebus.kernel-api.jar unless otherwise noted. OSB_ORACLE_HOME is the location in which you installed Service Bus.

For details on classes and methods, see the Java API Reference for Oracle Service Bus.

D.2 Schema-Generated Interfaces

A number of Transport SDK interfaces are generated from XML Schema by an XML Schema compiler tool. The source (XML Schema) for the following interfaces is provided in the file TransportCommon.xsd. This file is the base schema definition file for service endpoint configurations. This file is located in OSB_ORACLE_HOME/lib/modules/oracle.servicebus.kernel-api.jar.

The following interfaces are schema-generated:

  • EndPointConfiguration: The base type for endpoint configuration. An endpoint is a Service Bus resource where messages are originated or targeted. EndPointConfiguration describes the complete set of parameters necessary for the deployment and operation of an inbound or outbound endpoint.

  • RequestMetaDataXML: The base type for the metadata of an inbound or outbound request. Metadata is not carried in the payload of the message, but separately and is used as the context for processing the message. Examples of information that might be transmitted in the metadata are the Content-Type header, security information, or locale information.

  • RequestHeadersXML: The base type for a set of inbound or outbound request headers.

  • ResponseMetaDataXML: The base type for response metadata for an inbound or outbound message.

  • ResponseHeadersXML: The base type for a set of response headers.

  • TransportProviderConfiguration: Allows you to configure (a) whether this provider generates a service description (for example, WSDL) for its endpoints; (b) whether this provider supports inbound (proxy) endpoints; or (c) whether this provider supports outbound (business service) endpoints.

D.3 General Classes and Interfaces

This section summarizes the general Transport SDK classes and interfaces that you use when developing your own custom transports. For detailed information on each class and interface listed in this section, refer to the Java API Reference for Oracle Service Bus.

D.3.1 Summary of General Classes

class TransportManagerHelper: Helper class that allows the client to execute some common tasks with respect to the transport subsystem.

class ServiceInfo: Wrapper class that describes information about a service, such as its transport configuration and its binding type.

class TransportOptions: Supplies options for sending or receiving a message. There are two styles for using TransportOptions: multiline setup and single-line use.

class EndPointOperations: Describes different types of transport endpoint lifecycle-related events by which the transport provider is notified. Nested classes include: CommonOperation, Create, Delete, EndPointOperationTypeEnum, Resume, Suspend, and Update.

class Ref: Uniquely represents a resource, project or folder that is managed by the configuration system. This class is located in OSB_ORACLE_HOME/lib/modules/oracle.servicebus.configfwk.jar.

class TransportValidationContext: Container that supplies information to transport providers that can be used when implementing validation checks of endpoint configuration.

class Diagnostics: Contains a collection of Diagnostic entries relevant to a particular resource. This class is located in OSB_ORACLE_HOME/lib/modules/oracle.servicebus.configfwk.jar.

class Diagnostic: Represents a particular validation message related to a resource. Diagnostic objects are generated as a result of validation that is performed when a resource changes. Such changes in the system trigger validation for the changed resource, as well as all other resources that (transitively) depend on the changed resource. This class is located in OSB_ORACLE_HOME/lib/modules/oracle.servicebus.configfwk.jar.

class NonQualifiedEnvValue: Represents an instance of an environment-dependent value in configuration data. Environment-dependent values normally change when moving the configuration from one domain to another. For example the URI of a service could be different on test domain and production domains. This class is located in OSB_ORACLE_HOME/lib/modules/oracle.servicebus.configfwk.jar.

D.3.2 Summary of General Interfaces

interface TransportManager: A singleton object that provides the main point of centralization for managing different transport providers, endpoint registration, control, processing of inbound and outbound messages, and other points.

interface TransportProvider: Represents the central point for management of transport protocol-specific configuration and runtime properties. There is a single instance of TransportProvider for every supported protocol. For example, there is a single instance of HTTP transport provider, JMS transport provider, and so on.

interface BindingTypeInfo: Describes the binding details of the service. The implementation is a convenience wrapper class around several internal Service Bus structures. Additional methods can be added as needed by transport providers.

interface TransportWLSArtifactDeployer: The plug-in interface for modules that need to deploy, undeploy, or modify Oracle WebLogic Server related artifacts along with a Service Bus deployment. For example, in certain cases, Oracle WebLogic Server queues need to be deployed in response to the creation of a service.


For more information, see When to Implement TransportWLSArtifactDeployer.

interface SelfDescribedTransportProvider: Extends TransportProvider. The transport providers that generate a service binding type description from a given transport endpoint need to implement this interface. An example is the EJB transport provider.

interface SelfDescribedBindingTypeInfo: Extends the BindingTypeInfo interface for services that are self-described, such as EJB services.

interface WsdlDescription: Describes the WSDL document associated with a registered Service Bus service.

interface TransportCustomBindingProvider: Represents a class responsible for facilitating the generation of the extensible elements of SOAP binding or all the elements of custom Service Bus binding used during the generation of effective WSDL documents for WSDL-based transports. This includes information such as the transport URI for the <soap:binding> element and the location attribute for <soap:address>.

interface ServiceTransportSender: Sends outbound messages to a registered service associated with a transport endpoint. TransportProvider.sendMessageAsync() gets an instance of ServiceTransportSender from which the provider can retrieve the payload and metadata for outbound requests. This interface extends TransportSender.

interface CredentialCallback: Transport providers get an instance of this callback interface from Service Bus. The transport provider can call its methods to fetch a credential used for outbound authentication.

interface TransportEndPoint: A transport endpoint is an Service Bus entity or resource where service messages are originated or targeted.

D.4 Source and Transformer Classes and Interfaces

This section provides descriptions of the base Source and Transformer interfaces, along with several concrete Sources provided with Service Bus and some supporting classes. For more information, see Designing for Message Content .

D.4.1 Summary of Source and Transformer Interfaces

interface Source: Represents source content in some form. Sources may be transformed into other Sources through a Transformer instance. At minimum, a Source must natively support conversion to a byte-based stream using the two methods defined in this interface. Source may or may not take into account various TransformOptions, such as character-set encoding, during serialization.

interface SingleUseSource: A marker interface indicating that a type of Source can only be consumed once. It also provides one helper method that can be used to determine if the Source is still consumable, or valid.

If you create a Source class that implements the Source interface, Service Bus is free to call the getInputStream() method multiple times, each time retrieving the input stream from the beginning. If the Source class implements SingleUseSource, Service Bus calls getInputStream() only once; however, Service Bus buffers the entire message in memory in this case.

interface Transformer: Transforms one type of Source to another. The instance is responsible for indicating what types of sources it can convert between. Note that a transformer is required to support the full cross-product of transformations implied by the supported input and output sources. In other words, a transformer must support transforming any supported input source to any supported output source.

D.4.2 Summary of Source and Transformer Classes

class StreamSource: A byte-stream Source whose content comes from an InputStream. As a byte-stream source, the serialization methods do not heed any transformation options.


Because this stream is backed by an InputStream, this is a single-use Source. Both serialization methods pull from the same underlying InputStream, and once that content is consumed, it is gone. The push-based writeTo() method results in all data being consumed immediately, assuming no error occurs. The pull-based getInputStream() actually gives the underlying InputStream directly to the caller.

class ByteArraySource: A byte-stream Source whose content comes from a byte array. As a byte-stream source, the serialization methods do not heed any transformation options.

class StringSource: A Source that is backed by a single String. Serialization is simply a character-set encoded version of the character data.

class XmlObjectSource: Apache XBean Source content is represented as an Apache XBean. The XBean may be typed and so may be accompanied by a SchemaType object and an associated ClassLoader. However, both of these are entirely optional and the XBean can be untyped XML.

class DOMSource: A Source whose content comes from a DOM node. The referenced node may be a full-fledged org.w3c.dom.Document, but it may also be an internal node in a larger document.

class MFLSource: Represents MFL content. MFL data is essentially binary data that has some logical structure imposed on it by an MFL definition. CSV is a simple example of MFL data, but the structure can be arbitrarily complex. The logical/in-memory representation of the data is an XML document, but its serialized representation is the raw unstructured binary data.

class SAAJSource: A Source that is backed by a SAAJ SOAPMessage object. A SAAJSource is typically converted to and from MessageContextSource and MimeSource.

class MimeSource: A Source representing arbitrary content with headers. Essentially this is a Source that represents a MIME part. Headers must conform to RFC822 whereas the Source can be of any type. The serialization format for this Source is a fully-compliant MIME package. This Source is also aware of Content-Transfer-Encoding, and it will perform the proper encoding of the underlying content stream if the header is present. Note that this means that the Source provided to the constructor should be in raw form and not be already encoded.

class MessageContextSource: A Source that represents all message content. The Source for the message and attachments are left untyped to allow for deferred processing. Eventually, however, the attachments source will likely be converted into an object and the message source will likely be converted to a specific typed source such as an XmlObjectSource or a StringSource.


The serialization format of a MessageContextSource is always a MIME multipart/related package, irrespective of the native serializations of the message and attachment sources. However, if this serialized object is needed more than once, it is best to transform the Source into a MimeSource.

class TransformOptions: Represents a set of transformation options. Instances of this class are used in conjunction with the Transformer class to influence how an input source is converted to an output source (for example, a change in character-set encoding from SHIFT_JIS to EUC-JP). This class is also used by the InputStream and OutputStream methods of the Source interface, since that is effectively also a transformation between the Source and the byte-level representation in the InputStream and OutputStream.

class JavaObjectSource: Represents the payload carried by Service Bus transports that provide a Java messaging type, such as the JMS transport. The objects that make up this payload are registered in the pipeline Java object repository by the binding layer, and their contents are visible in message context variables through <ctx:java-content ref='jcid:xyz' xmlns:ctx="http://www.bea.com/wli/sb/context" /> XML elements. In this example, ref points to the unique ID of the object in the Java object repository.

class JavaXmlSource: Represents the payload carried by the services that supports Java objects as the arguments, such as the JEJB transport. JavaXmlSource is made up of an XML representation that defines the shape of the message body in the pipeline and a map containing Java objects against unique keys. In the XML representation, Java object arguments are substituted by <ctx:java-content ref='jcid:xyz' xmlns:ctx="http://www.bea.com/wli/sb/context" /> elements, where the ref attribute equals a key in the JavaObjects map that indexes the replaced Java object. The map contains the objects to be registered in pipeline Java object repository against the unique IDs in the XML representation.

D.5 Metadata and Header Representation for Request and Response Messages

This section lists classes and interfaces that deal with request and response message metadata representation. For additional information, see Handling Messages and Designing for Message Content .

D.5.1 Runtime Representation of Message Contents

abstract class CoLocatedMessageContext: Needs to be extended by a transport provider that implements optimization for co-located outbound calls to go through a Java method invocation instead of the transport layer. For an example implementation, see the class com.bea.alsb.transports.sock.SocketCoLocatedMessageContext.java, which is part of the Sample Socket Transport described in Creating a Sample Socket Transport Provider. For additional information, see Co-Located Calls."

abstract class RequestHeaders: Represents a union of standard and user-defined headers in a given inbound or outbound request message. The set of standard headers is specific to each transport provider. This is an abstract class to be extended by each transport provider to implement its version of request headers.

abstract class RequestMetaData<T extends RequestHeaders>: Represents inbound or outbound request message metadata information (for example, headers, request character set encoding, and so on.) Transport providers provide an extension of this class that adds metadata information applicable to the transport provider. For example, HTTP transport provider adds get/setQueryString(), get/setClientHost(), and other methods.

abstract class ResponseHeaders: Represents a union of standard and user-defined headers in a given inbound or outbound response message. The set of standard headers is specific to each transport provider. This is an abstract class to be extended by each transport provider to implement their version of response headers.

abstract class ResponseMetaData<T extends ResponseHeaders>: Represents inbound or outbound response message metadata information (such as headers, request character set encoding, and so on.) Transport providers provide an extension of this class that adds metadata information applicable to the transport provider. For example, HTTP transport provider adds get/setHttpResponseCode() and other methods.

D.5.2 Interfaces

interface TransportMessageContext: Most message-oriented middleware (MOM) products treat messages as lightweight entities that consist of a header and a payload. The header contains fields used for message routing and identification; the payload contains the application data being sent. In general, the transport-level message context consists of a message ID, RequestMetadata, request payload, ResponseMetaData, response payload and related properties.

interface InboundTransportMessageContext: Implements the message context abstraction for incoming messages.

interface OutboundTransportMessageContext: Implements the message context abstraction for outgoing messages.

interface ServiceTransportSender: Sends outbound messages to a registered service. The service is associated with a transport endpoint.

interface TransportSendListener: This is the callback object supplied to the outbound transport allowing it to signal to the system that response processing can proceed. This callback object should be invoked on a separate thread from the request message.

D.6 User Interface Configuration

Each transport provider can decide on a list of service endpoint specific configuration properties to persist, so a flexible user interface is required that allows the user to enter provider-specific configuration properties for each new service endpoint. The set of classes and interfaces described in this section allow each transport provider to expose its own properties for the user to enter as part of the service definition editors in the Oracle Service Bus Console. Use these interfaces and classes to develop the user interface for a new transport.

D.6.1 Summary of UI Interfaces

interface TransportProviderFactory: This interface registers the new transport provider with the transport manager.

interface TransportUIBinding: Represents an object responsible for rendering provider-specific UI pages used for defining the service, providing a summary, and validating transport provider specific endpoint configurations.

interface CustomHelpProvider: Lets you provide context-sensitive help for the functionality you add to the Oracle Service Bus Console, such as custom transports. For implementation details, see Creating Help for Custom Transports.

D.6.2 Summary of UI Classes

class TransportUIContext: Supplies options for portions of the user interface that are specific to the transport provider. It is passed by the Oracle Service Bus Console to each transport provider.

class TransportUIGenericInfo: Holds transport-specific UI information for the common transport page in the service definition editors.

class TransportUIFactory: Provides factory methods for creating a Transport Edit Field and different kinds of Transport UI objects associated with the field. Also provides some helper methods for accessing values in these objects.

class TransportEditField: Represents a single editable UI element in the provider-specific portion of the Oracle Service Bus Console service definition editors.

class TransportViewField: Represents a single read-only UI element in the provider-specific portion of the service summary page.

class TransportUIError: Returns validation errors to the Oracle Service Bus Console.