Setting up your environment

The first thing to do when starting working on a new component is to download and install Apache Maven 2, and a good IDE (e.g. NetBeans, Eclipse or IntelliJ).
In this document, it is assumed that you use Eclipse or NetBeans. You should be able to find out equivalent actions for other IDEs.

The first thing to do is to download Apache Maven and an IDE (e.g. Eclipse, NetBeans or IntelliJ).
In the rest of this document, it is assumed you use Eclipse as your IDE. When this document references Eclipse actions, you should be able to find equivalents with other IDEs.

Installing and configuring Apache Maven 2

Apache Maven 2 is a popular "software project management and comprehension tool". In many ways, it can be seen as the successor of - the still popular - Ant tool. Nowadays, Maven 2 is used by an increasing number of software projects, including Petals ESB. An important part of the development of Petals component is based on the use of this tool.

1. Download Apache Maven 2 from : http://maven.apache.org/.
2. Install Maven 2 using this guide : http://maven.apache.org/download.html.
3. Check if the M2_HOME environment variable is pointing to your Maven 2 installation.
4. Check if M2_HOME/bin has been added to your system path.

To use the OW2 Maven 2 repositories, you must perform some additional configuration :

1. Go into the Maven 2 local repository (typically C:/Documents and settings/username/.m2 on Windows or /home/username/.m2 on most Unix(es)).
2. Open (or create if not present) the settings.xml file and make sure to include the repositories listed in the sample below.

   <settings>
       <profiles>
           <profile>
               <id>default-profile</id>
               <activation>
                   <activeByDefault>TRUE</activeByDefault>
               </activation>
               <repositories>
                   <repository>
                       <id>ow2</id>
                       <name>OW2 Repo</name>
                       <url>http://maven.objectweb.org/maven2
                       </url>
                       <snapshots>
                           <enabled>false</enabled>
                       </snapshots>
                       <releases>
                           <enabled>true</enabled>
                       </releases>
                   </repository>
                   <repository>
                       <id>ow2-snapshot</id>
                       <name>OW2 SNAPSHOT Repo</name>
                       <url>http://maven.objectweb.org/maven2-snapshot
                       </url>
                       <snapshots>
                           <enabled>true</enabled>
                       </snapshots>
                       <releases>
                           <enabled>false</enabled>
                       </releases>
                   </repository>
               </repositories>
               <pluginRepositories>
                   <pluginRepository>
                       <id>ow2-plugin</id>
                       <name>OW2 plugin Repo</name>
                       <url>http://maven.objectweb.org/maven2
                       </url>
                       <snapshots>
                           <enabled>false</enabled>
                       </snapshots>
                       <releases>
                           <enabled>true</enabled>
                       </releases>
                   </pluginRepository>
               </pluginRepositories>
           </profile>
       </profiles>
   </settings>
   

   Download link : settings.xml.

3. That's it for Apache Maven 2

Info For more information on Apache Maven 2, you should read the following books : Maven by Example Maven: The Complete Reference Note : Theses two books where originally one : Maven the definitive guide.

Configuring your IDE

Since modern days java developers doesn't use text editors such vi or emacs, and since we are modern days java developers, we use Integrated Development Environment such Eclipse or NetBeans. In order to use them correctly, we must configure them.

Configuring Eclipse

In order to make Eclipse use Maven artifacts, you have to set a class path variable.
To do so, launch your Eclipse, select Window > Preferences and go into Java > Build Path > Classpath Variable.
The variable to create is called M2_REPO.

If it does not exist, click New..., call it M2_REPO and associate it the Maven repository folder.
This folder is located at ~/.m2/repository. Click OK to register this variable and then OK to save and close the preferences.

Configuring NetBeans

This section has to be completed.

Creating a component

First, decide whether you want to create a Binding Component (BC) or a Service Engine (SE) :

• Binding components host services that will act as entry points and exit points for communication protocols. They are intermediaries between what is inside the bus and what is outside.
• Service engines host configured services, such as a XSLT transformation, or a BPEL application.

In both cases, these services instantiate the features offered by the component, by providing a configuration and artifacts.

Once this is done, you should pick up a name for your component, following the Petals ESB component naming conventions :

• petals-bc-componentName for binding components.
• petals-se-componentName for service engines.

Go into a directory where you can store your project.
Your IDE workspace may be a good place for that. Open a terminal on this location. The command below creates a service engine, based on the CDK 5, and called petals-se-sample.

# Maven command to create a Petals service engine
mvn archetype:generate
        -DarchetypeGroupId=org.ow2.petals
        -DarchetypeArtifactId=maven-archetype-petals-jbi-service-engine
        -DarchetypeVersion=1.3
        -DgroupId=org.ow2.petals.se.sample
        -DartifactId=petals-se-sample
        -Dversion=1.0-SNAPSHOT

Be careful, the previous command has been formatted for readability purpose. In fact, it should be on a single line.

The meaning of these options is listed below.

• archetypeArtifactId is the type of artifact to create.
  • maven-archetype-petals-jbi-service-engine for a service engine.
  • maven-archetype-petals-jbi-binding-component for a binding component.
