Nav
You are viewing an older version of this section. Click here to navigate to the latest version.

Examining the Generated Connector Project

This document describes the folder structure and files that Maven generated for you when created your connector project.  

Assumptions

This document assumes that you created a new connector project and that in Eclipse or Mule Studio, your connector project directory looks similar to the screenshot below.

image

Source Folder

image The Source Folder gathers all of the inputs necessary to eventually build the target folder. The first Maven command you ran used the Mule connector archetype to generate a skeleton in the source folder which includes the four paths described in the following table.

Folder Description

src/main/java

Contains the source Java files for your connector, including the skeleton Java file for your connector. As you add additional classes, the project stores them in this folder.

src/main/resources

Contains non-code resources accessed by your connector. This folder is empty when you initially create the project.

src/test/java

Contains the Java source for the test files for your connector, including the skeleton JUnit test case.

src/test/resources

Contains non-code resources accessed by your tests. This folder contains a skeleton Mule configuration file for running tests.

Connector Class

image Open the src/main/java/org/hello/HelloConnector.java file. This class defines the main class for the connector and includes the important @Connector annotation. 

DevKit already created a class and a couple of methods and marked them with annotations.  The annotations tell Mule how to call and treat your classes, methods, or parameters in specific, predefined ways. They are the only point of contact with Mule that you need to manage.

@Connector

The top level annotation for the connector, applied to the connector class itself, is @Connector. The annotation informs DevKit that a Java class is intended to function as a connector.


         
      
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
/**
* Cloud Connector
*
* @author MuleSoft, Inc.
*/
@Connector(name="myConnector", schemaVersion="1.0-SNAPSHOT")
public class myConnector
{
 
    /**
    * Configurable
    */
    @Configurable
    private String myProperty;
 
    [...]
 
}
 
[...]

The  @Connector annotation includes several parameters, two of which were automatically generated by the archetype: name and schemaVersion. You can define other parameters, as described in the table below.

Annotation Type Element Description Required? Default Value

name

The name of the connector. This value must be a simple string, with no spaces.

 

schemaVersion

The version of the schema as generated by the DevKit.

1.0-SNAPSHOT

friendlyName

This is the human-readable name of the connector. It can contain spaces. Mule uses it only to label the connector in the palette Studio.

 

description

A longer text string describing the connector and its operation. Mule Studio displays the description as a tool tip.

 

namespace

The namespace of the connector.

http://www.mulesoft.org/schema/mule/name

schemaLocation

The location of the schema file that writes to the spring.schemas file.

minMuleVersion

The minimum Mule version with which the connector can be used. Mule checks the version at runtime and throws an error if versions are incompatible.

current version of DevKit

The following restrictions apply to the @Connector annotation.  

  • @Connector cannot be applied to interfaces

  • @Connector cannot be applied to final classes

  • @Connector cannot be applied to parametrized classes

  • @Connector cannot be applied to non-public classes

  • a class with @Connector must contain exactly one method annotated with @Connect

  • a class with @Connector must contain exactly one method annotated with @Disconnect

Connector Tests

image Open the src/test/java/org/hello/HelloConnectorTest.java file. DevKit creates a class, a couple of methods, and a configurable property, and marks them all with annotations. Within the methods of this class, you can write your own tests tailored to your testing needs. These tests are evaluated every time you compile your code.  You can also run these tests without building your connector by running the following Maven command from the console.  


         
      
1
mvn test

For more details on developing tests for your connector, see Developing DevKit Connector Tests.

POM file

image Based on the archetype used to create the project, Maven generates the project object model (POM) file.  Maven uses the pom.xml file to keep track of all dependencies needed to build a project, including the dependencies' version number and location. You may have to add items to the POM file during the connector development process in order to pull in additional libraries and add steps to the build process .

For more details on the role of the POM file, see http://maven.apache.org/pom.html[the POM Reference at maven.apache.org].

Icons Folder

image The icons folder contains the visuals that Mule Studio uses to represent your connector both on the palette and on the canvas. You can easily swap these files with others of your choice. You can also modify the folder from which Mule fetches them.

License and README Files

image Should you decide to share your connector with the Mule Community, your project includes a basic license agreement. You are free to change this licence agreement. Use the README file to provide users with initial information about the connector. These files are written in https://help.github.com/articles/github-flavored-markdown[Github-Flavored Markdown] format (.md`)`. 

Target Folder

image When the build process is successful and the tests defined in the test folder all pass, the Maven build process creates several artifacts in the target folder. If you ran a build process and don’t see this folder in the Package Explorer, right-click the project name, then select Refresh to view the following new elements:

  • hello-connector-1.0-SNAPSHOT.jar, the connector JAR

  • hello-connector-1.0-SNAPSHOT.zip, the Mule plugin which you can drop into the plugins directory in Mule standalone

  • apidocs, auto-generated installation instructions, Javadoc, and Mule API docs for your connector

  • update-site, the file that you import into Mule Studio to install and update the connector

Reference Documentation

The build also auto-generates Javadoc for your connector. The skeleton files that Maven generates already includes placeholder comments  (enclosed between /* and /) which you can update further. As you add functionality to your connector, be sure to rigorously add JavaDoc annotations to your code as Mule automatically incorporates the annotations into the auto-generated documentation during the build process.

To view it the documentation, open target/apidocs/index.html in your web browser.


         
      
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
/**
     * Connect
     *
     * @param username A username
     * @param password A password
     * @throws ConnectionException
     */
    @Connect
    public void connect(@ConnectionKey String username, String password)
        throws ConnectionException {
        /*
         * CODE FOR ESTABLISHING A CONNECTION GOES IN HERE
         */
    }
 
 
    /**
     * Custom processor
     *
     * {@sample.xml ../../../doc/hello-connector.xml.sample hello:my-processor}
     *
     * @param content Content to be processed
     * @return Some string
     */
    @Processor
    public String myProcessor(String content)
    {
        /*
         * MESSAGE PROCESSOR CODE GOES HERE
         */
 
        return content;
    }

Documentation Best Practice

DevKit enforces commenting your code. For every method you write, add a corresponding comment section so that your connector’s functionality is documented as soon as you built it. In these comment sections, list every parameter and every output of the method with the annotations @param and @return.

Notice, in the example below, that DevKit pulled the @param and @return content from the example code above into the Javadoc, automatically organizing it, formatting it, and including additional standard content. 

image

   

See Also