Tutorial - Barn Connector

DevKit is compatible only with Studio 6 and Mule 3. To build Mule 4 connectors, see the Mule SDK documentation.

This document describes the steps needed to build, install, and test a connector in Anypoint Studio.

The following tutorial describes how to create a simple connector that displays "Mule has been placed in the barn" in a browser. You can use the user interface for the connector in Anypoint Studio to change which animal is put in the barn.

Before Creating a Connector

Install:
1. Java 7
2. Maven
3. Studio
Start Anypoint Studio.
Configure Maven:
1. Click Anypoint Studio > Preferences > Anypoint Studio > Maven Settings.
2. Click Browse to locate the folder where you installed Maven.
3. Click Test Maven Configuration and when you see the green checkmark, click OK.
In Anypoint Studio, install the DevKit Plugin:
1. Click Install New Software.
2. Click Work with > Anypoint Addons Update Site > Anypoint Devkit Plugin.
3. Click Next, Finish, and restart Studio.

Creating a Connector Project

Create your initial Barn connector. Use File > New > Anypoint Connector Project. Name the connector Barn. You can leave all other fields the same. Click Finish. You can ignore any warning messages in the Studio Console.
Review the scaffolded connector:

Starting Connector Code

/**
 * (c) 2003-2015 MuleSoft, Inc. The software in this package is published under the terms of the CPAL v1.0 license,
 * a copy of which has been included with this distribution in the LICENSE.md file.
 */
package org.mule.modules.barn;
import org.mule.api.annotations.ConnectionStrategy;
import org.mule.api.annotations.Connector;
import org.mule.api.annotations.Configurable;
import org.mule.api.annotations.Processor;
import org.mule.api.annotations.param.Default;
import org.mule.modules.barn.strategy.ConnectorConnectionStrategy;
/**
 * Anypoint Connector
 *
 * @author MuleSoft, Inc.
 */
@Connector(name="barn", schemaVersion="1.0", friendlyName="Barn")
public class BarnConnector
{
    /**
     * Configurable
     */
    @Configurable
    @Default("value")
    private String myProperty;
    @ConnectionStrategy
    ConnectorConnectionStrategy connectionStrategy;
    /**
     * Custom processor
     *
     * {@sample.xml ../../../doc/barn-connector.xml.sample barn:my-processor}
     *
     * @param content Content to be processed
     * @return Some string
     */
    @Processor
    public String myProcessor(String content) {
        /*
         * MESSAGE PROCESSOR CODE GOES HERE
         */
        return content;
    }
    /**
     * Set property
     *
     * @param myProperty My property
     */
    public void setMyProperty(String myProperty) {
        this.myProperty = myProperty;
    }
    /**
     * Get property
     */
    public String getMyProperty() {
        return this.myProperty;
    }
    public ConnectorConnectionStrategy getConnectionStrategy() {
        return connectionStrategy;
    }
    public void setConnectionStrategy(ConnectorConnectionStrategy connectionStrategy) {
        this.connectionStrategy = connectionStrategy;
    }
}

Coding a Connector

To code the connector:

In Studio, open the main Java file, src/main/java/org/mule/modules/barn/BarnConnector.java
Paste the following code in the connector class, before the final closing curly brackets, and after the existing @Processor block:
```
/**
 * Custom processor that places an animal in the barn.
 *
 * {@sample.xml ../../../doc/barn-connector.xml.sample barn:putInBarn}
 *
 * @param animal Name of the animal to be place in the barn
 * @return returns processed message
 */
@Processor(friendlyName="Put an animal in the barn")
public String putInBarn(@Placement(group="Parameters")
  @FriendlyName("The animal's name") String animal) {
        return animal + " has been placed in the barn";
}
```
The path name in the @Sample statement indicates the path to the Javadoc *.xml.sample file in Studio–it’s not a filesystem path.

The line starting with @Processor identifies the processor function, which specifies the user interface for the connector.

The line starting with @FriendlyName indicates some of the UI elements that display in the browser when the connector runs in Anypoint Studio. This code changes the operation name to "Put an animal in the barn", and changes the Animal prompt to "The animal’s name".
After inserting, @Placement and @FriendlyName are underscored as an error condition. Mouse over each annotation and select the import command from the popup menu to add import commands to your connector:

Add loading statements for future Javadoc documentation in your connector by providing map-payload statements:

Open the Javadoc doc/barn-connector.xml.sample file:

Include one BEGIN/END block for each @Processor statement block in your connector.

<!-- BEGIN_INCLUDE(barn:my-processor) -->
  <barn:my-processor config-ref="" content="#[map-payload:content]" />
<!-- END_INCLUDE(barn:my-processor) -->

For the second @Processor statement block, add these lines:

