This page tells you how to install your first service assembly and introduces the concepts 'service assembly' and 'service unit'

Service assemblies

In order to deploy an application to a JBI container, it is packaged as a service assembly, much like a JAVA web application is packaged in a WAR file. In the next tutorial, we'll go into more detail on how to create your own service assemblies. For now, we are going to look at an out-of-box example service assembly, deploy it and access the services that are being defined.

Deploying a service assembly

ServiceMix 3.2

<servicemix_home>/hotdeploy is now the hotdeploy directory for service assemblies

The directory <servicemix_home>/deploy is the hot-deploy directory for service assemblies. If you copy a valid service assembly into this directory, it will be deployed on the JBI container automatically. You can find the example service assembly in <servicemix_home>/examples/wsdl-first/wsdl-first-sa-<version>.zip (where <version> matches the ServiceMix version you're using). If you copy this file into the <servicemix_home>/deploy directory, ServiceMix starts the deployment process. Upon completion of deployment, your console output should show these messages:

INFO  - ServiceAssemblyLifeCycle       - Starting service assembly: wsdl-first-sa
INFO  - ServiceUnitLifeCycle           - Initializing service unit: wsdl-first-jsr181-su
INFO  - ServiceUnitLifeCycle           - Initializing service unit: wsdl-first-http-su
INFO  - ServiceUnitLifeCycle           - Starting service unit: wsdl-first-jsr181-su
INFO  - ServiceUnitLifeCycle           - Starting service unit: wsdl-first-http-su
INFO  - jetty                          - jetty-6.0.1
INFO  - jetty                          - Started SelectChannelConnector @ 0.0.0.0:8192
INFO  - AutoDeploymentService          - Directory: deploy: Finished installation of archive:  wsdl-first-sa-<version>.zip

Testing the service assembly

The deployment output shows that Jetty was started on port 8192. If you now point your browser at http://localhost:8192, you'll get a list of services that are available. If you click on the link for PersonService, you get the WSDL for that service. ServiceMix exposes the service as a web service, but doesn't automatically provided you with a more human-friendly web user interface.

To make it easier to test this web service, there is an HTML file available in the distribution (<servicemix_home>/examples/wsdl-first/client.html). If you open this page in your browser, you can see the SOAP request on the left side. By pressing the Send button, this SOAP message will be sent to the web service that you have just installed. The response will be shown on the right side.

What's (in) a service assembly (SA)?

Now that we know how to deploy a service assembly, it's time to take a look at what is in there. If you extract the archive, you'll find a lot of files in there. Only three of them are absolutely necessary to make up a valid service assembly. First of all there is the JBI deployment descriptor (META-INF/jbi.xml), which describes the rest of the contents of the service assembly. The services itself are being defined in service units. This assembly consists of two service units:

  • wsdl-first-jsr181-su-<version>.zip contains configuration for a web service developed as a JSR-181 compliant POJO
  • wsdl-first-http-su-<version>.zip contains the necessary configuration information to expose the previous webservice using HTTP

What's (in) a service unit (SU)?

In JBI, service units hold the actual configuration information for the services being deployed. You need to have at least one service unit for every JBI component you want to use in your application. For instance, in this case we have two service units, because we want to build a service using JSR-181 (service unit that targets the servicemix-jsr181 service engine) and expose it to the outside world using HTTP (targeting the servicemix-http binding component).

If you extract the contents of either one of the service unit files mentioned before, you again get a set of files in there. The most important one is xbean.xml, an XML file to hold the configuration information. We are going to look into building these files ourselves in the next tutorial

Things to remember

  • Applications for a JBI container are packaged in a service assembly.
  • You can install a service assembly by copying it to <servicemix_home>/deploy
  • A service assembly consists of a deployment descriptor and service units.
  • A service unit contains the necessary configuration for configuring services, targeting a single JBI component.

Further reading