This chapter lists and summarizes the Oracle Service Bus classes and interfaces provided in the Transport SDK. For information on which interfaces are required to develop a custom transport provider, see Chapter 39, "Developing a Transport Provider."
This chapter includes these sections:
Section 41.4, "Source and Transformer Classes and Interfaces"
Section 41.5, "Metadata and Header Representation for Request and Response Messages"
The classes and interfaces discussed in this chapter are located in OSB_ORACLE_HOME/lib/sb-kernel-api.jar unless otherwise noted.
For details on classes and methods, see the Oracle Fusion Middleware Java API Reference for Oracle Service Bus.
A number of 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/sb-schemas.jar
where OSB_ORACLE_HOME is the directory in which you installed Oracle Service Bus.
Schema-Generated Interfaces
EndPointConfiguration – The base type for endpoint configuration. An endpoint is an Oracle 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 such 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 whether this provider generates a service description (for example, WSDL) for its endpoints; whether this provider supports inbound (proxy) endpoints; or whether this provider supports outbound (business service) endpoints.
This section summarizes general classes and interfaces of the Transport SDK.
This section includes these topics:
Section 41.3.2, "Summary of General Interfaces"
Note:
For detailed information on each class and interface listed in this section, refer to the Oracle Fusion Middleware Java API Reference for Oracle Service Bus.
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/modules/com.bea.common.configfwk_version.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/modules/com.bea.common.configfwk_<version>.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/modules/com.bea.common.configfwk_version.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/modules/com.bea.common.configfwk_version.jar.
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.
interface BindingTypeInfo – Describes the binding details of the service. The implementation is a convenience wrapper class around several internal Oracle 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/modify WLS related artifacts along with an Oracle Service Bus deployment. For example, in certain cases, WLS queues need to be deployed in response to the creation of a service.
Tip:
For more information, see Section 39.11, "When to Implement TransportWLSArtifactDeployer."
interface SelfDescribedTransportProvider – Extends TransportProvider. Those 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 those services that are self-described (for example, EJB services).
interface WsdlDescription – Describes the WSDL associated with a registered Oracle 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 Oracle Service Bus binding used during the generation of effective WSDLs for WSDL-based transports. The object can facilitate in generating 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 (which extends TransportSender) from which the provider can retrieve the payload and metadata for outbound requests.
interface CredentialCallback – Transport providers get an instance of this callback interface from Oracle Service Bus. The transport provider can call its methods to fetch a credential used for outbound authentication.
interface TransportEndPoint – A transport endpoint is an Oracle Service Bus entity/resource where service messages are originated or targeted.
Following are descriptions of the base Source and Transformer interfaces, along with several concrete Sources provided with Oracle Service Bus and some supporting classes.
For more information, see Section 38.8, "Designing for Message Content."
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 through the two methods defined in this interface. Source may or may not take into account various TransformOptions (for example, 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" (valid).
If you create a Source class that implements the Source interface, Oracle 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, Oracle Service Bus calls getInputStream() only once; however, Oracle 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. 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.
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.
Note:
Because this stream is backed by an InputStream, that means that this source 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 any type of source. 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. 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.
Note:
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/OutputStream methods of the Source interface, since that is effectively also a transformation between the Source and the byte-level representation in the InputStream/OutputStream.
class JavaObjectSource – A JavaObjectSource represents the payload carried by Oracle 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 proxy service 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 – A 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 proxy service 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.
This section lists classes and interfaces that deal with request and response message metadata representation. See also Section 39.5, "Handling Messages," and Section 38.8, "Designing for Message Content."
This section includes these topics:
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 Chapter 41, "Transport SDK Interfaces and Classes." See also Section 39.5.5, "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.
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 – Inbound Transport Message Context implements the message context abstraction for incoming messages.
interface OutboundTransportMessageContext – Outbound Transport Message Context 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.
This section includes these topics:
Because each transport provider can decide on a list of service endpoint specific configuration properties to persist, a flexible user interface is required that allows the user to enter provider-specific configuration properties for each new service endpoint. What follows is a set of classes and interfaces that allow each transport provider to expose its own properties for the user to enter as part of Oracle Service Bus service definition wizard in the Oracle Service Bus Administration Console.
This section lists interfaces and classes used to develop the user interface for a new transport.
interface TransportProviderFactory – This interface is the extension point to plug custom Oracle Service Bus transports into Eclipse.
interface TransportUIBinding – Represents an object responsible for rendering provider-specific UI pages used during the service definition, summary, as well as validation of transport provider specific endpoint configurations.
interface CustomHelpProvider – Lets you provide context-sensitive help for functionality you add to the Oracle Service Bus Administration Console, such as custom transports. For implementation details, see Section 39.12, "Creating Help for Custom Transports."
class TransportUIContext – Supplies options for the transport provider specific user interface. It is passed by Oracle Service Bus Administration Console to each transport provider.
class TransportUIGenericInfo – Holds transport specific UI information for the common transport page in the Oracle Service Bus Service Definition wizard.
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 Oracle Service Bus Administration Console service registration wizard.
class TransportViewField – Represents a single read-only UI element in the provider-specific portion of the service summary page Oracle Service Bus Administration Console service registration wizard.
class TransportUIError – Returns validation errors to the Oracle Service Bus Administration Console.