PEtALS Quick Start Distribution 

Roland NAUDIN

Christophe HAMERLING

PEtALS Team

(CC) EBM WebSourcing - This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/3.0/

Abstract

This document presents the Quick Start release of PEtALS. This release targets PEtALS beginners to ease their first step with PEtALS.

Table of Contents

Preface
1. Presentation
1.1. What is PEtALS?
1.2. Acronyms
1.3. Quick Start features
2. PEtALS container
2.1. Pre-Requisites
2.2. Installation
2.3. Directory structure
2.4. Configuration
2.5. Starting PEtALS
2.6. Stopping PEtALS
3. Use cases
3.1. Call the Time service
3.2. Say hello to the world
3.3. Transfer a file
3.4. Make some data transformation
4. Next steps...

List of Figures

1.1. PEtALS is an ESB fully JBI compliant
3.1. File Transfer use case
3.2. Transformation use case

Preface

PEtALS delivers the OW2 Java Business Integration (JBI) bus (See JSR-208 specifications for further details on JBI).

Since its beginning, PEtALS has increased its coverage amongst different high value domains like clustering, robustness, availibility, performance... Moreover, PEtALS relies entirely on its OW2 partner technology, the Fractal component model, which brings to its architecture a strong modularity. Please visit the Fractal web site for further details at http://fractal.objectweb.org.

Since the version 2.1 of the PEtALS kernel, the PEtALS team have decided to exploit Fractal leverage by delivering various PEtALS distributions. Each distribution is packaged and customized to be addressed to a specific audience.

As its name suggests, this distribution is attended to PEtALS beginners, it proposes an all-in-one PEtALS container with an embedded Web console, simple use cases and this getting-started documentation.

The documentation leads you through the PEtALS universe and introduces the specialized documentations when needed.

Chapter 1. Presentation

Table of Contents

1.1. What is PEtALS?
1.2. Acronyms
1.3. Quick Start features

PEtALS helps you to integrate your Enterprise Business Units in order to provide a coherent and rational global solution. With PEtALS, you can compose your new applications by integrated already existing ones and new ones.

Thus, all your applications expose their business logic by exposing services. This concept is well known as Service Oriented Architecture (SOA).

PEtALS offers a solid backbone for your enterprise Information System and acts as a Bus, a place where all your data are exchanged. PEtALS connects services to each others. PEtALS is an Enteprise Service Bus (ESB).

Please visit our Web site for further details at http://petals.ow2.org.

Figure 1.1. PEtALS is an ESB fully JBI compliant

PEtALS is an ESB fully JBI compliant

Along the document, we are using common JBI acronyms :

The Quick Start distibution provides the following modules:

Once achieved the 4 use cases, you will be able to build your own integrations; you will be a new member PEtALS users community!

Chapter 2. PEtALS container

Table of Contents

2.1. Pre-Requisites
2.2. Installation
2.3. Directory structure
2.4. Configuration
2.5. Starting PEtALS
2.6. Stopping PEtALS

PEtALS doesn't require any installer to be installed. Just unzip the provided archive where you want to install it.

Generally, PEtALS find by itself its directory location. On some systems, the installation path can not be automatically found, in such case you must set the PETALS_HOME environment variable :

The Quick Start PEtALS is pre-configured to work properly.

If you want to customize the configuration, please use the PEtALS Standalone distribution and the PEtALS Platform distribution.

  1. Go to $PETALS_HOME/bin

  2. Launch startup.sh or startup.bat :

    # ./startup.sh

    You can launch PEtALS in console mode, to be able to interact with it via the terminal. In this case, use the option -C in the terminal :

    # ./startup.sh -C
    [Note]Note

    You can also use directlty the jar server.jar in the $PETALS_HOME/bin, with the command start, stop, shutdown as argument.

There is several ways to stop PEtALS :

  1. If PEtALS is launched in a simple terminal, type <ctrl>+ c to stop PEtALS.

  2. If PEtALS is launched in console mode, just type q or x and <enter> in the terminal :

    # q

    By typing q, PEtALS is stopped; components, SAs ant SLs aren't uninstalled/undeployed.

    By typing x, PEtALS is shut down; components, SAs ant

    SLs are uninstalled/undeployed.

  3. If PEtALS is launched in background, launch the stop.sh script :

    # ./stop.sh

  4. If PEtALS is launched in background mode, launch the shutdown.sh script :

    # ./shutdown.sh

