Transport SDK User Guide

Developing ALSB Transports for WorkSpace Studio

This chapter documents the best practices, design considerations, and packaging to develop transports for ALSB WorkSpace Studio design time. The Transport SDK interface provides a bridge between transport protocols and the ALSB run time.

Tip:

Before you begin this chapter, review Design Considerations.

This chapter includes the following sections:

Introduction

ALSB transports were originally designed to be deployed on ALSB servers and configured through the ALSB console. With design environments like WorkSpace Studio, some modifications to the SDK and the existing transports are necessary.

This document describes the additional steps to ensure ALSB transports design time can be used on platforms outside the ALSB console.

The sample socket transport was ported to WorkSpace Studio and can be considered a best practice for WorkSpace Studio integration. The sample socket resources are located at ALSB_HOME/samples/servicebus/sample-transport/. The Java source files are in the /src subdirectory. The sample also contains a build script that automatically packages the sample socket transport for both WorkSpace Studio integration and ALSB console deployment. For information on building and deploying the sample socket transport, see Sample Socket Transport Provider.

Services Runtime and Services Configuration

When you develop a transport, you should distinguish the runtime aspects from the configuration aspects. The runtime aspects include proxy or business service deployment and service run-time invocation. The configuration aspects include proxy or service configuration and validation.

The runtime aspects do not need to change since they are always exercised in the context of a running ALSB server. However, the configuration aspects are dependent on the design environment.

Developers should consider three different modes:

Online mode – The services for the custom transport are configured with the ALSB console on a running ALSB server.
Offline mode – The transport is configured with a design environment running outside the ALSB server. No remote server is available.
Offline mode with remote server – The transport is configured with a design environment running outside the ALSB server. However, a remote server is available and can be used for both validation and configuration purposes.

Transports running in WorkSpace Studio must support offline mode and, optionally, offline mode with a remote server.

This section contains the following topics:

Offline Methods

When you deploy a transport in offline mode, the configuration framework creates a single session for all the resource configurations. This session is never activated. Since proxy or business services can only be deployed on a running ALSB server, there is no need to activate the session. However, it is still important to detect conflicts and configuration errors and the validation methods are still exercised.

Following is a list of the minimum set of classes and methods defined by the Transport SDK that must be implemented in offline mode. The exceptions were removed from the methods signature for better readability.

Note:

You do not need to completely re-implement your transport for offline mode. In most cases your transport will only need a few changes to existing methods to support both online and offline modes.

The public interface TransportProvider class

String getId();
void validateEndPointConfiguration(TransportValidationContext context);
SchemaType getEndPointConfigurationSchemaType();
SchemaType getRequestMetaDataSchemaType();
SchemaType getRequestHeadersSchemaType();
SchemaType getResponseMetaDataSchemaType();
SchemaType getResponseHeadersSchemaType();
TransportProviderConfiguration getProviderConfiguration();
TransportUIBinding getUIBinding(TransportUIContext context);
void shutdown();
Collection<NonQualifiedEnvValue> getEnvValues(Ref ref,
     EndPointConfiguration epConfig);
void setEnvValues(Ref ref, EndPointConfiguration epConfig,
     Collection<NonQualifiedEnvValue> envValues);
Collection<Ref> getExternalReferences(EndPointConfiguration epConfig);
void setExternalReferences(Map<Ref, Ref> mapRefs, EndPointConfiguration
     epConfig);
Map<String, String> getBusinessServicePropertiesForProxy(Ref ref);
XmlObject getProviderSpecificConfiguration(Ref ref, Map<String, String>
     props);

The public interface TransportProviderFactory class

This interface registers transports in offline mode. See Deploying a Transport Provider for more details.

The public interface TransportUIBinding class

You should implement all the methods in this interface and define the user interface used to configure a proxy or business service.

The public class TransportManagerHelper class

This class is typically used by TransportProvider developers. However, some of the methods that are not valid in offline mode will throw exceptions, which are described below. Other methods are meant only for runtime or deployment, such as public isAdmin().

Two methods are also available when working in offline mode with remote server:

The public Set<String> getDispatchPolicies(JMXConnector connector); method
The public DomainRuntimeServiceMBean getDomainRuntimeServiceMBean(JMXConnector connector); method

See Working Offline with a Remote Server for more information.

Do not invoke the following two methods in offline mode:

The isAdmin method throws exceptions (public static boolean isAdmin();). This method throws a java.lang.IllegalStateException message.
The clusterExists() method always returns false (public static boolean clusterExists();). This method always returns false.

Restrictions when Working Offline

When you work offline, none of WebLogic Server services running on the server are available. Do not use these services inside the methods described in Offline Methods.

Following are examples of restrictions for working offline:

