{section}
{column}

This component provides only services and doesn't act as a consumer of service.
This component is based on the PEtALS CDK.

h1. Exposing a Java class as a POJO service
PROVIDE SERVICE : Expose a Java class as a Service

h2. Usage

{petalslink:author=llacote|type= Note : Titre du PDF d'où est importée cette section : Chapter 3. POJO Services Specifications}{petalslink}

A Java class acting as a POJO service must follow these rules :
* no specific interface implementation is required.
* if a {{public setComponentContext(ComponentContext context)}} setter method is defined, the component set its {{ComponentContext}} instance with this method at the initialization of the POJO.
* if a {{public setDeliveryChannel(DeliveryChannel channel)}} setter method is defined, the component set its {{DeliveryChannel}} instance with this method at the initialization of the POJO.
* if a {{public setJBIListener(AbstractJBIListener jbiListener)}} setter method is defined, the component set its {{JBIListener}} instance with this method at the initialization of the POJO.
* if a {{public setLogger(Logger logger)}} setter method is defined, the component set its {{Logger instance}} with this
method at the initialization of the POJO.
* if a {{public void init()}} method is defined, the compenent invoke it at the initialization of the POJO.
* a {{public boolean onExchange(Exchange exchange)}} MUST be provided.
* all methods can throw exceptions.

A sample class following those rules:
{code:java}
package test;
import java.util.logging.Level;
import java.util.logging.Logger;
import javax.jbi.component.ComponentContext;
import org.ow2.petals.component.framework.api.message.Exchange;
import org.ow2.petals.component.framework.listener.AbstractJBIListener;
public class SamplePojoService {
AbstractJBIListener jbiListener;
Logger logger;
ComponentContext ctx;
public void setJBIListener(AbstractJBIListener jbiListener) {
this.jbiListener = jbiListener;
}
public void setComponentContext(ComponentContext ctx) {
this.ctx = ctx;
}
public void setLogger(Logger logger) {
this.logger = logger;
}
public boolean onExchange(Exchange exchange)
throws Exception {
[...]
jbiListener.sendSync(anotherExchange);
[...]
return false;
}
public void init() {
logger.log(Level.INFO, "SamplePojo inits.");
}
}
{code}
The method {{onExchange(Exchange exchange)}} is invoked when a MessageExchange targeting the POJO service is
received on the component. The POJO service must process the service here.
If the POJO service sets a response on the exchange to support patterns {{InOut}} or {{InOptionalOut}}, the method has to return {{true}}. The component will send the response back.
Otherwise, the method return {{false}} and the component responds with a DONE acknowledgement.
If an exception is raised, depending of the nature of the exception ({{RuntimeException , FaultException}}...) and the pattern, a Fault or an ERROR acknowledgement will be sent.

{center}{*}Configuration of a Service Unit to provide a service (CDK)*{center}
{table-plus:columnAttributes=,,style="text-align:center;",style="text-align:center;"}


|| {color:#333333}Parameter{color} || {color:#333333}Description{color}\\ || {color:#333333}Default{color}\\ || {color:#333333}Required{color}\\ ||
| timeout | Timeout in milliseconds of a synchronous send. This parameter is used by the method {{sendSync}} (Exchange exchange) proposes by the CDK {{Listeners}} classes. \\
Set it to 0 for an infinite timeout. | 0 | No |
| WSDL | Path to the WSDL document describing services and operations exposed by the provided JBI endpoints defined in the SU. \\
The value of this parameter is : \\
* an URL
* a file relative to the root of the SU package \\
If not specified, a basic WSDL description is automaticaly provided by the CDK. | | No |
| wsdl-imports-download | If false, the external imports declared in the service WSDL won't be downloaded, so they won't be replaced by their content. | true | No |
| org.ow2.petals.messaging.provider.noack | Check PEtALS container document for further details. This propety activates the bypass of acknowledgment messages destinated to this SU. | \- | No |


{table-plus}
{petalslink}{include:0 CDK SU Provide Configuration}{petalslink}
\\
{center}{*}Configuration of a Service Unit to provide a service (POJO)*{center}
{table-plus:columnAttributes=,,style="text-align:center;",style="text-align:center;"}
|| Parameter\\ || Description || Default value || Required ||
| class-name \\ | The name of the Java class to expose as a service. \\ | \- \\ | Yes \\ |
{table-plus}

h3. Service Unit descriptor
The POJO class(es) and their depending libraries must be set in JAR(s) file(s) at the root directory of the POJO Service
Unit package.
The POJO JBI descriptor must contain a {{provides}} section for each POJO to expose in the JBI bus. For each provides
section, the name of the POJO class must be filled.
Here is an example:

{code:xml}
<?xml version="1.0" encoding="UTF-8"?>
<!-- JBI descriptor for PEtALS' "petals-se-pojo" (POJO), version 2.0 -->
<jbi:jbi version="1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:jbi="http://java.sun.com/xml/ns/jbi"
xmlns:pojo="http://petals.ow2.org/components/pojo/version-2.0"
xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-4.0"
xmlns:generatedNs="http://POJO/test">
<!-- Import a Service into PEtALS or Expose a PEtALS Service => use a BC. -->
<jbi:services binding-component="false">
<!-- Import a Service into PEtALS => provides a Service. -->
<jbi:provides
interface-name="generatedNs:POJO"
service-name="generatedNs:POJOService"
endpoint-name="POJOServiceEndpoint">
<!-- CDK specific elements -->
<petalsCDK:wsdl xsi:nil="true" />
<!-- Component specific elements -->
<pojo:class-name>test.SamplePojoService</pojo:class-name>
</jbi:provides>
</jbi:services>
</jbi:jbi>
{code}

h3. Service Unit content

The Service Unit has to contain the following elements, packaged in an archive:
* The META-INF/jbi.xml descriptor file, has described above.
* At least one jar containing the POJO class to expose
{code}
service-unit.zip
+ META-INF
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; - jbi.xml (as defined above)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; - mypojoclasses.jar
{code}

h1. Component Configuration
The following attributes can be set during the installation phase to configure the component, using the params element of the jbi-install-component ANT task:

{center}{*}Configuration of the component (CDK)*{center}
{table-plus:columnAttributes=,,style="text-align:center;",style="text-align:center;",style="text-align:center;"}

|| {color:#333333}Parameter{color} || {color:#333333}Description{color} || {color:#333333}Default{color} || {color:#333333}Required{color} || {color:#333333}Required{color} ||
| acceptor-pool-size | The size of the thread pool used to accept Message Exchanges from the NMR. Once a message is accepted, its processing is delegated to the processor pool thread. | 3 | Yes | Runtime |
| processor-pool-size | The size of the thread pool used to&nbsp;process Message Exchanges. Once a message is accepted, its processing is delegated to one of the thread of this pool. | 10 | Yes | Runtime |
| ignored-status | When the component receives an acknowledgement message exchange, it can skip the processing of these message according to the type of the acknowledgment. If you decide to not ignore some acknowledgement, the component listeners must take care of them. \\
\\
Accepted values : DONE_AND_ERROR_IGNORED, DONE_IGNORED, ERROR_IGNORED or NOTHING_IGNORED | DONE_AND_ERROR_IGNORED | Yes | Component |
| properties-file | Name of the file containing properties used as reference by other parameters. Parameters reference the property name in the following pattern $\{myPropertyName}. At runtime, the expression is replaced by the value of the property. \\
\\
The value of this parameter is :
* an URL
* a file relative to the PEtALS installation path
* an empty value to stipulate a non-using file | \- | No | Installation |
| external-listener-class-name | Qualified name of the class extending *AbstractExternalListener*
{note}Only for Binding Components{note} | \- | No | Component |
| jbi-listener-class-name | Qualified name of the class extending *AbstractJBIListener* | \- | Yes | Component |
| performance-notifications | Enable the performance notifications in the component. The CDK proposes to a performance notification feature to the component implementor. If you enable this feature, you must use the related
method accessible in the {{AbstractComponent}} class. | \- | No | Runtime |
| performance-step | When the performance notification feature is enabled, it is possible to define a step on the notifications. When there is an heavy message traffic, it is recommanded to increase this step to
avoid performance disturbance. | \- | No | Runtime |
{table-plus}
{petalslink}{include:0 CDK Component Configuration Table}{petalslink}

*Definition of CDK parameter scope :*

* *Component :* The parameter has been defined during the development of the component. A user of the component can not change its value.
* *Installation:* The parameter can be set during the installation of the component, by using the installation MBean (see JBI specifications for details about the installation sequence). If the parameter is optional and has not been defined during the development of the component, it is not available at installation time.
* *Runtime :* The paramater can be set during the installation of the component and during runtime. The runtime configuration can be changed using the CDK custom MBean named {{RuntimeConfiguration}}. If the parameter is optional and has not been defined during the development of the component, it is not available at installation and runtime times.

{petalslink}{include:0 CDK Parameter scope}{petalslink}

{column}
{column:width=25%}
{panel:title=Table of contents}{toc}{panel}
{panel:title=Contributors}{contributors:order=name|mode=list}{panel}
{column}
{section}