E-mail
|
Key
This line was removed.
This word was removed. This word was added.
This line was added.
|
Changes (81)
View Page History
...
{section} h1. Features
\\
This Service Engine allows to expose an annotated POJO as a JBI Service in the bus.
This Service Engine allows to expose an annotated POJO as a JBI Service in the bus.
This service engine allows to create a Petals service from an annotated Java class.
The annotations are the ones defined by the [JSR-181 specification|http://jcp.org/en/jsr/detail?id=181|http://jcp.org/en/jsr/detail?id=181], although most of the JAX-WS annotations are supported, Apache Axis2 being used by the component.
The annotations are the ones defined by the [JSR-181 specification|http://jcp.org/en/jsr/detail?id=181|http://jcp.org/en/jsr/detail?id=181], although most of the JAX-WS annotations are supported, Apache Axis2 being used by the component.
This component is based on the Petals ESB Component Development Kit and on Apache Axis2 for invocation and marshalling.
\\
If you want more details about jsr181, you can consult this the specification on the Java Community Process portal : [http://jcp.org/en/jsr/detail?id=181|http://jcp.org/en/jsr/detail?id=181]
This component can only expose services in Petals ESB.
The invocation of Petals services from the annotated class is experimental and will not be discussed here.
The invocation of Petals services from the annotated class is experimental and will not be discussed here.
{column}
{column:width=350px}
{column:width=350px}
...{section}
h1. Component Configuration
\\
The component can be configured through its JBI descriptor file like this :
\\
{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi version="1.0" xmlns:jbi="http://java.sun.com/xml/ns/jbi"
xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-4.0"
xmlns:jsr181="http://petals.ow2.org/components/jsr181/version-1.0>
The component can be configured through its JBI descriptor file like this :
\\
{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi version="1.0" xmlns:jbi="http://java.sun.com/xml/ns/jbi"
xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-4.0"
xmlns:jsr181="http://petals.ow2.org/components/jsr181/version-1.0>
h1. Creating a native Petals service
<jbi:component type="service-engine" bootstrap-class-loader-delegation="parent-first">
<jbi:identification>
<jbi:name>petals-se-jsr181</jbi:name>
<jbi:description> The jsr181 Service Engine (based on Axis2)</jbi:description>
</jbi:identification>
<jbi:component-class-name>org.ow2.petals.se.jsr181.Component</jbi:component-class-name>
<jbi:component-class-path>...</jbi:component-class-path>
<jbi:bootstrap-class-name>org.ow2.petals.se.jsr181.Bootstrap</jbi:bootstrap-class-name>
<jbi:bootstrap-class-path>...</jbi:bootstrap-class-path>
<jbi:identification>
<jbi:name>petals-se-jsr181</jbi:name>
<jbi:description> The jsr181 Service Engine (based on Axis2)</jbi:description>
</jbi:identification>
<jbi:component-class-name>org.ow2.petals.se.jsr181.Component</jbi:component-class-name>
<jbi:component-class-path>...</jbi:component-class-path>
<jbi:bootstrap-class-name>org.ow2.petals.se.jsr181.Bootstrap</jbi:bootstrap-class-name>
<jbi:bootstrap-class-path>...</jbi:bootstrap-class-path>
This section explains how to create a native Petals service, that will run on the JSR-181 component.
We speak of native service because this service is coded in Java and runs inside Petals. It does not need any container or third-party server.
We speak of native service because this service is coded in Java and runs inside Petals. It does not need any container or third-party server.
<!-- Component Development Kit Parameters -->
<petalsCDK:acceptor-pool-size>5</petalsCDK:acceptor-pool-size>
<petalsCDK:processor-pool-size>10</petalsCDK:processor-pool-size>
<petalsCDK:ignored-status>DONE_AND_ERROR_IGNORED</petalsCDK:ignored-status>
<petalsCDK:properties-file />
<petalsCDK:performance-notifications>false</petalsCDK:performance-notifications>
</jbi:component>
</jbi:jbi>{code}
\\
{note:title=Note}Actually, nothing is configurable in this JBI descriptor, so leave it as it is.{note}
{note:title=Node}The class name values in italic should not be modified by the user.
{note}
<petalsCDK:acceptor-pool-size>5</petalsCDK:acceptor-pool-size>
<petalsCDK:processor-pool-size>10</petalsCDK:processor-pool-size>
<petalsCDK:ignored-status>DONE_AND_ERROR_IGNORED</petalsCDK:ignored-status>
<petalsCDK:properties-file />
<petalsCDK:performance-notifications>false</petalsCDK:performance-notifications>
</jbi:component>
</jbi:jbi>{code}
\\
{note:title=Note}Actually, nothing is configurable in this JBI descriptor, so leave it as it is.{note}
{note:title=Node}The class name values in italic should not be modified by the user.
{note}
{include:0 CDK Component Configuration Table}
\\
{include:0 CDK Interceptor configuration for SU}
\\
{include:0 CDK Interceptor configuration for SU}
h2. Service-Unit content
A service-unit for this component must contain:
* One or several JAR files, containing at least one Java annotated class.
* A WSDL definition, that is coherent with the Java class. The best way to ensure that is to generate the WSDL from the annotated class.
* A JBI descriptor.
* One or several JAR files, containing at least one Java annotated class.
* A WSDL definition, that is coherent with the Java class. The best way to ensure that is to generate the WSDL from the annotated class.
* A JBI descriptor.
h1. Service Configuration
\\
The directory structure of a SU for the Petals-SE-Jsr81 looks like this:
The directory structure of a SU for the Petals-SE-Jsr81 looks like this:
PROVIDE SERVICE : Expose an Java Class as Service in the JBI environment.
{noformat}
su-jsr181-ServiceName-provide.zip
+ META-INF
- jbi.xml
+ Service.wsdl
+ ServiceImplementation.jar (one or several)
{noformat}
su-jsr181-ServiceName-provide.zip
+ META-INF
- jbi.xml
+ Service.wsdl
+ ServiceImplementation.jar (one or several)
{noformat}
The petals-se-jsr181 component can expose a Java Class as JBI ServiceEndpoint. This is done by deploying a Service Unit on it.
When a message is received on a JSR181 linked endpoint from the JBI environment, it is mapped to an Axis2 message and sent to the Axis2 runtime. The linked Java Class is called and the response is processed and returned to the JBI environment.
h2. The Service implementation
The native service is implemented by Java class which must be annotated with JSR-181 annotations (@WebService to be exact).
Every parameter must be a Java bean, with a public zero-argument constructor.
The important thing to take care is the way objects will be marshalled and unmarshalled, i.e. the transformation between the XML messages than come from and to Petals, and the Java objects the service implementation will deal with. This is why all your parameters should respect the Java bean conventions.
Every parameter must be a Java bean, with a public zero-argument constructor.
The important thing to take care is the way objects will be marshalled and unmarshalled, i.e. the transformation between the XML messages than come from and to Petals, and the Java objects the service implementation will deal with. This is why all your parameters should respect the Java bean conventions.
h3. Service Unit descriptor
The Service Unit descriptor file ( jbi.xml ) looks like this :
\\
{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi version="1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:jbi="http://java.sun.com/xml/ns/jbi"
xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-4.0"
xmlns:helloworld="http://petals.ow2.org/helloworld"
xmlns:jsr181="http://petals.ow2.org/components/jsr181/version-1.0">
<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi version="1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:jbi="http://java.sun.com/xml/ns/jbi"
xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-4.0"
xmlns:helloworld="http://petals.ow2.org/helloworld"
xmlns:jsr181="http://petals.ow2.org/components/jsr181/version-1.0">
The service operation will be the class methods.
You are strongly encouraged to annotate every element of the class, so that the generated WSDL is easy to read.
The WSDL should be generated from the annotated class. Tools like *wsgen* make this task easy (or you can use Petals Studio too).
You are strongly encouraged to annotate every element of the class, so that the generated WSDL is easy to read.
The WSDL should be generated from the annotated class. Tools like *wsgen* make this task easy (or you can use Petals Studio too).
<jbi:services binding-component="false">
<jbi:provides
interface-name="helloworld:Helloworld"
service-name="helloworld:HelloworldService"
endpoint-name="HelloworldEndpoint">
<petalsCDK:wsdl>Service.wsdl</petalsCDK:wsdl>
<jsr181:class>org.ow2.petals.usecase.jsr181.TestService</jsr181:class>
</jbi:provides>
</jbi:services>
</jbi:jbi>
{code}
{include:0 CDK Parameter scope}
{include:0 CDK SU Provide Configuration}
<jbi:provides
interface-name="helloworld:Helloworld"
service-name="helloworld:HelloworldService"
endpoint-name="HelloworldEndpoint">
<petalsCDK:wsdl>Service.wsdl</petalsCDK:wsdl>
<jsr181:class>org.ow2.petals.usecase.jsr181.TestService</jsr181:class>
</jbi:provides>
</jbi:services>
</jbi:jbi>
{code}
{include:0 CDK Parameter scope}
{include:0 CDK SU Provide Configuration}
\\
*Configuration of a Service Unit to provide a service (JSR181)*
{table-plus}
{table-plus}
Here is a sample annotated class:
|| Parameter \\ || Description \\ || Default \\ || Required \\ ||
| class \\ | The JSR181 annotated class which will provide the Service.This class must be available in the Service Unit class loader. | \- \\ | Yes \\ |
| class \\ | The JSR181 annotated class which will provide the Service.This class must be available in the Service Unit class loader. | \- \\ | Yes \\ |
{table-plus} {code:lang=java}
package org.ow2.petals.usecase.jsr181;
h3. Annotated class
\\
The following class is a sample of JSR181 annotated class (taken from the Petals usecase sources) :
{code}package org.ow2.petals.usecase.jsr181;
\\
The following class is a sample of JSR181 annotated class (taken from the Petals usecase sources) :
{code}package org.ow2.petals.usecase.jsr181;
import java.text.SimpleDateFormat;
import java.util.Date;
import java.util.Date;
.../**
* @author Christophe Hamerling - EBM WebSourcing
* @author chamerling - eBM WebSourcing
*
*
* NOTE : The
* @WebService parameters are not used by the component, the service name is
* defined in the service unit. Need to modify the CDK to be able to
* create the endpoint from these values...
*
*
* NOTE : The
* @WebService parameters are not used by the component, the service name is
* defined in the service unit. Need to modify the CDK to be able to
* create the endpoint from these values...
*/
@WebService(serviceName = "Hello", name = "MyService", targetNamespace = "http://petals.ow2.org")
@WebService(serviceName = "Hello", name = "MyService", targetNamespace = "http://petals.ow2.org")
.../**
* Say hello to the world !
*/
@WebMethod
@WebMethod
public String sayHello( String str ) {
System.out.println( "Hey! This is the sayHello operation." );
return "You say me told me: " + str;
}
/**
* Gets a person from its id only to test 'complex' data binding.
*
* @param id
* @param id
... */
@WebMethod
@WebMethod
public Person getPerson( int id ) {
System.out.println( "Get person " + id );
return new Person( id, "Christophe", "Hamerling", 29, "France" );
}
/**
*
*
... @WebMethod
public String getTime() {
public String getTime() {
System.out.println( "Get time" );
return new SimpleDateFormat().format( new Date( System.currentTimeMillis()));
}
/**
* NOP
* NOP
... @WebMethod
public void voidvoid() {
public void voidvoid() {
System.out.println( "The Void operation" );
}
/**
* The final WSDL operation will be 'specializedOperation'
*/
@WebMethod(operationName = "specializedOperation")
public void operation() {
@WebMethod(operationName = "specializedOperation")
public void operation() {
System.out.println( "The specialized operation" );
}
/**
*
*
... @WebMethod
public String iAmThrowingAnException() throws Exception {
public String iAmThrowingAnException() throws Exception {
System.out.println( "throw exception" );
throw new Exception( "This is a server side Exception" );
}
}{code} }
{code}
The main annotations you may use are :
* The *@WebService* annotation is *mandatory* and is used by the Axis2 engine to build the service. You can specialize the service name, target namespace and more with the annotation parameter.
* The *@WebMethod* annotation is used to delare the that the method will be seen as a JBI operation. You can specialize the operation name and more with the annotation parameters.
* The *@WebParam* annotation is used to configure an operation parameter.
More information is available on the [Apache Axis2 page : [http://ws.apache.org/axis2/|http://ws.apache.org/axis2/] . page|http://ws.apache.org/axis2/].
Before sending the JBI message to the Axis2 service, the JBI Service Engine will check if :
* If the requested operation exists. If not, an error will be returned in the JBI message exchange.
* If the requested operation exists. If not, an error will be returned in the JBI message exchange.
\\
In fact, for each annotated class, the Petals Jsr181 component creates an Axis2 service.
The messages that are received from the bus are then forwarded to the right Axis2 service the component holds.
Before forwarding the JBI message to the Axis2 service, the service engine checks that :
* The requested operation exists in the Axis2 service. If not, an error will be returned in the JBI message exchange.
In fact, for each annotated class, the Petals Jsr181 component creates an Axis2 service.
The messages that are received from the bus are then forwarded to the right Axis2 service the component holds.
Before forwarding the JBI message to the Axis2 service, the service engine checks that :
* The requested operation exists in the Axis2 service. If not, an error will be returned in the JBI message exchange.
* The JBI Message Exchange Pattern (MEP) is compatible with the target operation. For example, in the previous code snippet, an InOut MEP is not compatible with the 'voidvoid' operation and an error will would be returned in the JBI message exchange.
With the previous code samples, you can now call the _\{__[http://petals.ow2.org/helloworld]__}HelloworldService_ and operation _sayHello_ with an InOut MEP with a JBI message payload like :
{code:lang=xml}<sayHello> \\
It is not possible to only provide the Java class.
The component needs the annotated class, the associated WSDL and a JBI descriptor.
This descriptor references WSDL elements. You mandatory need to have generated the WSDL.
h2. Service-Unit descriptor
The service-unit descriptor file (jbi.xml) looks like this:
\\
{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi version="1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:jbi="http://java.sun.com/xml/ns/jbi"
xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5"
xmlns:helloworld="http://petals.ow2.org/helloworld"
xmlns:jsr181="http://petals.ow2.org/components/jsr181/version-1">
<jbi:services binding-component="false">
<jbi:provides
interface-name="helloworld:Helloworld"
service-name="helloworld:HelloworldService"
endpoint-name="HelloworldEndpoint">
<petalsCDK:wsdl>Service.wsdl</petalsCDK:wsdl>
<jsr181:class>org.ow2.petals.usecase.jsr181.TestService</jsr181:class>
</jbi:provides>
</jbi:services>
</jbi:jbi>
{code}
\\
{include:0 CDK SU Provide Configuration}
\\
*Configuration of a Service Unit to provide a service (JSR-181)*
{table-plus}
|| Parameter \\ || Description \\ || Default \\ || Required \\ ||
| class \\ | The JSR-181 annotated class which will provide the Service. This class must be available in the Service-Unit class loader. | \- \\ | Yes \\ |
{table-plus}
h2. Data-binding
The data-binding is the process that transforms XML messages into Java objects, and vice-versa.
The Jsr181 component delegates this task to Axis2.
As an example, invoking the *sayHello* operation of the previous service, with a message payload like:
{code:lang=xml}
<sayHello>
The component needs the annotated class, the associated WSDL and a JBI descriptor.
This descriptor references WSDL elements. You mandatory need to have generated the WSDL.
h2. Service-Unit descriptor
The service-unit descriptor file (jbi.xml) looks like this:
\\
{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi version="1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:jbi="http://java.sun.com/xml/ns/jbi"
xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5"
xmlns:helloworld="http://petals.ow2.org/helloworld"
xmlns:jsr181="http://petals.ow2.org/components/jsr181/version-1">
<jbi:services binding-component="false">
<jbi:provides
interface-name="helloworld:Helloworld"
service-name="helloworld:HelloworldService"
endpoint-name="HelloworldEndpoint">
<petalsCDK:wsdl>Service.wsdl</petalsCDK:wsdl>
<jsr181:class>org.ow2.petals.usecase.jsr181.TestService</jsr181:class>
</jbi:provides>
</jbi:services>
</jbi:jbi>
{code}
\\
{include:0 CDK SU Provide Configuration}
\\
*Configuration of a Service Unit to provide a service (JSR-181)*
{table-plus}
|| Parameter \\ || Description \\ || Default \\ || Required \\ ||
| class \\ | The JSR-181 annotated class which will provide the Service. This class must be available in the Service-Unit class loader. | \- \\ | Yes \\ |
{table-plus}
h2. Data-binding
The data-binding is the process that transforms XML messages into Java objects, and vice-versa.
The Jsr181 component delegates this task to Axis2.
As an example, invoking the *sayHello* operation of the previous service, with a message payload like:
{code:lang=xml}
<sayHello>
<param0>Hey!!!</param0>
</sayHello>
{code}
</sayHello>
{code}
and you will get a response like :
{code:lang=xml}<dlwmin:sayHelloResponse
\\
... would result in a response like:
{code:lang=xml}
<dlwmin:sayHelloResponse
... would result in a response like:
{code:lang=xml}
<dlwmin:sayHelloResponse
xmlns:dlwmin="http://petals.ow2.org"
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<return>You say me told me: Hey!!!</return>
</dlwmin:sayHelloResponse>
{code}
{code}
h1. Samples
Obviously, we assume the operation was invoked with the right MEP (*InOut* here).
The jsr181 service engine samples are available as use cases section. You can find them in the project sources repository.
We recommend you to check this source code to create the JSR181 class and the Service Unit.
h1. Configuring the component
h1. Limitations
\\
The component can be configured through its JBI descriptor:
\\
{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi version="1.0" xmlns:jbi="http://java.sun.com/xml/ns/jbi"
xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5"
xmlns:jsr181="http://petals.ow2.org/components/jsr181/version-1">
<jbi:component type="service-engine"
bootstrap-class-loader-delegation="parent-first">
<jbi:identification>
<jbi:name>petals-se-jsr181</jbi:name>
<jbi:description> The JSR-181 Service Engine (based on Axis2)</jbi:description>
</jbi:identification>
<jbi:component-class-name>org.ow2.petals.se.jsr181.Jsr181Se</jbi:component-class-name>
<jbi:component-class-path><jbi:path-element/></jbi:component-class-path>
<jbi:bootstrap-class-name>org.ow2.petals.se.jsr181.Jsr181Bootstrap</jbi:bootstrap-class-name>
<jbi:bootstrap-class-path><jbi:path-element/></jbi:bootstrap-class-path>
<petalsCDK:acceptor-pool-size>5</petalsCDK:acceptor-pool-size>
<petalsCDK:processor-pool-size>10</petalsCDK:processor-pool-size>
<petalsCDK:ignored-status>DONE_AND_ERROR_IGNORED</petalsCDK:ignored-status>
<petalsCDK:notifications>false</petalsCDK:notifications>
<petalsCDK:jbi-listener-class-name>org.ow2.petals.se.jsr181.Jsr181JBIListener</petalsCDK:jbi-listener-class-name>
</jbi:component>
</jbi:jbi>
{code}
The component can be configured through its JBI descriptor:
\\
{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi version="1.0" xmlns:jbi="http://java.sun.com/xml/ns/jbi"
xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5"
xmlns:jsr181="http://petals.ow2.org/components/jsr181/version-1">
<jbi:component type="service-engine"
bootstrap-class-loader-delegation="parent-first">
<jbi:identification>
<jbi:name>petals-se-jsr181</jbi:name>
<jbi:description> The JSR-181 Service Engine (based on Axis2)</jbi:description>
</jbi:identification>
<jbi:component-class-name>org.ow2.petals.se.jsr181.Jsr181Se</jbi:component-class-name>
<jbi:component-class-path><jbi:path-element/></jbi:component-class-path>
<jbi:bootstrap-class-name>org.ow2.petals.se.jsr181.Jsr181Bootstrap</jbi:bootstrap-class-name>
<jbi:bootstrap-class-path><jbi:path-element/></jbi:bootstrap-class-path>
<petalsCDK:acceptor-pool-size>5</petalsCDK:acceptor-pool-size>
<petalsCDK:processor-pool-size>10</petalsCDK:processor-pool-size>
<petalsCDK:ignored-status>DONE_AND_ERROR_IGNORED</petalsCDK:ignored-status>
<petalsCDK:notifications>false</petalsCDK:notifications>
<petalsCDK:jbi-listener-class-name>org.ow2.petals.se.jsr181.Jsr181JBIListener</petalsCDK:jbi-listener-class-name>
</jbi:component>
</jbi:jbi>
{code}
# The WSDL description is not dynamically generated from the Java class at runtime. This is due to an Axis2 and Petals ESB class loader issue. You can find an example on how to generate and include the WSDL description from the Java class with some
Maven2 plugins in the usecases related to this component.
# The JBI Component Context is not available on the POJO so you can not access to the JBI Delivery Channel to do some light orchestration. This feature will be added soon \!
Maven2 plugins in the usecases related to this component.
# The JBI Component Context is not available on the POJO so you can not access to the JBI Delivery Channel to do some light orchestration. This feature will be added soon \!
\\
{include:0 CDK Component Configuration Table}
\\
This component has no specific parameter.
{include:0 CDK Component Configuration Table}
\\
This component has no specific parameter.