The WLS MBeans are not available.
The server Java properties are not available.
You cannot access the JNDI tree directly. However, if JNDI properties are defined in the service configuration, you can attempt to use them.
You can not determine if the service is going to run in a cluster or a standalone server.
You do not have access to WebLogic Server security infrastructure.
You do not have access to any static singleton service located on the server.

Because some of the services are not available, it is necessary to evaluate how the transport user interface is affected. In general, the user interface should be more flexible to let users manually configure values instead of trying to retrieve values from the server environment.

WorkSpace Studio design time does not currently support deployment to an ALSB cluster. Therefore, the user interface must be populated as if there is no cluster. If necessary, the user can use a customization file to update the configuration and force a deployment to an ALSB cluster.

For example, some transports retrieve the list of available WorkManager items by using the TransportManagerHelper and letting the user pick one through a drop-down list. However, in offline mode, the MBeans are not available so the drop-down list cannot be populated. The transport provider has two choices:

Let the user type the correct WorkManager name. In that case, the user interface must be changed to be a text box and not a drop-down list when working offline.
Another less flexible option is to populate the drop-down list with just the default WorkManager. When the service is pushed to a running ALSB server, the WorkManager name can be switched using an environment value substitution.

Working Offline with a Remote Server

When you work offline, a remote server might be available. For instance, when you configure a service on WorkSpace Studio, the user can associate a remote ALSB server to the current project. The transport provider can take advantage of the remote server by accessing the WebLogic Server MBeans and retrieving information. This mode is similar to working online; however, some restrictions still apply since the code is not running on the server and only the MBeans are available.

When you work offline, the following statements apply:

The server Java properties are not available.
You cannot use most of TransportManagerHelper methods as described in Offline Methods.
You cannot access the JNDI tree directly. However if JNDI properties are defined in the service configuration, you can attempt to use them.
You do not have access to any static singleton service located on the server.

To access the MBeans, the framework provides an instance of JMXConnector when it requests the TransportUI object, or when it asks the provider to validate a configuration. The JMXConnector is available in the TransportUIContext or the TransportValidationContext:

JMXConnector connector = (JMXConnector)uiContext.get(TransportValidationContext.JMXCONNECTOR);

For more information, see the sample transport in Reference.

If the connector is not present, a remote server is not available. This connector object can then be used to access the MBeans. Helper methods have been added to the TransportManagerHelper to retrieve the list of WorkManager and WebLogic Server domain MBean.

Note: This behavior is generalized for both online and offline modes. The public static Set<String> getDispatchPolicies() method defined in the TransactionManagerHelper will be deprecated and must be replaced by the same method with JMXConnector as a parameter. If you do not replace it, the following error appears: com.bea.wli.sb.transports.TransportException.

Bootstrapping Transports in Offline Mode

In online mode, transports must be packaged as EAR files and deployed on an ALSB server. When the EAR is loaded at startup, the transport registers a callback on a startup event and registers an instance of the TransportProvider to the TransportManager.

In offline mode, a new mechanism registers transports. The SDK introduces a new interface called com.bea.wli.sb.transports.TransportProviderFactory. A transport developer must implement this interface and must make the default constructor public. The interface is provided in Reference, as well as a sample implementation.

If the TransportProvideFactory is instantiated, you can assume the transport needs to work in offline mode (with or without a remote server).

Note:

You can set a boolean operator in the TransportProviderFactory when the constructor is invoked to determine if the transport is running in offline mode. This information can also be passed in the TransportUIContext and the TransportValidationContext. Your Engineering Department can assist you in making this decision.

Packaging Transports in Offline Mode

In offline mode, you can use transports in different design environments. The WorkSpace Studio environment defines specific packaging, which is described in the next section. In general, transports simply need to be available to external design time environments as a self-contained JAR file. A self-contained JAR file has the JAR file include the transport config.xml file, the header, metadata schemas, XBeans classes, TransportProviderFactory implementation, and the compiled transport classes.

Packaging Transports as WorkSpace Studio Plug-Ins

Packaging your custom transport as a WorkSpace Studio plug-in, in conjunction with your transport user interface implementation, lets service developers select and configure your transport in the development environment.

Figure 4-1 shows the service creation wizard with a drop-down field populated with available transports.

Figure 4-1 A custom transport available when creating a service

Figure 4-2 shows the service editor—after a service has been created—with a configuration page for the selected transport.

Figure 4-2 Transport configuration page in WorkSpace Studio

Note:

Your implementation of the TransportUIBinding interface determines the user interface for selecting and configuring your transport, both in WorkSpace Studio and in the ALSB console.

ALSB provides Eclipse-based plug-ins to WorkSpace Studio. The core ALSB plug-in, com.bea.alsb.core, defines an extension point (com.bea.alsb.core.transports) that is used to register ALSB transports in the WorkSpace Studio environment as plug-ins.

Transport Plug-in Resources

