Tutorial: Creation of a
...
Hello World
...
Style of JBI Component
Note |
---|
The content of this document |
...
overlaps a bit with Creating a Standard JBI Component and Notes on Creating JBI Component using maven2. Any changes you might want to make to |
...
this document |
...
may be relevant for |
...
these documents as well. |
...
In addition, questions not answered by this document may be answered by the |
...
one of those documents. |
...
Note |
---|
...
can be very useful, especially for new users |
...
as it focuses on using the |
...
samples and components shipped with ServiceMix |
...
. |
This tutorial describes how to create a very simple " Hello world" World style of JBI service engine (SE) component, pack it into a Service Unit (SU) which will be packed to a Service Assambly (SA), and finally how to run the SE inside ServiceMix. The SE will answer received messages with "Hello, I received xyz bytes!", so we literally see that it works. As it has the same structure as real, useful SE, the given hints help to use the presented code as a blueprint to create own SE-SA-SUs. Still, the example is as minimalistic as possible, so readers shall not get lost in too many details but get an idea of the big picture.
This tutorial shows the desired/best practices or "clean" way to create a SE-SA-SU using ServiceMix Maven archetypes and the Maven plugin (see Maven JBI plugin), so how the workflow shall be - of course, other possibilities exist and may be better suited for certain situations. Furthermore, it will explain the reasons for critical choices and how required information can be retrieved. Where appropriate, additional reading is suggested.
To make it as easy as possible to follow the descriptions, they contain only the relevant code snippets, while the full code is available in the SVN repository. Please note that the code snippets are fetched directly from the full code in the SVN repository, thus the wiki and the code share always at the same, up to date state.
Tip | ||
---|---|---|
| ||
This tutorial is especially useful for ServiceMix beginners. The Maven Getting Started Guide is a recommended and short reading. It explains most of the Maven related things needed. |
Note | ||
---|---|---|
| ||
INS When to use this JBI Component provide exact position in the SVN! maybe moving the content of overlapping existing docus to this new tut and - where appropriate - delete the old ones (only leaving a redirect). This shall already include everything stated at provide additional reading |
Prerequisites
The following is required:
- Around 15 minutes of time
- A running copy of ServiceMix 3.0 and Maven 2.0.4 or higher
- A connection to the Internet to download dependencies
- A text editor to alter XML files
- An editor or IDE for Java files
Overview SE-SU-SA
JBI components are can be tought of as the "smallest applications" you can access in an ESB. They have a very specific purpose, thus a narrow scope and set of functionallity. Components come in two flavours: Service Engine (SE) and Binding Components (BC).
Components are enriched by metadata (which?) and the whole is packed into a Service Unit (SU) - basically a JAR archive.
. It demonstrates some best practices for creating JBI components. The example in this tutorial is as minimalistic as possible so as to focus on key concepts and not drown in details. The example component will respond to all requests with the message:
Panel |
---|
Hello, I received <xyz> bytes! |
Note | ||
---|---|---|
| ||
INS When to use this JBI Component provide exact position in the SVN! maybe moving the content of overlapping existing docus to this new tut and - where appropriate - delete the old ones (only leaving a redirect). This shall already include everything stated at provide additional reading |
Prerequisites
- Maven 2.0.4 or higher
- If you have never used Maven previously the Maven Getting Started Guide explains some valuable concepts surrounding Maven
- ServiceMix 3.0 or higher
- See the ServiceMix downloads
- A broadband internet connection (so Maven can automatically download dependencies)
A Very Brief Introduction to Java Business Integration
The Java Business Integration (JBI) spec provides a standards-based, service-oriented approach to application integration through the use of an abstract messaging model, without reference to a particular protocol or wire encoding. JBI introduces the concepts of Binding Components (BCs), Service Engines (SEs) to Service Units (SUs) and Service Assemblies (SAs) to define an architecture for vendor-neutral pluggable components. The purpose of this architecture is to provide standards-based interoperability amongst components/services.
JBI components are can be thought of as the smallest applications or services accessible in a service-oriented architecture. Each service has a very specific purpose and therefore a narrow scope and set of functionality. Components come in two flavours: Service Engine (SE) and Binding Components (BC). Several SUs are packed into a SA. An SA is a complete application consisting of one or more services interacting with one another.
See also the page providing information on working with service units
Below are some quick definitions:
- Component Architecture
- Binding Components - Components that provide or consume services via some sort of communications protocol or other remoting technology
- Service Engines - Components that supply or consume services locally (within the JBI container)
- Component Packaging
- Service Units - Packaging for an individual service that allows deployment to the JBI container; similar to a WAR file from J2EE
- Service Assemblies - Packaging for groups of SUs for deployment to the JBI container; similar to an EAR file from J2EE
For further reading, see the JBIforSOI document for a good introduction to JBISeveral SUs are packed into a Service Assambly (SA). An SA is a complete "application" consisting of multiple components (reminder: the "smallest appliactions") interacting with each other and making up the big "application".
Note | ||
---|---|---|
| ||
Further reading: JSR 208. Include references from here to sections/pages in the spec. Maybe add an attachment to this wiki page containing a FDF (annotations for the PDF) so skimming the sepc quickly without missing important information is possible. |
Creating the
...
Creating the stub of the SE
First, a JBI component has to be created. Here, we use archetypes, just like shown at Creating a Standard JBI Component and Notes on Creating JBI Component using maven2 and Creating a protocol bridge. The Maven 2 archetypes are a kind of pattern, generic model, blueprint or template, or as Merriam-Webster defines "the original pattern or model of which all things of the same type are representations or copies". Using archetypes, Maven creates the basis for components, settings and so on, thus archetypes spare developers repetetive work and avoid errors like typos etc.
...
Maven Projects for Each Component
Creating a Skeleton Project For the JBI Service Engine (SE)
The focus of this section is on the creation of a JBI component. For this task, a Maven archetype will be used to create a Maven project skeleton to house the component. Maven archetypes are templates for Maven projects that jumpstart project creation via the automation of repetitive tasks by following standard conventions. The result of using an archetype to create a Maven project is a directory structure, a Maven POM file and, depending on the archetype being used, sometimes Java objects and JUnit tests.
Note |
---|
As this text describes how to create a |
...
Hello World |
...
service engine and pack it into |
...
a SU and SA, the project name is |
...
|
...
given project, the IDs and names shall be altered such that they describe the purpose or function of the given piece of |
...
the SA. |
1) Create a directory named hello-world-se:
Code Block |
---|
$ mkdir hello-world-se
|
2) Use a Maven archetype to generate a Maven project for the SE:
Panel |
---|
mvn archetype:create -DarchetypeGroupId=org.apache.servicemix.tooling -DarchetypeArtifactId=servicemix-service-engine \ |
The first three parameters to the mvn
command (
First, we create a directory hello-world-SE-SU-SA and open a command line in this folder. Now we execute the following command (it has to be one line but was split to be readable):
...
-DarchetypeGroupId=org.apache.servicemix.tooling -DarchetypeArtifactId=servicemix-service-engine
...
-DarchetypeVersion=3.
...
1-incubating-SNAPSHOT) identify which Maven archetype to use for the archetype:create
goal, while the last two parameters (-DgroupId=org.apache.servicemix.samples.
...
helloworld -DartifactId=hello-world-
...
se) uniquely identify the Maven project that is being generated. The groupId
(printed in pink) is used as the Java package and the artifactId
is used as the project name. Therefore, only alphanumeric characters valid values for the groupId
and artifactId
parameters.
Tip |
---|
The value of the |
The output from executing the archetype:create
goal is shown below (only relevant information has been The first three parameters identify the maven 2 archetype to use, while the last two parameters define the generated maven 2 project. The version information "3.0-incubating" may have to be changed; a look at any of ServiceMix' pom.xml reveals the version to use. Maven uses the group ID (printed in pink) as default Java package (see output below as well), thus invalid characters like minus, percent etc. must be avoided or a custom package name has to be given as parameter. Mavens output following the command looks like this (only relevant information preserved):
Panel | ||
---|---|---|
|
Maven creates a new folder having the same name as the artifact ID directory using the artifactId
provided (printed in green in the command and output). Inside this folder, a file called pom.xml is created. This contains the Project Object Model providing Maven with all needed information for building (see Introduction to the POM at the Maven website). Moreover, Java source files and tests were createddirectory resides the pom.xml
and the src
directory.
Note | ||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||
The The maven-archetype-plugin 1.0-alpha4 or above is required for this tutorial. When an older version is installed, a BUILD ERROR build error will occur. The version of this plugin can be checked by having a look at verifying the name of the directories contained in following directories:
). In case the only version available is an older version is presentone, we create a minimal
<build> <pluginManagement> <plugins> <plugin>
|
Creating the
...
Project For the SU and
...
SA
The archetypes for SUs and SAs do not contain much code, but rather help with tasks related to Maven. Later, we will only need to adapt the POMs to our project - just little work.
In From within the directory hello-world-
SE-SU-SA we se
, execute the following commands (they have to be one line but were split to be readable) to create the project for the SU:
No Formatcode |
---|
mvn archetype:create -DarchetypeGroupId=org.apache.servicemix.tooling -DarchetypeArtifactId=servicemix-service-unit \ -DarchetypeVersion=3.01-incubating-SNAPSHOT -DgroupId=org.apache.servicemix.samples.helloWorldSEhelloworld -DartifactId=hello-world-SUsu |
and From within the directory hello-world-se
, execute the following commands to create the project for the SA:
No Formatcode |
---|
mvn archetype:create -DarchetypeGroupId=org.apache.servicemix.tooling -DarchetypeArtifactId=servicemix-service-assembly \ -DarchetypeVersion=3.01-incubating-SNAPSHOT -DgroupId=org.apache.servicemix.samples.helloWorldSEhelloworld -DartifactId=hello-world-SA |
By now, the full structure of files is created by Maven and looks like this:
sa
|
The directory structures for each project should appear as follows:
Code Blocknoformat |
---|
C:\hello-world-SE-SU-SAse\hello-world-SAsa C:\hello-world-SE-SU-SAse\hello-world-SAsa\pom.xml C:\hello-world-SE-SU-SAse\hello-world-SEse C:\hello-world-SE-SU-SAse\hello-world-SEse\pom.xml C:\hello-world-SE-SU-SAse\hello-world-SEse\src\main\java\org\apache\servicemix\samples\helloWorldSEhelloworld C:\hello-world-SE-SU-SAse\hello-world-SEse\src\main\java\org\apache\servicemix\samples\helloWorldSEhelloworld\MyBootstrap.java C:\hello-world-SE-SU-SAse\hello-world-SEse\src\main\java\org\apache\servicemix\samples\helloWorldSEhelloworld\MyComponent.java C:\hello-world-SE-SU-SAse\hello-world-SEse\src\main\java\org\apache\servicemix\samples\helloWorldSEhelloworld\MyDeployer.java C:\hello-world-SE-SU-SAse\hello-world-SEse\src\main\java\org\apache\servicemix\samples\helloWorldSEhelloworld\MyEndpoint.java C:\hello-world-SE-SU-SAse\hello-world-SEse\src\main\java\org\apache\servicemix\samples\helloWorldSEhelloworld\MyLifeCycle.java C:\hello-world-SE-SU-SAse\hello-world-SEse\src\main\java\org\apache\servicemix\samples\helloWorldSEhelloworld\MySpringComponent.java C:\hello-world-SE-SU-SAse\hello-world-SEse\src\test\java\org\apache\servicemix\samples\helloWorldSEhelloworld C:\hello-world-SE-SU-SAse\hello-world-SEse\src\test\java\org\apache\servicemix\samples\helloWorldSEhelloworld\MySpringComponentTest.java C:\hello-world-SE-SU-SAse\hello-world-SEse\src\test\resources C:\hello-world-SE-SU-SAse\hello-world-SEse\src\test\resources\spring.xml C:\hello-world-SE-SU-SAse\hello-world-SUsu C:\hello-world-SE-SU-SAse\hello-world-SUsu\pom.xml C:\hello-world-SE-SU-SAse\hello-world-SUsu\src\main\resources |
According to the template rules, all the classes have the word "My" prefixed to them. We can rename the prefix to whatever we want to, as long as we make sure we change Java objects are prefixed with the word My. These Java objects can be renamed to whatever you prefer, making sure to also change the names in the corresponding resource files (all tests and the {{pom.xml}}s) as well.
Incorporating the SU and SA
...
Into the
...
Top Level POM
Now that we have created the SU and SA structure, we incorporate them into the main POM. We create a file called pom.xml in the projects, the top level pom.xml} must be made aware of each one. In the {{hello-world-
SE-SU-SA directory and instert se
directory create a file named pom.xml
containing the following content:
No Formatcode |
---|
<project> <modelVersion>4.0.0</modelVersion> <groupId>org.apache.servicemix.samples</groupId> <artifactId>helloWorldSE< <artifactId>hello-world-se</artifactId> <version>1.0-SNAPSHOT</version> <packaging>pom</packaging> <modules> <modules> <module>hello-world-SA<sa</module> <module>hello-world-SU<su</module> </modules> <dependencies> <dependency> <dependency> <groupId>org.apache.servicemix.samples.helloWorldSE<helloWorldse</groupId> <artifactId>hello-world-SU<su</artifactId> <version>1.0-SNAPSHOT</version> </dependency> </dependencies> </project> |
The <modules>
entity defines which child projects belong to the main project. The <dependencies> entity causes element denotes the child projects that were created using the Maven archetypes and the <dependencies>
element tells Maven to include the SU into the SA when it is constructed.Note:
Note |
---|
The content of |
...
the |
...
version of projects that were just created. We just have to use |
...
consistently the same version when we reference this project. |
...
Using Maven to Build and Package the Components
By now, it is already possible to call Maven with the relevant goals.
Compiling the
...
Components
In order to build, package and place a copy of each component in the Maven repository onyour local machine, execute the following from within hello-world-se
directory:
Code Block |
---|
We can build the code by executing
No Format |
---|
mvn compileinstall |
in the hello-world-SE-SU-SA/hello-world-SE directory and Maven shall present as one of the last lines of output
...
In case this success information is does not appearingappear, the output shall give information on the reasons. Further information can be found in will provide some information about what might have gone awry. Assistance with any issue you might experience is available from the ServiceMix community via the ServiceMix mailing lists archive and the Maven website.
Testing the
...
Components
Performing Doing automated testing of the code components is possible via Maven as well. As Because the ServiceMix ' root POM disables testing, we have to be activate it for the subprojects that shall prevents tests from being executed at the top level, this functionality must be activated so that the coponents can be tested. To do so, the <build>
entity of our hello-world-SE-SU-SA/ element of the hello-world-
SEse/pom.xml
has to be enriched by must be augmented using the following content:
Code Blocknoformat |
---|
<pluginManagement> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-surefire-plugin</artifactId> <configuration> <skip>false</skip><!-- this overrides the ServiceMix' root POM and forces to execute the tests's setting for test execution --> </configuration> </plugin> </plugins> </pluginManagement> |
where <skip>false</skip> is the relevant line of code. Now, when executing
By adding the configuation above, the install
goal will now including test execution in addition to building and packaging the components. To run the tests, execute the test
goal this time and you should see the following output:
Code Block |
---|
$ |
No Format |
mvn test
|
tests will be done and Maven outputs the following (truncated to the relevant information):
No Format |
---|
[INFO] Scanning for projects... [INFO] ---------------------------------------------------------------------------- [INFO] Building A custom project [INFO] task-segment: [test] [INFO] ---------------------------------------------------------------------------- ... [INFO] [compiler:compile] ... [INFO] [surefire:test] [INFO] Setting reports dir: c:\java\tmp\servicemix-helloWorldSE\target/surefire-reports ------------------------------------------------------- T E S T S ------------------------------------------------------- [surefire] Running org.apache.servicemix.samples.helloWorldSE.MySpringComponentTest ... [surefire] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 1,422 sec [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESSFUL [INFO] ------------------------------------------------------------------------ ... |
Note | ||
---|---|---|
| ||
Maybe add further testing at the end of the tutarial ("how to continue when having the working example") |
Generation and
...
Deployment of the SA
...
The execution of the install
goal above packages not only each component individually, it also packages the components together into a single SA. Of course, the code does not yet do anything, but we can already deploy the SA ServiceMix by switching to the hello-world-se/hello-world-sa
directory and executing the jbi:projectDeploy
goal like so:
Code Block |
---|
$ mvn jbi:projectDeploy
|
This tells the Maven JBI plugin to deploy the components to ServiceMix
By running
No Format |
---|
mvn install
|
from the hello-world-SE-SU-SA directory, the SA is generated in the hello-world-SE-SU-SA/hello-world-SA/target/ directory. Of course, our code does not yet do anything, but we can already deploy the SA and needed components to a running ServiceMix container by switching to the hello-world-SE-SU-SA/hello-world-SA/ directory and calling
No Format |
---|
mvn jbi:projectDeploy
|
Essentially, the plugin will walk the dependencies starting in the current project, then deploy each of the dependencies in reverse order. So it copies contents of the hello-world-SA-1.0-SNAPSHOT.zip and orther sources to ServiceMix subdirectories. For further information see Maven JBI plugin. When the deployment is complete, ServiceMix will output this confirmationthe following:
No Format |
---|
INFO - ServiceAssemblyLifeCycle - Starting service assembly: hello-world-SAsa |
Note: The command mvn install executed in the hello-world-SE directory creates a JAR and also a component installer. For installation, mvn jbi:installComponent has to be executedThis output tells us that the SA was successfully deployed to ServiceMix.
Note | ||
---|---|---|
| ||
When working with the <build> See also https://issues.apache.org/activemq/browse/SM-605?page=all for command line options. |
Adding functionality
during deployment. To stop the Maven JBI plugin from undeploying and redeploying dependencies each time, alter its configuration by disabling the deployment of dependencies using the following:
The configuration above introduces the For a few more configurable options on the Maven JBI plugin, see also Ability to configure jbi:projectDeploy goal to exclude updating dependencies. |
Adding Functionality to the Component
We're now ready to add a bit of functionality to the component. Using an IDE like IntelliJ IDEA or Eclipse make this task much easier. The steps described here apply to EclipseThe structure is done, so the functionality have to be added. Using an IDE like IDEA or
Eclipse this is easier; here, the workflow with Eclipse is described.
Note | ||
---|---|---|
| ||
The default implementation of the component accepts InOut MEPs (ADD OUTLINE for further work:
Classpath for SU to include manually manually till v3.1, see mail manually editing http://goopen.org/confluence/display/SM/Working+with+Service+Units |