Chapter 3. Use cases

Table of Contents

3.1. Call the Time service
3.2. Say hello to the world
3.3. Transfer a file
3.4. Make some data transformation

With this simple use case, you will be able with few manipulations to invoke your first service in the PEtALS Bus.

Here are the steps to follow :

  • Start your PEtALS container (see section 2.5) in console mode

  • Copy the Clock sample component located in the samples directory into the $PETALS_HOME/install directory . The PEtALS auto-installer automatically installs and starts the component

  • In the PEtALS terminal, type d, the terminal will diplay the content of the PEtALS JNDI repository. You should see something the new endpoint exposed by the Clock component :

    JNDI directory local 
<== / ==>

        <=users=>

        <=new-endpoints=>
                -> {http://petals.ow2.org}ClockService@ClockEndpoint [Link to /endpoints/{http://petals.ow2.org}ClockService@ClockEndpoint]

        <=services=>

                <={http://petals.ow2.org}ClockService=>
                        -> {http://petals.ow2.org}ClockService@ClockEndpoint [Link to /endpoints/{http://petals.ow2.org}ClockService@ClockEndpoint]

        <=endpoints=>
                -> {http://petals.ow2.org}ClockService ->ClockEndpoint (INTERNAL):subdomain1/0/petals-sample-clock

        <=interfaces=>

  • Copy the sample client component located in the samples directory into the $PETALS_HOME/install directory . A graphical interface is displayed at the component startup.

  • With the help of the Client component documentation (http://petals.ow2.org/components.html), try to invoke the printTime operation to the ClockEndpoint. You should see a message on the PEtALS terminal like :

    [petals.container.components.petals-sample-clock]-INFO 2008-07-18 14:48:24,923 [petals-sample-clock] The ClockImpl service is called to display current time
[petals.container.components.petals-sample-clock]-INFO 2008-07-18 14:48:24,923 [petals-sample-clock] Time : Fri Jul 18 14:48:24 CEST 2008

  • Once your first service invocation done, try to change the MEP (Message Exchange Pattern) and the possible operations with the help of the service description (WSDL); see the error or fault generated when the operation or pattern is not supported by the Clock component.

  • To clean your PEtALS server, type x on the PEtALS console. All the installed JBI artefacts are automatically uninstalled and the PEtALS container is shut down.

This use case introduces the usage of the PEtALS Web console. This console allows you to administrate and monitor you PEtALS container in a nice and intuitive way.

Follow the steps:

  • Start your PEtALS container (see section 2.5)

  • With your favorite Web browser (of course we preconize to use Firefox), connect to the Web Console at the URL http://localhost:7878. Use default values to configure the Data Collector and to log in.

  • With the help of the Web Console documentation (http://petals.ow2.org/documentation.html), install and start the Helloworld sample component and the Client sample component, located in the samples directory.

  • Once the components are installed, unzip the use case Helloworld, located in usecases/petals-simplehelloworld.zip. Deploy and start the contained SA named sa-simplehelloworld.zip with the Web console administration section.

  • If you unzip the sa-simplehelloworld.zip SA, you will see that it contains another zip file, named su-simplehelloworld-provide.zip. This zip file is in fact a SU which decribes a provide service for the Helloworld component. Check in each JBI artifact the file META-INF/jbi.xml.This file is the JBI descriptor, the standard element which describes all the relevant information to build service configurations in JBI components.

    [Note]Note

    If you check in the JBI components zip files, you will find the same JBI descriptor. In this case, the JBI descriptor defines the component configuration itself. If you want more information on these descriptors, please see the JBI specifications.

  • With the Client sample GUI, get the service description (WSDL) of the Helloworld service and retrieve the available operations. Invoke the different operation (sayHello, printMessage) like for the previous use case and see what happened.

  • To clean your PEtALS server, type x on the PEtALS console. All the installed JBI artefacts are automatically uninstalled and the PEtALS container is shut down. You cant just shut down PETALS by typing q for example. When you will restart PETALS, the installed JBI elements would be recovered to retrieve their previous life-cycle states.

Now that you are more familliar with PEtALS and the sample components, we will introduce a real case of integration. This integration is quite simple, it consists to poll files from a local directory named in and transfer it to another directory named out. The file is sent through the PEtALS BUS as an attachment in a JBI Message Exchange.

Figure 3.1. File Transfer use case

File Transfer use case

In this use case, we introduce the usage of Apache Ant technology and specially the JBI dedicated ant tasks provided by PEtALS.

[Note]Note

You must have Ant installed on your system to process the use case (see section 2.1).

Please follow these steps:

You can have a look to the petals-bc-filetransfer component documentation (http://petals.ow2.org/components.html) for further details about how to configure it.

You can have a look to the samples of Ant task in the directory ant-sample of the Quick Start package, to have an illustration of all the possible PEtALS Ant tasks.

This last use case provides a more complex integration than an IN/OUT message flow. It involves a light orchestration of Message Exchange to build the complex message flows.

In this use case, we introduce the usage of the EIP component (Enterprise integration Patterns) to build a basic orchestration. The ingoing flow is exposed by a Web Service via the SOAP component, and the service itself is a transformation processed by the XSLT component.

Figure 3.2. Transformation use case

Transformation use case

Here are the steps to follow for this usecase:

  • Unzip the Transformation use case located at usecases/petals-simpletransformation.zip.

  • Start your PEtALS container if it is not already started.

  • Invoke the Ant goals in the following order from the use case root directory:

    • deploy : This goal installs, deploys and starts all the JBI artefacts required to run the use case.

      # ant deploy

    • run : This goal runs a java program. This program is a Web Service client based on Axis2 which send a request to the transformation Web Service and controls if the returned document is correctly formatted.

      # ant run

      On the Ant client side, you should see this type of message :

      run:
     [echo] Launching usecase simpletransformation...
     [java] log4j:WARN No appenders could be found for logger (org.apache.axis2.util.Loader).
     [java] log4j:WARN Please initialize the log4j system properly.
     [java] 
     [java] Invoking the Web Service at 'http://localhost:8084/petals/services/ExternalSimpleTransformation' with payload:
     [java] Payload:
     [java] <simpletransformation:request xmlns:simpletransformation="http://petals.ow2.org/simpletransformation">
              <simpletransformation:name>NAUDIN</simpletransformation:name>
              <simpletransformation:street>Paradise Street</simpletransformation:street>
              <simpletransformation:city>Toulouse</simpletransformation:city>
              <simpletransformation:documentid>5040</simpletransformation:documentid>
            </simpletransformation:request>
     [java] 
     [java] Response payload:
     [java] <simpletransformation:document xmlns:simpletransformation="http://petals.ow2.org/simpletransformation" simpletransformation:id="5040">
     [java]   <simpletransformation:name>NAUDIN</simpletransformation:name>
     [java]   <simpletransformation:area>Toulouse - Paradise Street</simpletransformation:area>
     [java] </simpletransformation:document>
     [java] Usecase simpletransformation SUCCESSFUL
      On the PEtALS console, you will see some log messages which shows that the SOAP message has been received by the SOAP BC, forwarded to the EIP one, to the XSLT...

    • clean : This goal cleans the PEtALS environment, it removes the deployed components and SA.

      # ant clean

Do not hesitate to pick a glance to the SA package in the deployables directory of the use case. You can see how the SUs are configured compared to the related component documentations (http://petals.ow2.org/documentation.html).

[Note]Note

If you want to test this use case with a graphical Web Service client, please have a look to the SOAP use cases documentation to get information about how using SOAPUI product.

Chapter 4. Next steps...

Now that you are quite familiar with PEtALS, you can start creating your own integration or service oriented application based on the large repository of PEtALS components. Check the available components at http://petals.ow2.org/components.html.

More adavanced use cases mainly based on SOAP capabilities are availbale on the project Web site.

If you want to control or optimize the PEtALS configuration, please refer to the Standalone distribution documentation.

If you are interesting about running PEtALS in a distributed environment, please refer to the Platform distribution documentation.

You can be interested to build your own components and thus join the PEtALS community. The PEtALS team provides a framework which handles most of the parts of JBI mechanisms and lets you focus on your business logic: the Component Development Kit (CDK).

PEtALS team work is based on prooved quality tools. The team has also written a guide to lead any interested developer who wish to join the PEtALS developer team (http://petals.ow2.org/documentation.html).