• archetypeVersion is the archetype version.
  • 1.3 is the one to use for the (released) CDK 5.
  • 1.4-SNAPSHOT is the one (currently) used with the CDK in development.
• groupId is the group ID, which is also the name of the root package in the created project.
• artifactId is the artifact ID, usually the full component name.
• version is the component version, followed by the -SNAPSHOT suffix.

During the creation, you are asked to confirm the project properties. Type in 'Y' to confirm.
The executed command results in the creation of a Java Maven project.
To transform it into a project we can use in our IDE. For Eclipse, we can use the following commands:

# Go into the created project
cd petals-se-sample

# Convert it into an Eclipse project
mvn eclipse:eclipse

You should now wait for Maven to download all the required dependencies and create the Eclipse files. Once this is done, launch your Eclipse IDE and import the project in your workspace: select File > Import... and then General > Existing projects into Workspace. In the open dialog, click Browse..., select your workspace as the root folder and click OK. Now, in the listed projects, check your component project and click OK.

Your component project is now created and ready to be completed.
The main files to notice are:

• The pom.xml, which holds the Maven dependencies.
• The src/main/jbi/jbi.xml, which is the component JBI descriptor.
• The src/main/jbi/.xsd* files, which define the structure of component configurations.

For a service engine:

• JBIListener.java, which handles JBI messages coming from the bus.
• The ServiceEngine class, which defines the component and manages its life cycle.

For a binding component:

• JBIListener.java, which handles JBI messages coming from the bus.
• ExternalListener.java, which handles messages coming from outside the bus.
• The BindingComponent class, which defines the component and manages its life cycle.

Compiling an deploying a component

Once you have developed your component, the normal next step is to compile it and try to deploy it on Petals.
To compile your component, open a terminal inside the project directory, and execute one of the following commands:

# Just compile
mvn compile

# Compile and build it for deployment
mvn install

With the second command, on a successful build, the result component archive is available in the target folder of your component project. This archive (*.zip) can be deployed in Petals in two ways:

1. The first one is to use the Petals administration console.
2. The second and most simple one is to copy this archive in the install directory of your Petals installation. This solution perfectly fits development mode.

In any case, you must start Petals before deploying your component.
A successful deployment in Petals is a first validation of your component (but clearly not enough).

Testing and debugging a component

Debugging a component

Although debugging needs you to have some tests to run, it seems a better option to introduce how to debug a component, prior to explain how to test it.

Debugging a component needs three simple steps:

1. Stop your Petals. Execute its debug script (debug.bat / debug.sh).
2. In your IDE, use the remote debug feature to launch Petals (see below for details).
3. Add breakpoints in your component code.

Using Eclipse

In Eclipse, the remote debug feature can be used by selecting Run > Debug Configurations...
On the left, right-click on Remote Java Application and click New.

In the Name field, type in Petals Remote.
In the Connect tab, type in the Petals host and port (usually, localhost and 8000).
In the Source tab, make sure your component project is in the displayed sources.
If not, click Add... In the open dialog, double click Java Project, select your project and click OK.

Click Apply to save the debug configuration.
Click Debug to launch Petals in debug mode. The terminal in which you launched the debug script should now display that Petals is starting.

You can now build and deploy your component in Petals.
Do not forget to add breakpoints inside your component code. Defining them before or after the build / deployment has no incidence on the debugging.

To make debugging effective, you must manage to make your code to be called.
This is achieved by creating some configurations / tests for your component.

Using Netbeans

This secction has to be completed.

Testing a component

Testing a component can be seen from two points of view.
The first one is the industrial test campaign, which relies on continuous integration (e.g. Hudson), and which is based on Maven and JUnit. Clearly, it is not in the scope of this document to discuss this kind of tests (although EBM WebSourcing has set up this kind of tests on its side).

The second way to consider testing is related to debugging, and consists in making small unit of tests to check the behavior of your component. They can be seen as check tests that complete code verification. This kind of test requires you to create service assemblies for your component, and play with the different parameters a service-unit can hold. Defining such service assemblies is a primary step toward continuous integration, though it is not enough (you will probably not cover all the possible cases).

The methodology for running these tests is the following:

1. Start Petals in debug mode (and add breakpoints if necessary in your component code).
2. Build and deploy your component in Petals.
3. Deploy the service assembly to test with your component (and check that it goes fine).
4. Deploy the sample client component (available on the Petals website and in the Petals Quick Start versions).
5. Once deployed, the sample client launches a Swing dialog which allows you to call any service inside Petals.

In the sample client dialog, go into the Query tab and click Find all the endpoints.

A list of Petals services appears in the lower part of the dialog. If the deployment of your service assembly went fine, you should find it in the displayed list. Double click it and go back in the Send tab. Play with the Message Exchange patterns (MEP) and the In request (which must be an XML document). Eventually, use the SendSync or Send--Accept buttons to send your message to your service.

The sent message should be received and processed by your component.
If you launched Petals in debug mode and added breakpoints, the execution should be suspended when a breakpoint is reached at runtime.