Your transport plug-in must provide the following resources:

MANIFEST.MF file – Contains key information about your transport plug-in. Use the sample socket transport MANIFEST.MF for reference. See MANIFEST.MF.
In the plugin.xml file, provide an extension point that registers your transport with WorkSpace Studio as a plug-in. Use the sample socket transport plug-in as a reference. See plugin.xml.
A transport JAR file containing your transport implementation.
(Optional) Resources for providing online help.

Transport Plug-in Packaging

You can package your transport plug-in either as a JAR file or in an exploded directory. Packaging as a JAR makes the transport more portable. Packaging as an exploded directory lets you reference resources in other ALSB plug-ins. For example, if you want to merge your transport help with the ALSB transport topics in the WorkSpace Studio help system, you must package your transport plug-in in an exploded directory, as described in Providing Custom Transport Help in WorkSpace Studio.

Whether you package your plug-in in a JAR or an exploded directory, you must package your transport implementation in a JAR file.

Use the following guidance for packaging your transport as a plug-in:

To construct the plug-in JAR or exploded directory name, append the Bundle-Version to the Bundle-SymbolicName from the MANIFEST.MF file. For example, the sample socket transport JAR is named Socket_Transport_3.0.0.0.jar.
Package with the following directory structure, as shown in Figure 4-3:

plugin.xml (root of the plug-in)
/lib/your_transport.jar (transport classes and resources)
/META-INF/Manifest.mf
/help – If you are providing help for your transport, include a /help directory for your help resources, as described in Providing Custom Transport Help in WorkSpace Studio.

Figure 4-3 Plug-in packaging

Plug-in packaging

For reference on transport plug-in packaging:

Build the sample socket transport, as described in Sample Socket Transport Provider. View the generated Socket_Transport_3.0.0.0.jar.
View the packaging of the ALSB transports, located at ALSB_HOME/eclipse/plugins/com.bea.alsb.transports.<transport_version>

Reference

This section contains the following topics:

Working in Different Modes

Dispatch Policies are used by most transports and allow services throttling. This code distinguishes the three modes described in Services Runtime and Services Configuration:

Online mode
Offline mode
Offline mode with remote server

The connection to the remote server is retrieved from the context, as shown in Listing 4-1.

Listing 4-1 Connection to the Remote Server

/**
  * Builds the dispatch policies in the ui object.
  *
  * @param curDispatchPolicy
  * @return TransportEditField containing existing dispatch policies.
  */
      public TransportEditField getDispatchPolicyEditField(StringcurDispatch
          Policy) {
          TransportUIFactory.TransportUIObject uiObject = null;
          Set<String> wmSet = null;
          
          if (SocketTransportProviderFactory.isOffline()) { // if on
               Eclipse try to get the MBeans from the UIContext
                    JMXConnector connector = (JMXConnector)uiContext.get
                         (TransportValidationContext.JMXCONNECTOR);
               if (connector != null) {
                    try {
                         wmSet = TransportManagerHelper.getDispatchPolicies
                              (connector);
                    } catch (Exception ex) {
                         wmSet = null; //continue
                    }
               }
          } else { // if running on the server use the helper to get the
               policies
               try {
                    wmSet = TransportManagerHelper.getDispatchPolicies();
               } catch (TransportException e) {
                    SocketTransportUtil.logger
                         .error(SocketTransportMessagesLogger.
                              noDispatchPolicies(), e);
               }
          }

          if (wmSet == null) // if JMXConnector not available or impossible
               to connect provide a simple edit field
          {
               uiObject = TransportUIFactory.createTextBox
                    (curDispatchPolicy);
          } else // create a drop down list
          {
               // adding default work manager to the list.
               wmSet.add(DEFAULT_WORK_MANAGER);
               String[] values = wmSet.toArray(new String[wmSet.size()]);
               uiObject = TransportUIFactory.createSelectObject(
                    values,
                    values,
                    curDispatchPolicy,
                    TransportUIFactory.SelectObject.DISPLAY_LIST,
                         false);
          }
          return TransportUIFactory.createEditField(DISPATCH_POLICY,
               TextMessages.getMessage(TextMessages.DISPATCH_POLICY,
                    locale),
               TextMessages.getMessage(TextMessages.DISPATCH_POLICY_INFO,
                    locale), uiObject);
     }

TransportProviderFactory

TransportProviderFactory, Listing 4-2, lets you provide development-time functionality in WorkSpace Studio.

Listing 4-2 The TransportProviderFactory Class

package com.bea.wli.sb.transports;

import com.bea.wli.sb.transports.TransportException;
import com.bea.wli.sb.transports.TransportManager;

/**
 * This interface is the extension point to plug custom ALSB transports in
   Eclipse.
 * The implementation must declare the default class constructor.
 */
public interface TransportProviderFactory {

