This chapter describes how to build and run the sample socket transport provider. This sample and its source code are installed with Service Bus. The sample serves as an example implementation of a custom transport provider.
This chapter includes the following sections:
The primary purpose of the sample socket transport provider is to serve as an example transport provider implementation.
This publicly available sample demonstrates the implementation and configuration details of the Transport SDK.
The sample transport is designed to send and receive streamed data to and from a configured TCP socket in Service Bus. The sample transport illustrates the following Transport SDK concepts:
Implementing the set of Transport SDK APIs that are required to build a custom transport.
Performing transport endpoint validations, such as checking that no socket endpoint is listening on the configured address.
Implementing several UI configuration options, including socket properties and message patterns.
Implementing a one-way or synchronous request-response message pattern.
Using POJOs (Plain Old Java Objects) for metadata and headers of endpoint requests and responses.
Using streaming in Service Bus pipelines.
Figure 43-1 shows the basic architecture of the sample socket transport provider. Any client can connect to the server socket. Data is received at the server socket and passes through the pipeline. The response comes back through the outbound transport. The response is finally sent back to the inbound transport and back to the client.
Figure 43-1 Sample Socket Transport Architecture
Figure 43-2 illustrates the configuration properties for the transport endpoint. These properties are configured in the schema file,
SocketTransport.xsd. For the location of this file, see Sample Location and Directory Structure .. This file allows you to extend the basic set of properties defined in the common schema provided with the SDK. Refer to the
SocketTransport.xsd file for information on each of the properties.
For more information about these configuration properties, see Step 4. Define Transport-Specific Artifacts .
Figure 43-2 SocketEndpointConfiguration Properties
Also in the
SocketTransport.xsd file are the request and response header and metadata properties, as illustrated in Figure 43-3. Refer to the
SocketTransport.xsd file for more information about these properties.
Figure 43-3 Request and Response Header and Metadata Configurations
This section briefly describes some of the key folders in the sample project. You can use this directory structure as a model for developing your custom transport provider.
After you create a sample domain, the sample transport should be in the
Table 43-1 lists and briefly describes key
Table 43-1 Key Sample Transport Provider Directories
This directory is created when you build the sample socket transport. It contains the built and packaged transport for use in Service Bus.
This directory contains these internationalization files. There is one of each file for each supported locale.
This directory contains these application deployment descriptor files:
This directory contains one file,
This directory contains the socket transport provider configuration file used by the Transport SDK, which is named
This directory contains the relevant schemas defined for this transport, in this case,
This directory contains the source tree of the sample transport.
This directory includes a testing utility for the sample transport provider, along with the source tree for the test server and client.
This directory contains the deployment descriptors required for the sample transport help web application.
The following Ant build files are also located in the
build.properties – Properties file for Ant.
build.xml – An Ant build file with different targets for compile, build, stage, and deploy.
Perform the steps provided in this section in the order given to build and deploy the sample transport provider.
A script is provided in the Service Bus domain to configure the environment for building the sample.
To set up the environment:
setDomainEnv.sh on a UNIX system)
Once you set the environment configuration, you can build the transport using the Ant build files provided in the
To build the sample transport provider:
This command compiles the source files in
/lib/transports and copies transport-socket.xml to
The sockets sample also provides automated scripts for you to deploy the sample transport provider to the WebLogic Server. Once the sample is built and staged successfully, you can run the deploy command.
To deploy the sample transport provider:
wls.hostname wls.port wls.username wls.password wls.server.name
If you want to be able to create or import projects in JDeveloper using the sample socket transport provider, you need to modify the transport registration file.
To register the sample transport provider with JDeveloper:
transport-socket.xmlin an XML or text editor.
The final file should look like this:
<plugin xmlns="http://www.bea.com/alsb/offline/extensions"> <transport class="com.bea.alsb.transports.sock.SocketTransportProviderFactory" id="socket" helpId="contexts_socketTransport"/> <libraries> <library name='lib/transports/sock_transport.jar'/> </libraries> </plugin>
The sample consists of a test server and a test client. The client sends a message to the server. You configure Service Bus to receive and process the message.
Perform the tasks in this section in the order given. These instructions are for creating the sample project in the Oracle Service Bus Console, but you can do this in JDeveloper as well.
The first step to creating the sample is to create the actual project that will contain the Service Bus resources.
To create the project:
SocketTestin the Resource Name field.
The new project appears in the Project Definition Editor.
In the sample project, you create a business service to talk to the server.
To create the business service:
The Create Business Service wizard appears.
Figure 43-4 Create Business Service Wizard
The business service appears in the Business Service Definition Editor. You can click the different subtabs to view the configuration.
In this section, you create a proxy service to accept messages from the client.
To create the proxy service:
The Create Proxy Service wizard appears.
Figure 43-5 Create Proxy Service Wizard
The proxy service appears in the Proxy Service Definition Editor. You can click the different subtabs to view the configuration.
Now that the business and proxy services are defined, you can create a pipeline to route incoming messages to the business service.
To create the pipeline:
The Create Pipeline dialog appears.
Figure 43-6 Create Pipeline Dialog
The pipeline appears in the Pipeline Definition Editor. You can click the different subtabs to view the configuration.
The Edit Message Flow window appears.
Figure 43-8 Editing the Message Flow
Figure 43-9 Adding an Action
You are returned to the Pipeline Definition Editor.
In this section, you configure the proxy service to send messages to the pipeline you created.
To connect the proxy service and pipeline:
The Proxy Service Definition Editor appears.
You can test the socket transport provider using the client and server tools provided with the sample files, and you can test project components using the Test Console in the Oracle Service Bus Console.
The sample project includes a simple socket server and a client to test the socket transport provider. First you need to start the sample server and client, and then you can work with the Test Console to test the transport provider.
Run the following command from the
sample-transport directory to start the test server, which is a server socket that listens on a specified port and receives and sends the messages.
java -classpath .\test\build\test-client.jar -Dfile-encoding=utf-8 -Drequest-encoding=utf-8 com.bea.alsb.transports.sample.test.TestServer 7031 <message-file-location>
7031 is the port number in the business service endpoint URI, where ServerSocket is listening. The file and request encoding indicate the encoding of the request and response.
message-file-location is the path and name of the message file to send as a response to the business service.
If the server is started successfully, a message appears indicating that it is started and listening on a socket. If you specify a file to process, the text of the file appears in the command window.
Run the following command to start the initiating socket service, which is a client to the configured socket proxy service. It sends a message and receives the response from Service Bus.
java -classpath .\test\build\test-client.jar -Dfile-encoding=utf-8 -Dresponse-encoding=utf-8 com.bea.alsb.transports.sample.test.TestClient <host-name> <port> <thread-ct> <message-file-location>
host-name is the host name on which the Service Bus server is located.
port is the port number at which the proxy service is listening (7032, in our example).
thread-ct is the number of clients that can send a message to Service Bus.
message-file-location (optional) is the location of the message file to send as a response to the business service.
file-encoding is an optional argument specifying the encoding of the file. The default is
response-encoding is the encoding of the response received from the socket proxy service. The default is
In this section you test the transport provider using the Oracle Service Bus Console.
To test using the Test Console:
The Test Console appears in a new browser window.
Figure 43-10 Testing the Sample Transport Provider in the Test Console
Figure 43-11 Successful Sample Transport Provider Test