Skip to Main Content U.S. Department of Energy

Transports

Since MIF is a specialization and simplification of Mule, the transports used in MIF are a subset of those in Mule. Thus, the documentation here is highly condensed from the Mule transport documentation (registration required). It may be useful to refer to the mule docs to learn the full set of features provided by Mule. The documentation focuses on the properties required by MIF applicatins.

Overview

In MIF, communication between modules is enabled by transports, which are responsible for abstracting network communications and passing messages throughout a pipeline. Each communication protocol that is supported by MIF (e.g., JMS or HTTP) is implemented by a separate transport. Most of the complexity of a transport is hidden from the user by the use of swappable endpoints, which allow a module to be oblivious as to the communication protocols it is using. However, it is sometimes necessary or desirable to configure the attributes of a transport. In this case, there are API methods which enable the programmer to explicitly create and configure a connector.

Endpoints

Each transport has its own type of endpoint, which is used to connect modules to each other so that they can exchange messages. Each module has a set of inbound and outbound endpoints which can be set using the MIF API. To connect one module to another, the outbound endpoint of one module in the pipeline must match the inbound endpoint of another.

Endpoints are configured as strings representing a URI. It possible to set properties on an endpoint to configure special behavior or override the default properties of a connector. For example, it is possible to configure whether an endpoint is synchronous or asynchronous by setting the “synchronous” property.

So an endpoint URI has the format:

scheme://host:port/path/to/service?property1=value1&property2=value2

Where “scheme” is the particular type of transport being used (http, jms, vm, etc.); “host:port” is a hostname and port which may or may not be present due to the nature of a given transport; path is the path that distinguishes the endpoint from others. Properties are defined after a ”?” at the end of a path and are delineated by key value pairs.

Concrete example

Each transport's endpoints are either synchronous or asynchronous by default. This default can be overridden by setting the “synchronous” property on an endpoint. For example, HTTP endpoints are synchronous by default. So, the following is an http inbound endpoint that creates an asynchronous service, listening at the address localhost:9090/helloService

http://localhost:9090/helloService?synchronous=false

Connectors

Connectors are used to configure the attributes of a particular transport for the current pipeline or component. For example, the JMS connector allows the user to configure the location of the JMS server. Most of the time, the user does not need to explicity configure a transport since a default connector will automatically be created for each type of endpoint that occurs in the pipeline.

API users will want to create and configure connectors when:

  1. It is necessary to optimize the performance of a transport. This is common, for example, when using TCP endpoints.
  2. No default connector can be created. For example, the use of JMS requires an explicit connector because it is necessary to specify the location of the JMS server.

If there is only one connector for a given protocol in a MIF pipeline, all endpoints associated with that transport will use this connector. However, multiple connectors may exist for the same transport in a single pipeline. In this case, you need to specify the name of the connector as a property on the endpoint so that MIF knows which connector to use for that particular endpoint.

For example, the following code excerpt shows a JMS connector defined with the name “jms-localhost”. Then, a module is configured with an inbound endpoint which specifies that connector, using the “connector” endpoint property. This allows endpoints in a MIF pipeline to connect to multiple JMS servers:

MifConnector conn = pipeline.addMifJmsConnector("tcp://localhost:61616", JmsProvider.ACTIVEMQ);
conn.setName("jms-localhost");
MifModule fullNameModule = pipeline.addMifModule(NameArrayProcessor.class, "jms://topic:NameTopic?connector=jms-localhost", "stdio://stdout");

Properties can be set on a connector by calling the “setProperty” method on a MifConnector, e.g.:

MifConnector stdioConn = pipeine.addMifConnector(EndpointType.STDIO);
stdioConn.setProperty("messageDelayTime", 1000);

Supported Transports

Below is a description of the transports supported by MIF, along with a description of the useful properties which can be set on endpoints and/or connectors of this type. All endpoints support the “connector=connectorName” property as described above.

VM

The VM endpoint is used for commuication within the JVM. The key property that can be set on a VM endpoint is whether or not it is synchronous. If this property is set to synchronous=true, messages are passed synchronously from one module to another so that a slow receiver could slow down the sender. On the other hand, if this property is set to false, the sender sends as fast as it can without waiting for the receiver to complete each request.

Endpoint properties

property type default description
synchronous boolean true If true, the sender waits for the receiver to finish processing each message before sending the next one.

