Roadmap for a perspective Servicemix developer

THE POINT:

• connect the dots between the documentation already existing on the Servicemix website
• Give a developer interested in Servicemix a run through on getting the software up and running
• Give the developer instructions on compiling/installing the packaged Smix examples
• Give the developer information on monitoring/configuring the software via jconsole
• Create two working service assemblies (SA's) which work together, using out of the box Smix components!

Also...

Check out Hello World - SE and Hello World - BC, tutorials in progress on creating a simple JBI service engine (SE) and simple JBI binding component (BC) using the ServiceMix Maven tooling (mainly Maven archetypes).

Conventions:

TERMS:

1. 'company repository' = a remote Maven 2 repository used within your company to hold dependencies/artifacts.
2. [Smix_source_folder] = the location of the folder created after uncompressing the downloaded Smix source distribution (from .zip, .tar.gz etc.).
3. [Servicemix_binary_distribution_home] = installation location of the Smix binary distribution on your machine

Note: I am using apache-servicemix-3.0-incubating-20060907.104512-15-src.tar.gz for the following tutorial. If you do not use this snapshot release I cannot guarantee the following will work.

Note: I am writing all this from a Apple MacBook, and therefore the tutorital is from a BSD perspective.

BEFORE STARTING:

• You will need Maven 2.0.4 or greater installed on your machine

Getting the component dependencies into your local machine/company repository

If you are going to be running any of the examples or doing any development with a current SNAPSHOT/release then you may want to do a few things first. It makes sense to check out the 3.0 (SNAPSHOT if you want the newest) source code so that you can install the Smix component dependencies in your local repository. First go here and download the ServiceMix 3.0 sources. Next you will want to build the Servicemix app and it's included components. Go to Building for instructions.

Once you have built the 3.0 app, following the instructions linked above, the Smix component modules will be installed locally.

Next up install the compiled binary Servicemix...

You now have Smix built from source, and the Smix components in a Maven 2 repository. The built distribution of Smix will be in [Smix_source_folder]/apache-servicemix/target. There will be a source distribution that is like (exactly like?) the one which you downloaded, and the .zip, .tar.gzip binary distributions. Install the binary distribution following the source installation instructions for Windows respectively Unix. Once you have installed the binary Servicemix installation you are ready to do some testing.

wsdl-first

The first thing to do now is install the wsdl-first service assembly (SA) which contains a few service units (SU's) (see JBI specification document). The end result is a XFire based SOAP service which is pretty simple. The actual code for the service is in the file [Servicemix_binary_distribution_home]/examples/wsdl-first/wsdl-first-jsr181-su/src/main/java/org/apache/servicemix/samples/wsdl_first/PersonImpl.java. Phew! Take a look at the code, it is pretty simple. It uses an annotation which describes the class as a jsr181 web service. One interesting thing to note about this project is the use of an ant task inside the parent pom.xml. This task uses XFire's WsGenTask to create Java objects used by the web service, as described in the WSDL file.

So let's get this up and running in our Smix container. Start Smix, watch the output to make sure things start up correctly. You will need to open up a new console for the next step, since the Smix output is taking up the other. You will be able to watch this output to see what is going on in some of the following steps. Go back to [Servicemix_binary_distribution_home]. You need to copy the components needed by the wsdl-first SA from the /components folder to the /install folder. The ones you should copy are:

• servicemix-http-3.0-incubating-SNAPSHOT-installer.zip
• servicemix-shared-3.0-incubating-SNAPSHOT-installer.zip
• servicemix-jsr181-3.0-incubating-SNAPSHOT-installer.zip

With each copied component will come messages from Smix in the console output window. Watch these to make sure things properly install. If any problems crop up, try to copy the component again. I have received a zip related exception before. I did the copy a second time and the problem didn't show itself a second time.

There is an easy way to do the following: copy the file [Servicemix_binary_distribution_home]/examples/wsdl-first/wsdl-first-sa-3.0-incubating-SNAPSHOT.zip into the /install folder. Watch the Smix console window making sure things go well. You can now open a browser and go here to see the WSDL for the SOAP service.

That was the easy way....but you want to learn about developing so let's do it the 'hard' way. First go to the [Servicemix_binary_distribution_home]/examples/wsdl-first folder and type mvn install. This example project is using a Maven 2 plugin for creating specific JBI components. If you look in the module pom.xml files you will see a special packaging type. After the mvn install completes there will be file called wsdl-first-sa-3.0-incubating-SNAPSHOT-installer in the wsdl-first-sa module's target folder. This is the SA for the wsdl-first example project. Now we want to deploy this to our container. The Maven JBI plugin will take care of this for us!!! Note we need to make a small change to the wsdl-first-sa module's pom.xml. The plugin will normally try to install all the shared libraries needed by the SA when running the Maven goal jbi:projectDeploy. This is sometimes useful. But often it causes problems because another SA in Smix is using the shared lib already. In this case the Maven goal will try to remove and redeploy the shared lib from Smix. This causes a problem and will make the SA deployment fail. So to tell the plugin to not do this make the following change in the pom.xml:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.servicemix.tooling</groupId>
            <artifactId>jbi-maven-plugin</artifactId>
            <extensions>true</extensions>
        </plugin>
    </plugins>
</build>

into....

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.servicemix.tooling</groupId>
            <artifactId>jbi-maven-plugin</artifactId>
            <extensions>true</extensions>
            <configuration>
                <deployDependencies>false</deployDependencies>
            </configuration>
        </plugin>
    </plugins>
</build>

That little config change will prevent some headaches later.

You are ready to rock. Change directory to the wsdl-first-sa module. Type 'mvn jbi:projectDeploy'. You can watch the Smix console for information on the deployment.

Temporary excursion into monitoring

One great benefit to JBI and Smix are the monitoring capabilities. Using the jconsole application packaged with the Java SDK you can tap into your Smix instance. In doing so you can get all sorts of information on things like thread and memory usage, and have the ability to configure the Smix environment dynamically. Lets use jconsole! Open a terminal session and type 'nohup jconsole &'. If your machine has the Java SDK's /bin folder in it's path then this should launch the jconsole application. If the application has launched then you should be able to close the terminal window now.

You should see a window titled 'JConsole: Connect to Agent'. In the 'Local' tab's window you should see an entry. Select this entry and press the 'Connect' button. You should now be connected to your local Smix instance. Take some time to play around.

Done? Alright, now lets do some maintanance to the Smix environment. We are going to shut down the wsdl-first SA, then start it back up.

• Select the tab called 'MBeans'.
• This gives a tree like structure that you can navigate through.
• Open the node labeled 'org.apache.servicemix'. Open the 'servicemix' node.
• Open the node labeled 'Endpoint'. You will see all the installed endpoints in your JBI environment here. There should be only one.
• You should see a node labeled 'ServiceAssembly', open this node. You now should see one entry for wsdl-first. Click on this entry. The window to your right should now pop up some information about the SA.
• In the right window click on the tab labeled 'Operations'. You will see four operations: start, stop, shutdown, and getDiscriptior.
• Click the shutdown button. You will get a pop up window containing XML that tells you how the operation went. I hope that you see SUCCESS in the task-result element.
• With the SA shutdown try to get the WSDL and use the client.html app to contact the web service. Niether will work.
• Let us start the SA again, click the start button in the operations window. You again get a pop up with XML.
• Try again to get the WSDL or hit the web service using the client.html app. Both should now work.
  
  
  So this is brief but should give you a good idea of how easy it can be to manage your Servicemix instance(s).

Next up - the bridge example

coming soon....

Handy Hint If you want to see how a component is used in the examples shipping with ServiceMix, try such a  Google Codesearch to find out wich sample uses the component. It's a lot faster than looking on the local hard drive unless you use a specialised desktop search engine.