{section}
{column}

h1. Introduction

The development of Petals ESB components is based on the use of three tools :
* Apache Maven 2 and its plugins for Petals ESB
* an Integrated Development Environment (IDE) for Java development
* the Petals ESB Component Development Toolkit (CDK), a Petals library which simplifies the work

This section explains how to use them to create, compile, deploy and test a Petals component.
{column}
{column:width=350px}
{panel:title=Table of contents}{toc}{panel}
{panel:title=Contributors}{contributors:order=name|mode=list}{panel}
{column}
{section}

h1. 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.


h2. Installing and configuring Apache Maven 2

[Apache Maven 2|http://maven.apache.org/] 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.

# Download Apache Maven 2 from : [http://maven.apache.org/|http://maven.apache.org/].
# Install Maven 2 using this guide : [http://maven.apache.org/download.html|http://maven.apache.org/download.html].
# Check if the {{M2_HOME}} environment variable is pointing to your Maven 2 installation.
# 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 :
# Go into the Maven 2 local repository (typically {{C:/Documents and settings/username/.m2}} on Windows or {{/home/username/.m2}} on most Unix(es)).
# Open (or create if not present) the {{settings.xml}} file and make sure to include the repositories listed in the sample below.
{code:lang=xml}
<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>
{code}
Download link : [^settings.xml].
# That's it for Apache Maven 2 :-)

\\
{info:title=Info}
For more information on Apache Maven 2, you should read the following books :
* [Maven by Example|http://www.sonatype.com/books/mvnex-book/reference/public-book.html]
* [Maven: The Complete Reference|http://www.sonatype.com/books/mvnref-book/reference/public-book.html]

*Note :* Theses two books where originally one : [Maven the definitive guide|http://www.sonatype.com/products/maven/documentation/book-defguide].
{info}

h2. 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.

h3. 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*.

{center} !eclipse-m2repo-cfg.png!{center}

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.

h3. Configuring NetBeans

This section has to be completed.

h1. 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.

-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
{code}

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

\\
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.

# Convert it into an Eclipse project
mvn eclipse:eclipse
{code}

\\
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*.

!petals-developing-components-import1.jpg!

\\
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.

h1. 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.

# Compile and build it for deployment
mvn install
{code}

\\
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:
# The first one is to use the Petals administration console.
# 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).

h1. Testing and debugging a component

h2. 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:
# Stop your Petals. Execute its debug script (debug.bat / debug.sh).
# In your IDE, use the remote debug feature to launch Petals (see below for details).
# Add breakpoints in your component code.

h3. 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*.

!petals-developing-components-debug1.jpg!

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.

h3. Using Netbeans

This secction has to be completed.

h2. 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:
# Start Petals in debug mode (and add breakpoints if necessary in your component code).
# Build and deploy your component in Petals.
# Deploy the service assembly to test with your component (and check that it goes fine).
# Deploy the sample client component (available on the Petals website and in the Petals Quick Start versions).
# Once deployed, the sample client launches a Swing dialog which allows you to call any service inside Petals.

!petals-developing-components-test1.jpg!

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.