For example, here is an example of an asynchronous VM endpoint

"vm://myqueue?synchronous=false"

STDIO

The STDIO transport is used to read from standard in and write to standard out. It is useful for testing and debugging. There are several examples of stdio endpoints in the sample code documentation.

Endpoint and Connector Properties

property type default description
promptMessage string none For an inbound endpoint, text printed to the console when waiting for input
messageDelayTime long For an inbound endpoint, the delay in milliseconds before writing the promptMessage
outputMessage string none For an outbound endpoint, text printed to the console

JMS

The JMS (Java Messaging Service) transport enables using endpoints to connect to JMS destinations (topics and queues). It is possible to use any JMS server provider with MIF, but ActiveMQ is preferred and is the provider MIF is tested against.

Endpoint Configuration

By default, JMS endpoints specify queues. In ActiveMQ, queues must be created administratively. For example, the following URI specifies that an endpoint connect to the queue called “aQueue”

jms://aQueue

To specify a topic, prepend the destination name with the string “topic:”. for example, the following URI specifies an endpoint connected to the topic called “bTopic”

jms://topic:bTopic

Connector Configuration

To create an ActiveMQ JMS connector, it is necessary to specify the server URI as well as the JMS provider. Specifying the provider in this way, allows provider-specific properties to be automatically set on the connector:

pipeline.addMifJmsConnector("tcp://localhost:61616", JmsProvider.ACTIVEMQ);

HTTP

The HTTP transport enables inbound endpoints to act as web servers and inbound endpoints to act as http clients. It is typically not necessary to configure the properties of an HTTP connector.

Endpoints

HTTP endpoints are synchronous by default. So, the following is an http inbound endpoint that creates an asynchronous service, listening at the address localhost:9090/helloService

http://localhost:9090/helloService?synchronous=false

HTTPS

The HTTPS transport enables the creation of secure services over HTTP. To create such a service, it is necessary, for the connector to be configured to point to the keystore where the service's certificate is located.

Connector Properties

property description
keyStore The location of the java keystore file
keyStorePassword The password for the keystore
keyPassword Password for the private key

Connector example

The following MIF pipeline creates an HTTP connector which is configured to use a self-signed certificate, which can be created with the Java keytool.

MifPipeline pipeline = new MifPipeline();
 
MifConnector httpsConn = pipeline.addMifConnector(EndpointProtocol.HTTPS);
httpsConn.setProperty("keyStore", "/dev/ssl/keystore/pnl.jks");
httpsConn.setProperty("keyStorePassword", "storepass");
httpsConn.setProperty("keyPassword", "keypass");
 
pipeline.addBridgeModule("https://hostname:9090/secureService", "stdio://out");
pipeline.start();

CXF

CXF SOAP web services can be created as described in the web service module sample. CXF endpoints are configured using the “http” protocol on a MifWebServiceModule. For example, the following creates a CXF SOAP web service:

pipeline.addMifWsModule(SoapService.class, "http://host.example.org:9000/ws", null);

TCP

This transport enables the creation of servers listening on raw TCP sockets (for inbound endpoints) and clients sending to sockets (outbound endpoints). As an example, the following endpoint URI will create a server listening on the given host and socket if used as an inbound endpoint.

tcp://localhost:7676

The following is an example of a TCP connector definition. Since the TCP protocol does not have the concept of a message, it is necessary to define what mule calls a “protocol” algorithm, then set it as a property on the the connector. Thus, you should always explicitly create a TCP connector and choose an appropriate tcp protocol.

MifConnector conn = pipeline.addMifConnector(EndpointProtocol.TCP);
conn.setProperty("tcpProtocol", new EOFProtocol());

The EOFProtocol class instantiated above is a Mule class which defines the message boundary to be when EOF on the socket is received. That is, the message ends when the client disconnects from the server. All of the available protocols can be found in Mule's TCP transport documentation.

Connector Properties

Relevant properties on TCP connectors can be found in the table below:

property type default description
keepSendSocketOpen boolean false For outbound endpoints, if this is set to true, the socket will stay open after each send in order to improve performance
sendBufferSize int 0 size of the sending socket's buffer
receiveBufferSize int 0 size of the receiving socket's buffer
 
communication_transports.txt · Last modified: 2010/06/02 15:37 by adamw