h2. Service Unit content
\\
The service unit must contain a JAR archive including the EJB Interface (and EJB Home Interface for a 2.x EJB) and all specific Java classes used by this interface.
It is also highly recommended to provide a WSDL description of your EJB interface. This WSDL description will be used as Service Description for the JBI Endpoint linked to your EJB.
The directory structure of a SU for the BC-EJB must look like this :
{noformat}my-su-ejb.zip
+ META-INF
- jbi.xml
- my-ejb-wsdl-description.wsdl
- my-ejb.jar
- my-ejb-dependency1.jar
- my-ejb-dependency2.jar{noformat}
h1. Packaging EJB container RMI client libraries
Since the petals-bc-ejb is a generic binding component that allows to call Enterprise Java Beans running on different kind of application servers, you must add your application specific RMI client libraries to the component classpath. There are three solutions to add the libraries to do so :
* add the libraries directly in the component classpath (bad)
* add the libraries to each deployed service unit (average)
* add the libraries to a shared library deployed before component startup (good)
By default this component uses a shared library called "petals-sl-ejb" which must contains the RMI client libraries of the EJB targeted EJB container with its JEE EJB specification.
A shared library archive may look like this :
{noformat}petals-sl-ejb.zip
+ META-INF
- jbi.xml
- my-ejb-container-rmi-client.jar
- my-ejb-container-rmi-client-dependency1.jar
- my-ejb-container-rmi-client-dependency2.jar
- my-ejb-container-ejb-specification.jar{noformat}
Adding jar files to the archive is not sufficient. Each jar contained by the shared library must be declared within its JBI descriptor.
Here is an exemple of such files (jbi.xml file) :
{code:lang=xml}<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:petals="http://petals.ow2.org/extensions"
xmlns:jbi="http://java.sun.com/xml/ns/jbi" version="1.0">
<jbi:shared-library class-loader-delegation="self-first" version="my-ejb-container-versionXYZ">
<jbi:identification>
<jbi:name>petals-sl-ejb</jbi:name>
<jbi:description>SharedLibrary EJB for my-ejb-container-versionXYZ</jbi:description>
</jbi:identification>
<jbi:shared-library-class-path>
<jbi:path-element>my-ejb-container-rmi-client.jar</jbi:path-element>
<jbi:path-element>my-ejb-container-rmi-client-dependency1.jar</jbi:path-element>
<jbi:path-element>my-ejb-container-rmi-client-dependency2.jar</jbi:path-element>
<jbi:path-element>my-ejb-container-ejb-specification.jar</jbi:path-element>
</jbi:shared-library-class-path>
</jbi:shared-library>
</jbi:jbi>{code}
Finally, to add this shared library to the component classpath you must add the following section to the JBI descriptor of the component (here with the default shared library for the EJB component) just after the end of the "bootstrap-class-path" element:
{code:lang=xml}<shared-library>petals-sl-ejb</shared-library>{code}
h1. XML to Java binding
Since the JBI message payload is a XML message, the component must provide a way to transform Java objects into XML (marshalling) an XML to Java objects (unmarshalling). The message payload containing an EJB call is unmarshalled to Java objects that will be used as method parameters for the EJB call through RMI. The EJB response is intercepted by the component and then marshalled to an XML payload.
This marshalling / unmarshalling process is provided by the PEtALS-JAXB-Databinding library. This library uses a WSDL file (generated from your service class with Apache-CXF or OW2-Java2EasyWSDL from the EasyWSDL toolbox) to bind Java classes to XML tags.
h2. Request message
The incoming JBI message payload is unmarshalled by JAXB using the WSDL provided in the service unit. XML messages are transformed to Java Objects which are used to perform a RMI call on the EJB.
{code:lang=xml|title=An EJB call request which conforms to the provided WSDL (as generated by soapui, when the EJB is exposed outside the bus)}<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:q0="http://application.localisation.watersupply.petals.ow2.org/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<q0:getBureauDistributeurInfoByCommuneId>
<q0:arg0>452</q0:arg0>
</q0:getBureauDistributeurInfoByCommuneId>
</soapenv:Body>
</soapenv:Envelope>{code}
h2. Response message
The EJB response is intercepted by the component and then marshalled by JAXB conforming to the provided WSDL.
{code:lang=xml|title=An EJB response marshalled conforming to the WSDL (as received by soapui, when the EJB is exposed outside the bus)}<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<getBureauDistributeurInfoByCommuneIdResponse
xmlns="http://businessinfo.localisation.watersupply.petals.ow2.org"
xmlns:ns2="http://application.localisation.watersupply.petals.ow2.org/">
<ns2:return>
<BureauDistributeurInfo>
<code>code 0</code>
<id>452</id>
<libelle>libelle 0</libelle>
</BureauDistributeurInfo>
<BureauDistributeurInfo>
<code>code 2</code>
<id>452</id>
<libelle>libelle 2</libelle>
</BureauDistributeurInfo>
<BureauDistributeurInfo>
<code>code 3</code>
<id>452</id>
<libelle>libelle 3</libelle>
</BureauDistributeurInfo>
</ns2:return>
</getBureauDistributeurInfoByCommuneIdResponse>
</soapenv:Body>
</soapenv:Envelope>{code}
h1. JAAS authentication
The EJB binding component is JAAS enabled : it can handle security subjects from your JBI platform to your application server to perform authentication and role based EJB method restrictions.
{note:title=Caution}When using JAAS (or any security feature) you MUST ensure that all the JVM are compliant. In other words, the JVM running PEtALS MUST be fully compliant with the one running your application server. Both JVM must came from the same vendor, using the same kind of architecture (32 bits or 64 bits), cryptography libraries and so on.{note}
h2. JAAS configuration
JAAS authentication is based on a configuration file which specifies all the login modules to be used during the authentication process, as shown below.
{code}jonas {
// Login Module to use for the example jaasclient.
//First, use a LoginModule for the authentication
org.ow2.petals.bc.ejb.security.WSSUserPasswordLoginModule required
org.ow2.petals.users="users.properties"
org.ow2.petals.roles="roles.properties";
// Use the login module to propagate security to the JOnAS server
// globalCtx is set to true in order to set the security context
// for all the threads of the client container instead of only
// on the current thread.
// Useful with multithread applications (like Swing Clients)
org.objectweb.jonas.security.auth.spi.ClientLoginModule required globalCtx="true";
};{code}
In this file, only one configuration “jonas” (which is the configuration identifier) is defined. You can define several configurations in the same JAAS configuration file.
{note}Petals ESB must be configured to use this file as default JAAS configuration file at startup. To do so, you must set up the JVM property “java.security.autho.login.config” to the absolute path of your JAAS configuration file.
Assuming that “PETALS_HOME” is an environment variable pointing onto your PEtALS installation folder and your JAAS configuration file is called “jaas.conf” and resides in your Petals installation
folder, you can set this JVM property by adding the following option to the Petals startup command \--Djava.security.auth.login.config==”$PETALS_HOME/jaas.conf”.{note}
h2. Login module configuration
In your JAAS configuration file you can specify a list of LoginModule, which will be used for the whole authentication process.
{note}You can write your own LoginModule by implementing the javax.security.auth.spi.LoginModule interface. To do so feel free to read the JAAS LoginModule developer’s guide.{note}
For instance in the previous JAAS configuration file, two LoginModule were defined. The first one (org.ow2.petals.bc.ejb.security.WSSUserPasswordLoginModule) is used to make the authentication (based on user / password informations) and the second one, (org.objectweb.jonas.security.auth.spi.ClientLoginModule) is used to propagate the LoginContext to the application server (JOnAS).
{note}LoginModule classes must be included in the service unit.{note}
h2. JAAS resources
* *Sun.* _JAAS Reference_, available online at : [http://java.sun.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html|http://java.sun.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html]
* *Sun.* _JAAS Tutorials_, available online at : [http://java.sun.com/javase/6/docs/technotes/guides/security/jaas/tutorials/|http://java.sun.com/javase/6/docs/technotes/guides/security/jaas/tutorials/]
* *Sun.* _LoginModule Developer's Guide_, available online at : [http://java.sun.com/javase/6/docs/technotes/guides/security/jaas/JAASLMDevGuide.html|http://java.sun.com/javase/6/docs/technotes/guides/security/jaas/JAASLMDevGuide.html]
* *Bhattacharjee Rahul.* _Authentication using JAAS_, available online at : [http://www.javaranch.com/journal/2008/04/Journal200804.jsp#a6|http://www.javaranch.com/journal/2008/04/Journal200804.jsp#a6]
E-mail
...