h1. Getting Started
|
The purpose of this document is to provide a starting point for those new to ServiceMix and JBI. OSGi. Please read through each section here and if you have any questions, please just hop on the ServiceMix user [mailing list|Mailing Lists] to ask any questions you might have.
|
|
{info:title=Are You Familiar With Web Applications?}
If you are at all familiar with web applications, then you should find that the high level steps of getting started with ServiceMix are not much different than getting started in building web applications and deploying them to a web container like Jetty or Tomcat. First you need a good understanding of web application concepts. Next, you walk through some tutorials and examples to help you build and package a web application. Third, you install the binary distribution of the web container so that you can deploy your WAR files and run your application. The same basic steps apply here except that you're using ServiceMix instead of a web container and SUs/SAs instead of WARs.
{info}
|
h2. Introduction, OSGi and ServiceMix
ServiceMix is a complete and professional integration platform powered by OSGi. It provides an enterprise ready powerful Enterprise Service Bus (ESB). Thanks to OSGi, ServiceMix is a highly configurable platform and allow you to extend it very easily.
|
|
h2. Introduction
First read the FAQ entry titled, [What is JBI] and each page linked to that page. This document provides some good base knowledge about JBI concepts before diving any deeper into the the use of the technology.
|
OSGi is a dynamic module system for Java. OSGi provides the standardized primitives that allow applications to be constructed from small, reusable and collaborative components.
|
|
The OSGi Service Platform provides the functions to change the composition dynamically on the device of a variety of networks, without requiring restarts.
To minimize the coupling, as well as make these couplings managed, the OSGi technology provides a service-oriented architecture that enables these components to dynamically discover eath other for collaboration.
ServiceMix integrates a large number of projects such as:
* [Apache Karaf|http://karaf.apache.org] is the ServiceMix kernel
* [Apache ActiveMQ|http://activemq.apache.org] as message broker
* [Apache Camel|http://camel.apache.org] as message routing, components provider and EIP framework
* [Apache CXF|http://cxf.apache.org] as WS-* and RESTful WebService provider
* [Apache ODE|http://ode.apache.org] as WS-BPEL embedded engine
|
h2. Tutorials
The [Tutorials] section is the next step. These tutorials walk you through the basic use of the technology and show you how to build various examples. We are working to continually add new tutorials so please check back often. If there is a use case that you'd like to see, please hop on the ServiceMix user [mailing list|Mailing Lists] to discuss it. We're all very interested in what you'd like to see and we highly encourage contributions from the community.
|
{excerpt}
|
h2. Installing the ServiceMix Binary Distribution
|
{excerpt}
Once you've followed the tutorials to create some SUs and SAs, you'll need to deploy them to ServiceMix. This requires that you install the binary distribution of ServiceMix so that you can deploy your SAs to it. Below are the steps to achieve this.
|
h3. Pre-Installation Requirements
*Hardware:*
|
* 100 MB of disk space for the ServiceMix 34.x binary distribution.
|
*Operating Systems:*
|
* Windows: Windows XP SP2, Windows 2000
|
* Windows: Windows XP SP2, Windows 2000, Windows Vista, Windows 7
|
* Unix: Any Linux/Unix platform that supports Java
*Environment:*
|
* Java Developer Kit (JDK) 1.56.x (Java 56) or better for both deployment and compiling.
|
h3. Binary Distribution Installation Procedure
|
...
|
*Windows:*
{code}
|
> .\bin\servicemix.bat
|
{code}
|
...
|
{code}
$ ./bin/servicemix
|
{code}
|
|
{warning:title=Warning}
Using a IBM 1.5 JVM, you can have error at startup looking like this :
Caught : org.springframework.beans.factory.BeanDefinitionStoreException: Unexpected exception parsing XML document from class path resource [activemq.xml]; nested exception is java.lang.ClassCircularityError
org.springframework.beans.factory.BeanDefinitionStoreException: Unexpected exception parsing XML document from class path resource [activemq.xml]; nested exception is java.lang.ClassCircularityError
To avoid this, add -Xverify:none flag to the java command line.
{warning}
{warning:title=Warning}
Don't close the window containing the command prompt in which ServiceMix is running as doing so will terminate ServiceMix. On Linux/Unix, this can be worked around by starting ServiceMix with the [nohup|http://en.wikipedia.org/wiki/Nohup] utility.
{warning}
h3. Stopping ServiceMix
For both Windows and Unix installations, terminate ServiceMix by typing "CTRL-C" on the command line where ServiceMix is running. ServiceMix uses the [Java shutdown hook|http://java.sun.com/j2se/1.4.2/docs/guide/lang/hook-design.html] to cleanly shut down the container.
|
ServiceMix start and you are in the ServiceMix shell.
|
|
In ServiceMix 4.x you exit the shell by pressing "CTRL+D". To shutdown ServiceMix 4.x from the shell you type "osgi:shutdown".
|
{excerpt}
Do not close the console or shell in which ServiceMix was started, as that will terminate ServiceMix (unless ServiceMix was started with nohup).
{excerpt}
|
|
h2. Additional Resources
After the installation, ServiceMix is running with a basic configuration. For details on configuring additional options, please see [Configuration].
|
You can also start ServiceMix directly in background:
|
|
Before trying to use ServiceMix, make sure to read the [What is JBI] document, take a look at the available [Components list] for a list of JBI compliant components and get an idea for the ServiceMix [Architecture] along with the supported [NMR Flows].
|
*Windows:*
{code}
> .\bin\start.bat
{code}
|
|
A good next step is to deploy and run the [Examples] that are part of the ServiceMix binary distribution. The examples are located in the _examples_ directory under the directory in which ServiceMix was installed.
|
*Linux/Unix:*
{code}
$ ./bin/start
{code}
|
|
{tip:title=Handy Hint}
Add _$SERVICEMIX_HOME/bin_ directory to _$PATH_ variable to simplify execution of the examples.
{tip}
|
|
To view the statistics and operation of ServiceMix in a JMX Console and see how the Management works please read the page about the [JMX Console] and the page about [Management].
|
h3. Stopping ServiceMix
For both Windows and Unix installations, terminate ServiceMix by typing "CTRL-D" on the command line where ServiceMix is running.
|
|
[Getting Started with Fuse ESB|http://fusesource.com/docs/esb/4.3/esb_getting_started/index.html] provides a detailed overview of ServiceMix, the requirements for installing ActiveMQ, and a good tutorial to get you up and running quickly. In addition, [FuseSource|http://fusesource.com] provides detailed documentation on using ServiceMix at [http://fuseosurce.com/docs/esb].
|
You can also type "osgi:shutdown" in the ServiceMix shell.
|
|
h3. Working With the ServiceMix Source Code
If you're interested to dig in and work with the ServiceMix source code, take a look at the [Source] and the [Building] documents. These documents will help you check out the ServiceMix source code using Subversion and build it using Maven.
{excerpt}
|
If you started ServiceMix in background, you can use:
|
|
*Windows:*
{code}
> .\bin\stop.bat
{code}
*Linux/Unix:*
{code}
$ ./bin/stop
{code}
|
{children:all=true}
|