<!-- BEGIN_INCLUDE(barn:my-processor) -->
  <barn:put-in-barn config-ref="" animal="#[map-payload:content]" />
<!-- END_INCLUDE(barn:my-processor) -->

Completed barn-connector.xml.sample file

<!-- BEGIN_INCLUDE(barn:my-processor) -->
  <barn:my-processor config-ref="" content="#[map-payload:content]" />
<!-- END_INCLUDE(barn:my-processor) -->
<!-- BEGIN_INCLUDE(barn:my-processor) -->
  <barn:put-in-barn config-ref="" animal="#[map-payload:content]" />
<!-- END_INCLUDE(barn:my-processor) -->

Save this file.

Disable spell checking by mousing over text with a red underline and clicking Disable spell checking:

The completed connector code appears as follows:

Completed Connector’s Code

/**
 * (c) 2003-2014 MuleSoft, Inc. The software in this package is published under the terms of the CPAL v1.0 license,
 * a copy of which has been included with this distribution in the LICENSE.md file.
 */
package org.mule.modules.barn;
import org.mule.api.annotations.ConnectionStrategy;
import org.mule.api.annotations.Connector;
import org.mule.api.annotations.Configurable;
import org.mule.api.annotations.Processor;
import org.mule.api.annotations.display.FriendlyName;
import org.mule.api.annotations.display.Placement;
import org.mule.api.annotations.param.Default;
import org.mule.modules.barn.strategy.ConnectorConnectionStrategy;
/**
 * Anypoint Connector
 *
 * @author MuleSoft, Inc.
 */
@Connector(name="barn", schemaVersion="1.0", friendlyName="Barn")
public class BarnConnector
{
    /**
     * Configurable
     */
    @Configurable
    @Default("value")
    private String myProperty;
    @ConnectionStrategy
    ConnectorConnectionStrategy connectionStrategy;
    /**
     * Custom processor
     *
     * {@sample.xml ../../../doc/barn-connector.xml.sample barn:my-processor}
     *
     * @param content Content to be processed
     * @return Some string
     */
    @Processor
    public String myProcessor(String content) {
        /*
         * MESSAGE PROCESSOR CODE GOES HERE
         */
        return content;
    }
    /**
     * Custom processor that places an animal in the barn.
     *
     * {@sample.xml ../../../doc/barn-connector.xml.sample barn:putInBarn}
     *
     * @param animal Name of the animal to be place in the barn
     * @return returns processed message
     */
    @Processor(friendlyName="Put an animal in the barn")
    public String putInBarn(@Placement(group="Parameters")
      @FriendlyName("The animal's name") String animal) {
            return animal + " has been placed in the barn";
    }
    /**
     * Set property
     *
     * @param myProperty My property
     */
    public void setMyProperty(String myProperty) {
        this.myProperty = myProperty;
    }
    /**
     * Get property
     */
    public String getMyProperty() {
        return this.myProperty;
    }
    public ConnectorConnectionStrategy getConnectionStrategy() {
        return connectionStrategy;
    }
    public void setConnectionStrategy(ConnectorConnectionStrategy connectionStrategy) {
        this.connectionStrategy = connectionStrategy;
    }
}

Identifying Your Connector in Studio

When you create an Anypoint Connector Project, Studio creates the @Connector annotation containing a name, schema version, and friendly name.

Connectors use the @Connector annotation to describe the contents of a connector. The friendlyName parameter defines the connector’s label in the Studio palette.

@Connector(name="barn", schemaVersion="1.0", friendlyName="Barn")

After you install your connector in Studio, when users create a Mule Project, the friendlyName identifies your connector:

Installing Your Connector

Install your project: Right-click the connector project’s name in Package Explorer, and click Anypoint Connector > Install or Update.
Follow the prompts to accept the details, the terms of the license agreement, and installing software with unsigned content. Restart Studio for the changes to take effect. The connector then becomes available to include in a Mule Project.

Creating a Mule Project With Your Connector

After Studio restarts, create a Mule project using File > New > Mule Project.
Search for "http" and drag the HTTP connector to the canvas. The default settings are correct.
Search for "barn" and drag the Barn connector to the canvas. The canvas appears as:

To configure the Barn connector:
1. Click the green plus:
2. Ensure that the screen appears as follows and click OK:
  
  The two values for My Property and My Strategy Property are supplied by the default connector. You can ignore these.
3. In the first screen, click Operation and click Put in barn. In the Animal field specify a name such as the Mule animal:
Deploy your Mule project by clicking Run > Run As > Mule Application.
Open a browser and set the address to http://0.0.0.0:8081 - The browser displays:
You can change the Animal value, save your project, and refresh your browser to experiment with putting other animals in the barn.