     /**
       * Registers a new provider with the transport manager. Typically
       * called by the ALSB core eclipse plugin.
       * @param tm the transport manager to which to register
       */
       public void registerProvider(TransportManager tm) throws
            TransportException;
     /**
        * @return a unique string that identifies this provider, like "http"
       * This method must return the same ID than provider.getId()
       */
     String getId();
}

The code sample in Listing 4-3 shows how the Socket Transport implements this interface

Listing 4-3 Example of the Socket Transport Implementing the Interface

package com.bea.alsb.transports.sock;

import com.bea.wli.sb.transports.TransportManager;
import com.bea.wli.sb.transports.TransportException;
import com.bea.wli.sb.transports.TransportProviderFactory;

public class SocketTransportProviderFactory implements
     TransportProviderFactory {

     public static boolean isOffline() {
          return isOffline;
     }

     private static boolean isOffline = false;

     public void registerProvider(TransportManager tm) throws
          TransportException {
          isOffline = true;
          SocketTransportProvider instance =
               SocketTransportProvider.getInstance();
          tm.registerProvider(instance, null);
     }

     public String getId() {
          return SocketTransportProvider.ID;
     }
}

Extension Point Schema

Listing 4-4 is extracted from the extension point schema that defines the transport element and transport-provider attribute for adding a transport as a WorkSpace Studio plug-in, shown in plugin.xml.

Listing 4-4 Part of the Extension Point Schema

<element name="transport">
     <complexType>
          <attribute name="transport-provider" type="string" use="required">
               <annotation>
                    <documentation>
                    </documentation>
                    <appInfo>
                         <meta.attribute kind="java" basedOn="
                              com.bea.wli.sb.transports.Transport
                              ProviderFactory"/>
                    </appInfo>
               </annotation>
          </attribute>
     </complexType>
</element>

plugin.xml

Listing 4-5 shows the transport extension for the sample socket transport plugin.xml file. The file is located at ALSB_HOME/samples/servicebus/sample-transport/eclipse/.

Listing 4-5 Plugin.xml File

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.2"?>
<plugin>
     <extension
          id="socket"
          name="Socket Transport"
          point="com.bea.alsb.core.transports">
          <transport transport-provider="com.bea.alsb.transports
               .sock.SocketTransportProviderFactory"/>
     </extension>
</plugin>

The extension point attribute value is always com.bea.alsb.core.transports for transports.
The transport-provider attribute is the fully qualified path to your TransportProviderFactory implementation class.

Note:

Transport providers typically are not required to manage the life cycle inside WorkSpace Studio, so there is no need to extend the org.eclipse.core.runtime.Plugin class like a regular plug-in.

If you are providing help for your custom transport in WorkSpace Studio, you will also have help entries in plugin.xml. For more information, see Creating Help for Custom Transports.

MANIFEST.MF

Listing 4-6 shows the sample socket transport MANIFEST.MF file. The file is located at ALSB_HOME/samples/servicebus/sample-transport/eclipse/META-INF/.

Listing 4-6 Sample MANIFEST.MF File

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Socket Transport Plug-in
Bundle-SymbolicName: Socket_Transport;singleton:=true
Bundle-Version: 3.0.0.0
Bundle-Localization: plugin
Bundle-ClassPath: .,
     lib/sock_transport.jar
Require-Bundle: com.bea.alsb.core

Build.xml

Listing 4-7 shows the target to package the sample socket transport for WorkSpace Studio. The file is located at ALSB_HOME/samples/servicebus/sample-transport/.

Listing 4-7 Sample Transport Packaged for WorkSpace Studio

<target name="create_plugin">
     <mkdir dir="${build.dir.transports.sock.eclipse}/plugin"/>
     <copy todir="${build.dir.transports.sock.eclipse}/plugin"
          overwrite="true">
          <fileset dir="${src.dir.transports.sock.eclipse}"/>
     </copy>

     <mkdir dir="${build.dir.transports.sock.eclipse}/plugin/lib"/>
     <copy file="${sock.transport.jar}"
          todir="${build.dir.transports.sock.eclipse}/plugin/lib"
          overwrite="true"/>

     <zip destfile="${sock.transport.eclipse.jar}" basedir="${build.dir.
          transports.sock.eclipse}/plugin"/>
</target>

The build-jar target also builds the sample socket transport plug-in, along with the deployable transport EAR.

For more information on building the sample socket transport, see Sample Socket Transport Provider.

TransportManagerHelper Methods

Listing 4-8 shows the TransportManagerHelper methods.

Listing 4-8 TransportManagerHelper Methods

public static Set<String> getDispatchPolicies(JMXConnector connector)
     throws TransportException;

     public static DomainRuntimeServiceMBean
     getDomainRuntimeService(JMXConnector connector)
          throws TransportException;