Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (3.2)
  3. Extending Mule ESB 3
  4. Creating Transports

  5. Transport Archetype

Transport Archetype

Mule provides Maven archetypes that you can use as code templates for your Mule projects. These templates include a set of implementation notes and "todo" pointers that help you get started quickly. The Mule transport archetype will help you generate a tailored boilerplate transport project in seconds.

If you want to update an existing transport instead of creating a new one, such as adding new schema namespaces and registry bootstrapping to the transport, use the Creating Module Archetypes instead.

Follow the instructions below to create template files for a new transport, including all the necessary Java boilerplate and detailed implementation instructions in comments.

Configuring Maven

Add the following to the file settings.xml (usually in your Maven conf or $HOME/.m2 directory) so that Maven will allow you to execute Mule plug-ins.

settings.xml

<settings>
    <pluginGroups>
        <pluginGroup>org.mule.tools</pluginGroup>
    </pluginGroups>
    ...
</settings>

Using the Archetype

First, open a command shell and change to the directory where you want to create your project.

 > cd yourDir

Next, you execute the archetype and generate the code. If this is your first time running this command, Maven will download the archetype for you.

 > mvn mule-transport-archetype:create -DtransportId=xxx -DmuleVersion=3.1.1

Running the archetype
Maven uses by default the latest available version of the archetype. This can cause problems if you want to create a transport for an earlier version of Mule. In this case, run the mule-transport-archetype specifying the full version of the plugin like this:

 mvn org.mule.tools:mule-transport-archetype:3.1.1:create ...

At minimum, you pass in two system parameters:

  • transportId: The short name for the project (such as 'tcp'). This must be a single word in lower case with no spaces, periods, hyphens, etc. For transports this is usually the short protocol name of the underlying transport being connected.

  • muleVersion: The version of the Mule project archetype you want to use. This will also be the default Mule version used for the generated artifact.

The plug-in will ask various questions (described below) and then generate the files. You can also use this plug-in without user prompts by entering all the arguments at the command line. For a full list of arguments that can be passed in, see the Command Line Options.

After you have answered all the questions, the archetype creates a directory using the transport name you specified. The directory includes a POM file for building with Maven, a Mule configuration file (src\main\resources\mule-config.xml) that includes the namespaces for the transports and modules you specified and has placeholder elements for creating your first service, and a package.html file under src\main\java using the package path you specified. Lastly, it creates some template files under src\test to help you get started creating a unit test for the transport. A new MULE-README.txt file will be created in the root of your project explaining what files were created.

The Questions Explained

The plug-in prompts you to answer several questions about the transport you are writing. These may vary according to the options you select. An example of the output is shown below.

Provide a description of what the transport does:

You should provide an accurate description of the transport with any high-level details of what you can or cannot do with it. This text will be used where a description of the transport is required.

Which version of Mule is this transport targeted at?

The version of Mule you want to use for your transport. By default this will default to the version passed in on the command line.

Will this transport have a custom schema for configuring the transport in Xml?

All new transports should define an XML schema that defines how the transport is configured. If you do not use this option, users will have to use generic configuration to use your transport.

Can the transport receive inbound requests?

Can this transport receive inbound events? For example, the File transport allows you to listen for files written to a directory. JMS allows you to listen for events being written to a topic or queue.

Does the Message Receiver need to poll the underlying resource?

To receive a message, some transports must do polling. For example, the File transport must poll a directory to know something has been written there, whereas JMS provides a callback (MessageListener) to deliver the message. This question is asked only if the transport can receive inbound requests.

If this transport will have a default inbound transformer, enter the name of the transformer?

If the protocol of the application being connected to has its own message type, you can define a default inbound transformer that will be invoked by default when defining endpoints that use this transport. You enter the name of the transformer class (without package name) to generate, such as JmsMessageToObject.

Can the transport dispatch outbound requests?

Asks whether messages can be written to this transport. With the File transport, you can write file data to a directory, and with JMS you can write to a queue or topic.

If this transport will have a default outbound transformer, enter the name of the transformer?

If the protocol of the application being connected to has its own message type, you can define a default outbound transformer that will be invoked by default when defining outbound endpoints that use this transport. You enter the name of the transformer class (without package name) to generate, such as ObjectToJmsMessage.

Does the transport need a custom MuleMessageFactory?

This is usually only required if the underlying transport has an API that has a
message object i.e. JMSMessage or HttpServletRequest.

Can the transport request individual messages from the underlying resource?

If the transport can request messages from a message channel or resource rather than subscribing to inbound events or polling a resource, answer yes to this question. This will generate a MessageRequester class.

Does this transport support transactions?

If the underlying resource for this transport is transactional, you can have Mule generate a transaction wrapper that will allow users to enable transactions on endpoints defined using this transport.

Does this transport use a non-JTA transaction manager?

Not all technologies (such as JavaSpaces) support the standard JTA transaction manager. Mule can still work with different non-JTA transaction managers, and this archetype can generate the necessary stubs for you.

What type of endpoints does this transport use?

Mule supports a number of well-defined endpoints

The Custom option allows you to deviate from the existing endpoint styles and parse your own.

