Component Framework 3.0
This guide is a creation guide for JBI Components with the Component Framework (CF)
PEtALS Team FABRE Olivier
BARTHE Anne-Marie
- September 2007 -
(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/
Component Framework
Table of Contents
Component Development Kit .................................................................................................................... 5 1. How to create a ServiceEngine (sample : XSLT component) ? ..................................................................... 6 1.1. Classes to implement ................................................................................................................. 6 1.1.1. Main class of the component ............................................................................................ 6 1.1.2. JBI messages processing class .......................................................................................... 6 1.2. Component's configuration .......................................................................................................... 7 1.3. Services activation .................................................................................................................... 8 2. How to create a BindingComponent (sample : Mail component) ? ................................................................ 9 2.1. Classes to implement ................................................................................................................. 9 2.1.1. Main class of the component ............................................................................................ 9 2.1.2. JBI messages' processing class .......................................................................................... 9 2.1.3. External messages' processing class .................................................................................. 11 2.2. Component's configuration ........................................................................................................ 12 2.3. Services' activation .................................................................................................................. 13 2.4. Consuming services ................................................................................................................. 13 3. Go one step further... ......................................................................................................................... 15 3.1. Extensions of the deployment descriptors (jbi.xml file) ................................................................... 15 3.1.1. Component's extensions ................................................................................................. 15 3.1.2. Extensions of the ServiceUnits' "provides" or "consumes" fields ............................................ 16 3.2. Advanced attributes for Component's configuration ....................................................................... 17 3.3. Advanced attributes for ServiceUnit's configuration ....................................................................... 17 3.4. Exchange' interceptors .............................................................................................................. 17 3.4.1. Definition .................................................................................................................... 17 3.4.2. Interceptor's implementation ........................................................................................... 17 3.5. Configuration .......................................................................................................................... 18 3.5.1. Interceptor's configuration at Component's level ................................................................. 18 3.5.2. Interceptor's configuration at ServiceUnit's level ................................................................. 19 3.6. Benchmark notifications ........................................................................................................... 19 3.6.1. Introduction ................................................................................................................. 19 3.6.2. Use case ...................................................................................................................... 19 3.6.3. Client's approach .......................................................................................................... 21 3.6.4. Development side ......................................................................................................... 22 3.7. Exchange's sending in the JBI container ...................................................................................... 23 3.7.1. Synchronous send() with timeout ..................................................................................... 23 3.7.2. Synchronous send() without timeout ................................................................................. 23 3.7.3. Asynchronous send() without answer's synchrony ............................................................... 23 3.7.4. Asynchronous send() with answer's synchrony ................................................................... 23
Component Framework
2
Component Framework
List of Figures
3.1. Performance notification RECEIVING_FROM_NMR/SENDING_TO_OUTSIDE ....................................... 3.2. Performance notification RECEIVING_FROM_OUTSIDE/SENDING_TO_NMR ....................................... 3.3. MBeans of performance's notifications of the BC Soap .......................................................................... 3.4. MBeans of performance's notifications of the BC Soap .......................................................................... 3.5. Receiving performance's notifications through the PEtALS Eclipse plugin ................................................. 3.6. Receiving performance's notifications through the JConsole .................................................................... 20 20 21 21 22 22
Component Framework
3
Component Framework
List of Tables
3.1. Performance notification format ......................................................................................................... 21
Component Framework
4
Component Development Kit
Component Development Kit
The Component Development Kit (CDK) is a JBI component development framework. It comes in a set of classes making easier the interfacing with the JBI container, notably in supporting the use of the several aspects, as described in Chapter 7 of the JBI specification (Component Framework). It gives abstract classes to extend according the component type (Binding Component or Service Engine). It gives more utilitarian classes making easier MessagesExchanges takedown or existing extensions into ServiceUnits deployment descriptors handling. Lastly, it adds the concept of "interceptors" which lets the component making preprocessing or post-processing on MessagesExchanges.
Component Framework
5
How to create a ServiceEngine (sample : XSLT component) ?
Chapter 1. How to create a ServiceEngine (sample : XSLT component) ?
The XSLT component is a good example of ServiceEngine. It listens messages coming from the JBI container and applies an XSL conversion (beforehand defined with a ServiceUnit) on their content.
1.1. Classes to implement
1.1.1. Main class of the component
The first class to implement is the main class of example shows how to create a ServiceEngine. This class org.objectweb.petals.component.framework.se.AbstractServiceEngine. the component. The following must extend the abstract class
This class is used by the container during the init, start, stop or shutdown phases of the component. The developer can act on each of these phases : he implementes respectively the methods doInit(), doStart(), doStop() or doShutdown(). The developer can access to essential parts of the component like the ComponentContext (running component context), the DeliveryChannel (communication's API with the JBI bus), the Logger or the ComponentProperties (all component properties are existing into the deployment descriptor (jbi.xml) extensions). These various parts are available through the following methods : getContext(), getChannel(), getLogger() and getComponentConfiguration(). The XSLT component doesn't need a specific initialization, the AbstractServiceEngine class implementation is very easy :
package org.objectweb.petals.engine.xslt; import org.objectweb.petals.component.framework.se.AbstractServiceEngine; public class XsltEngine extends AbstractServiceEngine { }
1.1.2. JBI messages processing class
The second class to implement is the class which enables the component processing messages coming from the JBI container. This class must extend the abstract class org.objectweb.petals.component.framework.listener.AbstractJBIListener. For each message coming from the JBI container, the onJBIMessage(Exchange exchange) is called. The developer can process on the message exchange through this method (the xsl processing for the sample component). We can see an implementation sample of this class for the XSLT component below (it is a shortened version for our technical document needs) :
protected void onJBIMessage(Exchange exchange) { try { // Get in Message content Source inContent = exchange.getInMessageContentAsSource(); // Retrieve CDK extensions Extensions extensions = new Extensions(getProvides() .getExtensions()); // Retrieve XLS style sheet path String xslPath = retrieveXSLPath(exchange, extensions); // Apply transformation Source outContent = xslt.transform(inContent, xslPath); // Set the result to return
Component Framework
6
How to create a ServiceEngine (sample : XSLT component) ?
exchange.setOutMessageContent(outContent); } catch (BusinessException e1) { try { exchange.setFault(e1); } catch (MessagingException e) { getLogger().log(Level.SEVERE, "Can't return fault to consumer", e); } } catch (MessagingException e) { exchange.setError(e); } }
This method uses utilitarian classes and methods provided by the CDK. A sample of this utilitarian class : org.objectweb.petals.component.framework.util.ExchangeImpl. This class implements an interface similar to javax.jbi.messaging.MessageExchange, but also adds utilitarian methods and extra controls. This makes easier working with the main components of a MessageExchange, like the in-message content (getInMessageContentAsSource()), the out-message content (setOutMessageContent(outContent)), the faults (setFault(exception)) and the errors (setError(exception))... The JBIListener provides methods allowing access to the ComponentContext (getComponentContext()), the DeliveryChannel (getdeliveryChannel()), the Logger (getLogger()) and the Component (getComponent()). It gives also access to the Provides block (Java representation of the provides field of a service unit) matching the targeted endpoint of the processing message exchange. The method which allows access to this Provides object is getProvides().
1.2. Component's configuration
The component configuration is made into its deployment descriptor (file META-INF/jbi.xml into the component archive file), according its specification. In this file, we can find the description of : the main component class ("component-classname" tag), the bootstrap component class ("bootstrap-class-name" tag), the component classpath used for running the component ("component-class-path" tag) and the classpath used for the component's bootstrapping ("bootstrap-class-path" tag). The specific part of the CDK's configuration is composed of extensions into the component's description ("extensions:extensions" tag). Here is a sample of the deployment descriptor for the XSLT component :
petals-engine-xslt A Xslt Service Engine org.objectweb.petals.engine.xslt.XsltEngine petals-se-xslt-1.4-SNAPSHOT.jar ... org.objectweb.petals.component.framework.DefaultBootstrap petals-se-xslt-1.4-SNAPSHOT.jar ... org.objectweb.petals.engine.xslt.listener.JBIListener
Component Framework
7
How to create a ServiceEngine (sample : XSLT component) ?
In the case of a Service Engine, only one extension is required : jbi-listener-class-name. It is the complete name of the JBI message processing class, as defined in the previous chapters.
1.3. Services activation
A ServiceEngine is available only if it publishes its services as ServiceEndpoints. A ServiceEndpoint publishes a service provided by the ServiceEngine into the JBI bus. A sample of service provided by the XSLT component is the processing of an incoming XML message into an outgoing XML message, according the rules described in a processing XSL sheet. The endpoint activation takes part during the ServiceUnit bootstrap (call of the ServiceUnitManager component method start(String suName)) containing the "provides" fields. Here is a sample of a ServiceUnit (SU) activating an endpoint for the XSLT component :
test.xsl
At the end of this SU's bootstrapping, an endpoint is activated in the container for the XSLT component. This endpoint's interface name, service name and endpoint name get the values defined respectively in the attributes interface-name, service-name and endpoint-name of the "provides" tag. The "provides" tag includes an "extensions" tag, which matches with PEtALS' extensions. PEtALS' extensions allow to specify component's configuration information for a fixed endpoint. In the case of the XSLT component, an extension is used to specify the relative path of the XSL processing sheet into the SU's archive file.
Component Framework
8
How to create a BindingComponent (sample : Mail component) ?
Chapter 2. How to create a BindingComponent (sample : Mail component) ?
The Mail component will be our implementation sample of a BindingComponent based on the CDK. It allows the emails' exchange between an email server and the JBI container.
2.1. Classes to implement
2.1.1. Main class of the component
Likewise for a ServiceEngine, the first class to implement is the Component class. The chosen sample shows how to create a BindingComponent. In this case, the class to deploy is the org.objectweb.petals.component.framework.se.AbstractBindingComponent class. This class inherits of a common class of the AbstractServiceEngine class. So it is used for each step of the component's lifecycle and gives access to the ComponentContext, the DeliveryChannel, the Logger and the component's settings. The Mail component needs three utilitarian classes to process incoming and outgoing emails and to manage email server connections. These three classes are instantiated at the component's bootstrapping and are used during the component's running. Here is the Mail Component class' implementation :
public class MailBCImpl extends AbstractBindingComponent { @Override protected void doInit() throws JBIException { this.sessionDescriptorBuilder = new SessionDescriptorBuilder( getLogger()); this.mimeMessageManager = new MimeMessageManager(getLogger(), this); this.mailSessionManager = new MailSessionManager(getLogger()); } public MailSessionManager getMailSessionManager() { return mailSessionManager; } public MimeMessageManager getMimeMessageManager() { return mimeMessageManager; } public SessionDescriptorBuilder getSessionDescriptorBuilder() { return sessionDescriptorBuilder; } }
The doInit() method, which is overloaded here to instanciate the three utilitarian classes, is called at the end of the component's bootstrapping, allowing the developer to make specific bootsrapping tasks. Likewise for a ServiceEngine, the developer can act on the bootstrappping (doStart()), stop (doStop()) or shutdown (doShutdown()).
2.1.2. JBI messages' processing class
Likewise for the ServiceEngines, the second class to implement is the component processing messages coming from the JBI container. org.objectweb.petals.component.framework.listener.AbstractJBIListener. the class which enables It is the abstract class
In the case of a BindingComponent, this class' role is to forward JBI messages to external services of a JBI container. In the case of the Mail component, the JBIListener has to process the exchange JBI messages into emails and send them through the SMTP protocol to an email server. Here is the simplified implemention of the JBIListener, in the case of the Mail component :
Component Framework
9
How to create a BindingComponent (sample : Mail component) ?
public class MailBCJBIListener extends AbstractJBIListener { protected MailSessionManager mailSessionManager; protected MimeMessageManager mimeMessageManager; protected SessionDescriptorBuilder sessionDescriptorBuilder; @Override protected void init() { this.mimeMessageManager = ((MailBCImpl) getComponent()) .getMimeMessageManager(); this.mailSessionManager = ((MailBCImpl) getComponent()) .getMailSessionManager(); this.sessionDescriptorBuilder = ((MailBCImpl) getComponent()) .getSessionDescriptorBuilder(); } public void onJBIMessage(Exchange exchange) { if (!exchange.isInOnlyPattern()) { try { exchange.setFault(new PEtALSCFException( "MailBC can only handle InOnly message exchanges")); } catch (MessagingException e) { getLogger().log(Level.SEVERE, "Can't return fault to consumer", e); } } else { try { Extensions extensions = new Extensions(getProvides() .getExtensions()); // Build a mail session descriptor from the given address (URI) SessionDescriptor sessionDescriptor = sessionDescriptorBuilder .build(exchange, extensions); // Build the destination address InternetAddress internetAddress = new InternetAddress( sessionDescriptor.getToAddress()); // Build the mail session Session session = mailSessionManager .createSessionPropertiesFromDescriptor(sessionDescriptor); // Create a mail message with the incoming jbi message MimeMessage mimeMessage = mimeMessageManager .mapNormalizedMessageToMimeMessage(session, internetAddress, exchange.getInMessage()); // Send this mail mailSessionManager.sendMail(mimeMessage, sessionDescriptor, session); } catch (Throwable e) { try { exchange.setFault(new Exception(e)); } catch (MessagingException e1) { getLogger().log(Level.SEVERE, "Can't return fault to consumer", e); } } } } }
In addition to the onJBIMessage() method (required), the JBIListener provides an init() method, which allows the developer to position an initial context of operation for his JBIListener. This method is called instantly after the JBIListener's instantiation. The JBIListeners are instantiated by the CDK during the component's bootstrapping (call of the method start() on the component's main class).
Component Framework
10
How to create a BindingComponent (sample : Mail component) ?
2.1.3. External messages' processing class
The third class type to implement is org.objectweb.petals.component.framework.listener.AbstractExternalListener. This class type is specific to the BindingComponent. It is used to process messages coming from the service consumer out of JBI container. Thanks to these class types, the BindingComponent enables the access to the container's service through several protocols (HTTP, JMS, ...). When a ServiceUnit, which has fields "consumes", starts, the CDK instantiates an ExternalListener for each defined element "consumes". In the case of the Mail component the ExternalListener starts up a scheduler. This last one is querying at regular intervals an external email server which directions (address, port, protocol, ...) are specified in the "consumes"' extensions. If it finds new messages, it handles and process them into Exchange. Then it send them to the targeted JBI service. Here is the code of this ExternalListener :
public class MailBCExternalListener extends AbstractExternalListener { private Timer t; protected MailSessionManager mailSessionManager; protected SessionDescriptorBuilder sessionDescriptorBuilder; protected MimeMessageManager mimeMessageManager; @Override protected void init() { this.mailSessionManager = ((MailBCImpl) getComponent()) .getMailSessionManager(); this.sessionDescriptorBuilder = ((MailBCImpl) getComponent()) .getSessionDescriptorBuilder(); this.mimeMessageManager = ((MailBCImpl) getComponent()) .getMimeMessageManager(); } @Override protected void start() throws PEtALSCFException { // Extract session information from SU extensions Extensions extensions = new Extensions(getConsumes() .getExtensions()); SessionDescriptor sessionDescriptor = sessionDescriptorBuilder.build( null, extensions); // Create and register the listener MailBCExternalScheduler listener = null; t = new Timer(); listener = new MailBCExternalScheduler(getLogger(), this, sessionDescriptor, mailSessionManager, mimeMessageManager); // Start listening for new mails t .schedule(listener, 0, Integer.parseInt(sessionDescriptor .getPeriod())); } @Override protected void stop() throws PEtALSCFException { t.cancel(); } }
Likewise for the JBIListener, a method init() allows the developer to initialize the ExternalListener. The method getConsumes() allows access to the field "consumes" (as a Java object), which is at the beginning of the Listener creation. The implementation of the methods start() and stop() is required. These methods are respectively called during the bootstrapping or the stop of a ServiceUnit.
Component Framework
11
How to create a BindingComponent (sample : Mail component) ?
The ExternalListener provides methods allowing the access to the ComponentContext (getComponentContext()), the DeliveryChannel (getdeliveryChannel()), the Logger (getLogger()) and the Component (getComponent()). The Scheduler (MailBCExternalScheduler), instantiated during the "start()" of the Listener, send to the JBI container the emails processed into Exchanges. For this, it uses utilitarian methods provided by the Listeners. These methods sendXXX() enable sending messages in the synchronous or asynchronous way. These several methods are described in the next chapter "Go one step further..." (see below). Here is a sample of code using a method sendSync() without timeout :
protected void process(Message message) { try { // Transform mail in MessageExchange MessageExchange exchange = processor.process(message); if (exchange != null) { // Send exchange to the JBI Container externalListener.sendSync(new ExchangeImpl(exchange)); } } catch (JBIException e) { String msg = "Error processing a mail : " + message.getMessageNumber(); logError(msg, e); } finally { try { message.setFlag(Flag.DELETED, true); } catch (MessagingException e) { logWarning("Mail message can't be marked as deleted. " + "It will not be deleted from the store", e); } } }
2.2. Component's configuration
The BindingComponent's configuration is similar to a ServiceEngine's one, excepted an extra attribute : external-listenerclass-name. It is the qualified name of the processing class of external messages, as described in the previous chapters. Here is a sample of a deployment descriptor for the Mail component :
petals-binding-mail Mail binding component org.objectweb.petals.binding.mail.MailBCImpl petals-bc-mail-1.3-SNAPSHOT.jar ... org.objectweb.petals.component.framework.DefaultBootstrap petals-bc-mail-1.3-SNAPSHOT.jar org.objectweb.petals.binding.mail.listeners.MailBCJBIListener org.objectweb.petals.binding.mail.listeners.MailBCExternalListener
Component Framework
12
How to create a BindingComponent (sample : Mail component) ?
2.3. Services' activation
Activate services for a BindingComponent is similar to ServiceEngines' one. A service sample provided by the Mail component is the email sending to a specified address. Here is a sample of ServiceUnit "provides" for the Mail component :
name="scheme">smtp name="hostname">www.ebmwebsourcing.org name="username">test name="from">test@ebmwebsourcing.com name="to">test@ebmwebsourcing.com
This SU sets going an endpoint which publishes the email sending service to the address specified in the extensions (field "to"), using the specified email server (field "hostname").
2.4. Consuming services
Likewise the services' activation, the services' consuming is configured by the ServiceUnit deployment. Like the field "provides" previously described, the SU contents a field "consumes". During the bootstrapping of a SU containing a field "consumes", an ExternalListener is bootstrapped. It listens the queries coming from external consumers and send them to the targeted service, defined by the attributes of the "consumes" tag. Here is a sample of a "consumes" ServiceUnit for the Mail component :
pop3 192.168.5.2
Component Framework
13
How to create a BindingComponent (sample : Mail component) ?
test petals
In the case of the Mail component, the ExternalListener controls the email directory (by default the INBOX directory) on the server specified into the extensions (field "hostname") for the specified user (field "username"). The existing emails in this directory are processed into Exchanges et are sent to the endpoint specified into the attributes of the field "consumes" (here is an Helloworld component's endpoint).
Component Framework
14
Go one step further...
Chapter 3. Go one step further...
The previous chapters describe the basis of the CDK based component's creation. The CDK provides several ways of component's configuration and optimization like the threads' management, MessageExchange's interceptors, ...
3.1. Extensions of the deployment descriptors (jbi.xml file)
The JBI specification allows the developer to add extensions (XML tags) into the deployment descriptors of the SharedLibraries, ServiceUnits, ServiceAssemblies and Components. Here is a sample of a ServiceUnit :
name="scheme">smtp name="hostname">www.ebmwebsourcing.org name="username">test name="from">test@ebmwebsourcing.com name="to">test@ebmwebsourcing.com
PEtALS offers, through the CDK, an utilitarian class which makes easier the use of these extensions in the components. The Petals' accepted extensions are key-value type extensions, the key as the name of the "name" attribute of the "param" tag and the value as the content between the tags. As an example :
test---> key = username and value = test
In order to make PEtALS able to accept these extensions, they must be located between two tags (one openning, one closing), having this namespace :
"http://petals.objectweb.org/extensions"
3.1.1. Component's extensions
3.1.1.1. Where are they located in the deployment descriptor ?
They must be located right before the closing tag. Here is a sample of extensions, in a component's deployment descriptor :
petals-engine-xslt A Xslt Service Engine
Component Framework
15
Go one step further...
org.objectweb.petals.engine.xslt.XsltEngine petals-se-xslt-1.4-SNAPSHOT.jar ... org.objectweb.petals.component.framework.DefaultBootstrap petals-se-xslt-1.4-SNAPSHOT.jar ... 15 org.objectweb.petals.engine.xslt.listener.JBIListener
3.1.1.2. How to access them in the component ?
The extensions of the component's deployment descriptor are available from the component main class, thanks to the getComponentConfiguration() method. This method returns a ComponentConfiguration object, which has getters for all the component's standard properties (pool-size, ignored-status,...). The component's specific properties (component's specific extensions) are available from the ComponentConfiguration, through the getProperties() method. They are under the guise of a a java.util.Properties object.
3.1.2. Extensions of the ServiceUnits' "provides" or "consumes" fields
3.1.2.1. Where are they located in the deployment's descriptor ?
They must be located right before the closing or tag. Here is a sample of extensions in a deployment descriptor of a ServiceUnit (for the "consumes" field) :
name="scheme">pop3 name="hostname">192.168.5.2 name="username">test name="password">petals
Component Framework
16
Go one step further...
3.1.2.2. How to access them in the component ?
The "provides" and "consumes" fields' extensions are available in the two kinds of Listeners (JBIListener or ExternalListener), thanks to the getExtensions() method. Each Listener is linked to the runtime at a "provides" or "consumes" fields. An ExternalListener is only linked to a "consumes" field. However, a JBIListener can be linked to a "provides" in the case of a service provider processing, or linked to de "consumes" in the case of a consumer (answer to a service calling) processing. The getExtensions() method allows the developer to access directly to the extensions which are relevant for the message to process. And this without making a difference between a consumer or a provider case. The extensions are under the guise of an Extension object. It offers a getPetalsExtensions() method which returns a java.util.Properties object (which contains the whole keys-values). The values of the Petals' extensions are available singly from the following methods : getValue(String key, String defaultValue) and getValue(String key). At last, the Extensions object offers a getDocumentFragment() method which returns an org.w3c.dom.DocumentFragment object, which contains the whole extensions (Petals' and non-Petals' ones ), as a DOM tree.
3.2. Advanced attributes for Component's configuration
The CDK offers common configuration attributes for all the components. These attributes have to be specified in the existing extensions in its deployement descriptor (jbi.xml file) :
3.3. Advanced attributes for ServiceUnit's configuration
The CDK offers common configuration attributes for all the Service Units. These attributes have to be specified in the extensions of the existing "provides" or "consumes" fields in the SU's deployment descriptor (jbi.xml file) : The org.objectweb.petals.routing.strategy, org.objectweb.petals.transport.compress, org.objectweb.petals.messaging.noack and org.objectweb.petals.transport.qos attributes are automatically located by the CDK during the message sending with the send XXX() methods of the Listeners.
3.4. Exchange' interceptors
3.4.1. Definition
An interceptor allows processing a MessageExchange as an Exchange : • At the sending of an Exchange to the provider. This is the last operation done before the effective sending of the message. • At the receiving of an Exchange. This is the first operation done at the receiving of the message.
3.4.2. Interceptor's implementation
An interceptor must extend the abstract class org.objectweb.petals.component.framework.interceptor.Interceptor. A sample of an interceptor which prints the MessageExchange's ID would be :
public class MessageInfoPrintInterceptor extends Interceptor { @Override public void handleMessageAccept(Exchange exchange,
Component Framework
17
Go one step further...
ServiceUnitExtensibleElement consumeProvide, Map parameters) { System.out.println(exchange.getExchangeId()); } @Override public void handleMessageSent(Exchange exchange, ServiceUnitExtensibleElement consumeProvide, Map parameters) { System.out.println(exchange.getExchangeId()); }
Both implemented methods above allow the Exchange's interception : • When receiving a message, the handleMessageAccept method is invoked. • When sending a message, the handleMessageSent method is invoked. Both methods have the same definition, so we can access to : • The Exchange. • The parent object Consumes/Provides. • The extra attributes defined for each extension block (see following chapter). The abstract class Interceptor provides a set of attributes defined at its bootstrapping. Thus we can access to, during an interception : • The component (AbstractComponent). • A properties map, as a key-value form. These properties are extracted from the jbi.xml descriptor of the component (see following chapter).
3.5. Configuration
3.5.1. Interceptor's configuration at Component's level
The interceptors to use in the component are defined at the level of the extensions block of the jbi.xml component descriptor. The syntax is the following :
echo component parameter 1 echo component parameter 2 info component parameter 1 info component parameter 2
elements are the configuration attributes that the developer can define at the component's level. At the runtime, these attributes are available at the interceptor's level.
The yyy
Component Framework
18
Go one step further...
3.5.2. Interceptor's configuration at ServiceUnit's level
The interceptors defined at component level can be used at ServiceUnit's level. To use an interceptor, it has to be configured at the extension block of a ServiceUnit in the following way :
A B
The yyy elements are configuration parameters that the developer can defined at ServiceUnit's level. During the runtime, these attributes are available in the map parameters of the interception method. This mechanism allows a more accurate configuration of the interceptors. Please take note that the parameters at ServiceUnit's level are of utmost importance than the Component's ones. If the developer defines these attributes at ServiceUnit's level and having the same name than Component's ones, the map used in the parameters will contain mixed parameters (Component's + ServiceUnit' ones). We define the interceptors to use at the sending and receiving of Exchange respectively in the send and accept elements. The interceptors' calling sequence is the sequence into they are defined into the "receive" and "send" blocks. The interceptors which are defined at Component's level with a paramater active set at true are in all cases utmost importance than the interceptors defined at ServiceUnit's level and headed of the ordered interceptor list. In the same way, they are also configurable with extra parameters.
3.6. Benchmark notifications
3.6.1. Introduction
The CDK includes a JMX MBean which allows the publishing of notifications which measure the messages' processing duration. Four kinds of notifications are sent : • RECEIVING_FROM_NMR : global processing duration, by the emetting component, of a message coming from the NMR, • SENDING_TO_NMR : global processing duration of a message emetted by the emetting component on the MNR. This duration includes all the component processing durations coming into play, PEtALS bus' components as well as external components, • RECEIVING_FROM_OUTSIDE : global processing duration, by the emitting component, of an external query, • SENDING_TO_OUTSIDE : global processing duration by a linking chain which is external to the bus, and which emitting component is waiting an answer.
3.6.2. Use case
The notifications are located at Component's level, and always go together :
Component Framework
19
Go one step further...
• In the case of a BindingComponent, allowing the access to a ressource from the bus, each NMR sollicitation creates performance's notifications of RECEIVING_FROM_NMR and SENDING_TO_OUTSIDE type.
Figure 3.1. Performance RECEIVING_FROM_NMR/SENDING_TO_OUTSIDE
notification
• In the case of a ServiceEngine, each NMR sollicitation creates a RECEIVING_FROM_NMR notification. Moreover, if other services are invoked by this ServiceEngine, SENDING_TO_NMR notifications are sent. • In the case of a BindingComponent allowing the bus access from externals, each external sollicitation creates performance's notifications of RECEIVING_FROM_OUTSIDE and SENDING_TO_NMR types.
Figure 3.2. Performance RECEIVING_FROM_OUTSIDE/SENDING_TO_NMR
notification
Component Framework
20
Go one step further...
3.6.3. Client's approach
The performance's notifications are JMX notifications sent by a MBean loaded in each component, through the CF. The MBean is a custom MBean, which is located in the org.objectweb.petals domain and is named performance_notifier_, where is the component's name. The notifications's content is a String table observing :
Table 3.1. Performance notification format
index 0 1 2 3 4 5 description UID identifying a notifications' linked set. timestamp, corresponding also at the beginning of the measuring. emitting component notification's type, see above for more details on notification's types. treatment duration (in milliseconds) user data which content depends on the component. Refer the component's user guide to have more information about the accurate content of this field.
In the PEtALS' MX4J console, the MBeans of performance's notifications is located in the Server View tab, here is example below :
Figure 3.3. MBeans of performance's notifications of the BC Soap
To receive the performance's notifications of a component, they must be activated at component's MBean level. When this is done, in the PEtALS' MX4J console, after a click on the choosen MBean component, setting the "notificationsEnabled" attribute to true. It is also possible to define a sending step for the notifications through the attribute notificationsStep.
Figure 3.4. MBeans of performance's notifications of the BC Soap
The receiving of performance's notifications needs a JMX client which must suscribes to performance's notifications. It is possible to use the JConsole to receive these notifications. The PEtALS Eclipse plugin offers also a "Performance Notifications" view, more detailed than JConsole offers.
Component Framework
21
Go one step further...
Figure 3.5. Receiving performance's notifications through the PEtALS Eclipse plugin
Figure 3.6. Receiving performance's notifications through the JConsole
3.6.4. Development side
Natively the CDK classes load the management of some of the notifications. In the other cases, the notifications must be implemented at the component level itself. The CDK load the following cases : • RECEIVING_FROM_NMR notifications, when receiving a NMR message in a ServiceEngine or a BindingComponent. • SENDING_TO_NMR notifications, in a ServiceEngine or a BindingComponent, only if it uses the CDK methods to make a NMR call. In the other cases, the notifications have to be managed at component code level, using these methods : • AbstractComponent.createPerformanceNotificationSendingToOutside() : to create a SENDING_TO_OUTSIDE notification,
Component Framework
22
Go one step further...
• AbstractComponent.createPerformanceNotificationReceivingFromOutside() RECEIVING_FROM_OUTSIDE notification,
:
to
create
a
• AbstractComponent.createPerformanceNotificationSendingToNMR() : to create a SENDING_TO_NMR notification, • AbstractComponent.createPerformanceNotificationReceivingFromNMR() : to create a RECEIVING_FROM_NMR notification, • AbstractComponent.sendPerformanceNotification(...) : to publish a notification.
3.7. Exchange's sending in the JBI container
The CDK offers utilitarian methods which allow to send MessageExchanges under the guise of Exchanges through the JBI bus. These methods are available in two kinds of listeners (JBIListener and ExternalListener). There four methods : two synchronous ones and two asynchronous ones. They are similar for the two kinds of listener except that the ExternalListener's methods add destination details of the message (interface-name, service-name, endpoint-name) from the attributes of the "consumes" field, associated to this Listener. These details are added only if they are not specified in the MessageExchange set as a parameter of the method.
3.7.1. Synchronous send() with timeout
The method definition is the following : boolean sendSync(Exchange exchange, long timeoutMS). It sends the message set as attribute in the JBI bus, asynchronously, with the specified timeout as an attribute. If any operation is specified in the Exchange, it is searched in the extensions of the "provides" or "consumes" fields linked to the listener. The properties "routing.strategy", "transport.compress", "messaging.noack" and "transport.qos", possibly specified in the extensions of the "provides" or "consumes" fields linked to the listener, are automaticaly configured in the Exchange. The interceptors associated to the "provides" or "consumes" of this listener are automaticaly run (see Chapter 4 "Exchange's interceptors"). If the performance's notifications of the component are active, a notification is automaticaly send for each call of the method. It is possible to custom the field "userData" of the notifications with overloading of the getPerformanceNotificationUserData methodof the JBIListener.
3.7.2. Synchronous send() without timeout
The method definition is the following : boolean sendSync(Exchange exchange). This method is similar to the previous one but it searches for the timeout value to use in the "provides" or "consumes" fields extensions linked to the listener. If no value is found, the value 0 is used by default (i.e. no timeout).
3.7.3. Asynchronous send() without answer's synchrony
The method definition is the following : void send(Exchange exchange). This method is similar to the asynchronous send() without timeout, excepted that the sending is asynchronous and no benchmark notification is created.
3.7.4. Asynchronous send() with answer's synchrony
The method definition is the following : void sendAsync(Exchange exchange). This method is similar to the previous one but it adds a mechanism of answers' synchrony. Indeed, a frozing "accept" method is offered by the listeners. This method stays frozen until the answer sent to the Exchange (which is set as attribute)
Component Framework
23
Go one step further...
comes back to the service consumer. Then the accept(Exchange exchange) method returns the Exchange which contains the answer to the asynchronous call. Here is a sample of code showing the use of this asynchronous "send" method and the linked "accept" method :
Exchange m1 = createExchange(extensions); Exchange m2 = createExchange(extensions); sendAsync(m1); ... do some stuff sendAsync(m2); ... do some stuff Exchange reponse1 = accept(m1) --bloquant-... do some stuff Exchange reponse2 = accept(m2) --bloquant-... do some stuff
Component Framework
24