This chapter lists and summarizes the classes and interfaces provided by the Transport SDK. For information on which interfaces are required to develop a custom transport provider, see Developing a Transport Provider.
All of the classes and interfaces discussed in this chapter are defined in the package com.bea.wli.sb.transports, and are part of sb-public.jar, which is listed on the system CLASSPATH after AquaLogic Service Bus is installed.
Schema-Generated Interfaces
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 BEA_HOME/weblogic92/servicebus/lib/sb-public.jar
where BEA_HOME is the directory in which you installed AquaLogic Service Bus.
EndPointConfiguration - The base type for endpoint configuration. An endpoint is an AquaLogic 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 (a) whether this provider generates a service description (for example, WSDL) for its endpoints; (b) whether or not this provider supports inbound (proxy) endpoints; or (c) whether or not this provider supports outbound (business service) endpoints.
General Classes and Interfaces
This section summarizes general classes and interfaces of the Transport SDK.
For detailed information on each class and interface listed in this section, refer to the AquaLogic Service Bus Javadoc description.
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.
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.
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.
class EnvValue - 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.
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.
interface BindingTypeInfo - Describes the binding details of the service. The implementation is a convenience wrapper class around several internal AquaLogic Service Bus structures. Additional methods can be added as needed by transport providers.
interface TransportWLSArtifactDeployer - The plugin interface for modules that need to deploy/undeploy/modify WLS related artifacts along with an AquaLogic Service Bus deployment. For example, in certain cases, WLS queues need to be deployed in response to the creation of a service.
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 WsdlDescription - Describes the WSDL associated with a registered AquaLogic Service Bus service.
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 AquaLogic Service Bus. The transport provider can call its methods to fetch a credential used for outbound authentication.
interface TransportEndPoint - A transport endpoint is an AquaLogic Service Bus entity/resource where service messages are originated or targeted.
Source and Transformer Classes and Interfaces
Below is a description of the base Source and Transformer interfaces, along with several concrete Sources provided with AquaLogic Service Bus and some supporting classes. For more information, see Designing for Message Content.
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 via 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, AquaLogic 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, AquaLogic Service Bus calls getInputStream() only once; however, AquaLogic 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.
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.
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. 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 AttachmentsSource 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 AttachmentsSource - A Source representing a set of attachments. Its stream representation is equivalent to the stream representation of the $attachments variable. In other words, the stream representation is XML (not MIME).
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.
Metadata and Header Representation for Request and Response Messages
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 Transport SDK Interfaces and Classes. See also 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.
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 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.
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 AquaLogic Service Bus service definition wizard.
This section lists interfaces and classes used to develop the user interface for a new transport.
Summary of UI Interfaces
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.
Summary of UI Classes
class TransportUIContext - Supplies options for the transport provider specific user interface. It is passed by AquaLogic Service Bus Console to each transport provider.
class TransportUIGenericInfo - Holds transport specific UI information for the common transport page in the AquaLogic 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 AquaLogic Service Bus Console service registration wizard.
class TransportViewField - Represents a single read-only UI element in the provider-specific portion of the service summary page AquaLogic Service Bus Console service registration wizard.
class TransportUIError - Returns validation errors to the AquaLogic Service Bus Console.