Which Mule transports do you want to include in this project?

If you are extending one or more existing transports, specify them here in a comma-separated list.

Which Mule modules do you want to include in this project?

By default, the Mule client module is included to enable easier testing. If you want to include other modules, specify them here in a comma-separated list.

Example Console Output

In the example that follows, MuleForge hosting no longer exists. Enter n at the MuleForge prompt. 
********************************************************************************

               Provide a description of what the transport does:
                                                                     [default: ]
********************************************************************************
[INFO] muleVersion:
********************************************************************************

              Which version of Mule is this transport targeted at?
                                                                [default: 3.1.1]
********************************************************************************
[INFO] forgeProject:
********************************************************************************

              Will this project be hosted on MuleForge? [y] or [n]
                                                                    [default: y]
********************************************************************************
[INFO] hasCustomSchema:
********************************************************************************

Will this transport have a custom schema for configuring the transport in Xml?
[y] or [n]
                                                                    [default: y]
********************************************************************************
[INFO] hasReceiver:
********************************************************************************

             Can the transport receive inbound requests? [y] or [n]
                                                                    [default: y]
********************************************************************************
[INFO] isPollingReceiver:
********************************************************************************

   Does the Message Receiver need to poll the underlying resource? [y] or [n]
                                                                    [default: n]
********************************************************************************
[INFO] inboundTransformer:
********************************************************************************

If this transport will have a default inbound transformer, enter the name of the
transformer? (i.e. JmsMessageToObject)
                                                                    [default: n]
********************************************************************************
[INFO] hasDispatcher:
********************************************************************************

            Can the transport dispatch outbound requests? [y] or [n]
                                                                    [default: y]
********************************************************************************
[INFO] outboundTransformer:
********************************************************************************

If this transport will have a default outbound transformer, enter the name of the
transformer? (i.e. ObjectToJmsMessage)
                                                                    [default: n]
********************************************************************************
[INFO] hasCustomMessageFactory:
********************************************************************************

Does the transport need a custom MuleMessageFactory? [y] or [n]
(This is usually only required if the underlying transport has an API that has a message object
i.e. JMSMessage or HttpServletRequest)
                                                                    [default: n]
********************************************************************************
[INFO] hasRequester:
********************************************************************************

    Can the transport request incoming messages programmatically? [y] or [n]
                                                                    [default: y]
********************************************************************************
[INFO] hasTransactions:
********************************************************************************

              Does this transport support transactions? [y] or [n]
                                                                    [default: n]
********************************************************************************
[INFO] hasCustomTransactions:

********************************************************************************

Does this transport use a non-JTA Transaction manager? [y] or [n]
(i.e. needs to wrap proprietary transaction management)
                                                                    [default: n]
********************************************************************************
[INFO] endpointBuilder:
********************************************************************************

What type of endpoints does this transport use?
            - [r]esource endpoints (i.e. jms://my.queue)
            - [u]rl endpoints (i.e. http://localhost:1234/context/foo?param=1)
            - [s]ocket endpoints (i.e. tcp://localhost:1234)
            - [c]ustom - parse your own
                                                                    [default: r]
********************************************************************************
[INFO] transports:
********************************************************************************


Which Mule transports do you want to include in this project? If you intend extending a
transport you should add it here:

(options: axis,cxf,ejb,file,ftp,http,https,imap,imaps,jbpm,jdbc,
          jetty,jms,multicast,pop3,pop3s,quartz,rmi,servlet,smtp,
          smtps,servlet,ssl,tls,stdio,tcp,udp,vm,xmpp):
                                                                   [default: vm]

********************************************************************************
[INFO] modules:
********************************************************************************


Which Mule modules do you want to include in this project? The client is added f
or testing:

(options: bulders,client,jaas,jbossts,management,ognl,pgp,scripting,
          spring-extras,sxc,xml):
                                                               [default: client]

********************************************************************************

Command Line Options

By default, this plug-in runs in interactive mode, but it’s possible to run it in silent mode by using the following option:

-DinteractiveMode=false

The following options can be passed in:

Name Example Default Value

transportId

-DtransportId=tcp

none

description

-Ddescription="some text"

none

muleVersion

-DmuleVersion=3.1.1

none

hasCustomSchema

-DhasCustomSchema=true

true

forgeProject

-DforgeProject=true

true

hasDispatcher

-DhasDispatcher=true

true

hasRequester

-DhasRequester=true

true

hasCustomMessageFactory

-DhasCustomMessageFactory=true

false

hasTransactions

-DhasTransactions=false

false

version

-Dversion=1.0-SNAPSHOT

<muleVersion>

inboundTransformer

-DinboundTransformer=false

false

groupId

-DgroupId=org.mule.transport.tcp

org.mule.transport.<transportId>

hasReceiver

-DhasReceiver=true

true

isPollingReceiver

-DisPollingReceiver=false

false

outboundTransformer

-DoutboundTransformer=false

false

endpointBuilder

-DendpointBuilder=s

r

hasCustomTransactions

-DhasCustomTransactions=false

false

transports

-Dtransports=vm,jms

vm

modules

-Dmodules=client,xml

client