{section}
{column}

h1. Exposing a Java class as a POJO service (Provides mode)

h2. Usage

The POJO that you want to develop must follow certain constraints :
* 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 Service Unit.
* if a {{public setDeliveryChannel(DeliveryChannel channel)}} setter method is defined, the component set its {{DeliveryChannel}} instance with this method at the initialization of the Service Unit.
* if a {{public setJBIListener(AbstractJBIListener jbiListener)}} setter method is defined, the component set its {{JBIListener}} instance with this method at the initialization of the Service Unit.
* if a {{public setLogger(Logger logger)}} setter method is defined, the component set its {{Logger instance}} with this method at the initialization of the Service Unit.
* if a {{public void init()}} method is defined, the component invoke it at the initialization of the Service Unit.

h3. Process a service in the synchronous way

A sample class following the above rules for processing service in the synchronous way:
{code:java}
package test;
import java.util.logging.Level;
[...]
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 MessagingException {
[...]
jbiListener.sendSync(anotherExchange);
[...]
return true;
}

{code}

The method {{onExchange(Exchange exchange)}} is invoked when an exchange is received from the component that is addressed to the current POJO endpoint.
The POJO must process the service in that method.
The POJO can invoke any 'sub-service' during its processing by synchronous invocations using the {{jbiListener}} instance.
If the POJO service must reply with a message {{OUT}} or {{FAULT}}, according to the MEP, the method must build and set the message to the current exchange.
Then, the method musts return {{true}} to delegate the effective send back of the response or acknowledgment (according to the MEP) to the CDK.
The exceptions should be handled properly during the processing of the method, and set accordingly as error or fault to the exchange.
However, mishandled exceptions will be handled by the CDK as generic exceptions.

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

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

{table-plus}

{table-plus}

{table-plus}

{table-plus}

{table-plus}

{table-plus}

{table-plus}

{table-plus}

{table-plus}

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;"}

{table-plus}

{table-plus}

{table-plus}

{table-plus}

{table-plus}






|| Parameter \\ || Description || Default value || Required ||
| class-name \\ | The name of the Java class to expose as a service. \\ | \- \\ | Yes \\ |
{table-plus}

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}

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}

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;"}

{table-plus}

{table-plus}

{table-plus}

| 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}

{table-plus}

{table-plus}

{table-plus}

{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}