Red Hat Training
A Red Hat training course is available for JBoss Enterprise SOA Platform
ESB Programmers Guide
This guide is for software engineers.
Edition 5.3.1
Darrin Mison
Tom Wells
twells@redhat.com
Abstract
Preface
Chapter 1. Preface
1.1. Business Integration
1.2. What is a Service-Oriented Architecture?
A Service Oriented Architecture (SOA) is not a single program or technology. Think of it, rather, as a software design paradigm.
Note
1.3. Key Points of a Service-Oriented Architecture
- the messages being exchanged
- the agents that act as service requesters and providers
- the shared transport mechanisms that allow the messages to flow back and forth.
1.4. What is the JBoss Enterprise SOA Platform?
1.5. The Service-Oriented Architecture Paradigm
- Service Provider
- A service provider allows access to services, creates a description of a service and publishes it to the service broker.
- Service Requester
- A service requester is responsible for discovering a service by searching through the service descriptions given by the service broker. A requester is also responsible for binding to services provided by the service provider.
- Service Broker
- A service broker hosts a registry of service descriptions. It is responsible for linking a requester to a service provider.
1.6. Core and Components
1.7. Components of the JBoss Enterprise SOA Platform
- A full Java EE-compliant application server (the JBoss Enterprise Application Platform)
- an enterprise service bus (JBoss ESB)
- a business process management system (jBPM)
- a business rules engine (JBoss Rules)
- support for the optional JBoss Enterprise Data Services (EDS) product.
1.8. JBoss Enterprise SOA Platform Features
- The JBoss Enterprise Service Bus (ESB)
- The ESB sends messages between services and transforms them so that they can be processed by different types of systems.
- Business Process Execution Language (BPEL)
- You can use web services to orchestrate business rules using this language. It is included with SOA for the simple execution of business process instructions.
- Java Universal Description, Discovery and Integration (jUDDI)
- This is the default service registry in SOA. It is where all the information pertaining to services on the ESB are stored.
- Smooks
- This transformation engine can be used in conjunction with SOA to process messages. It can also be used to split messages and send them to the correct destination.
- JBoss Rules
- This is the rules engine that is packaged with SOA. It can infer data from the messages it receives to determine which actions need to be performed.
1.9. Features of the JBoss Enterprise SOA Platform's JBossESB Component
- Multiple transports and protocols
- A listener-action model (so that you can loosely-couple services together)
- Content-based routing (through the JBoss Rules engine, XPath, Regex and Smooks)
- Integration with the JBoss Business Process Manager (jBPM) in order to provide service orchestration functionality
- Integration with JBoss Rules in order to provide business rules development functionality.
- Integration with a BPEL engine.
- Be configured to work with a wide variety of transport mechanisms (such as e-mail and JMS),
- Be used as a general-purpose object repository,
- Allow you to implement pluggable data transformation mechanisms,
- Support logging of interactions.
Important
org.jboss.internal.soa.esb
and org.jboss.soa.esb
. Use the contents of the org.jboss.internal.soa.esb
package sparingly because they are subject to change without notice. By contrast, everything within the org.jboss.soa.esb
package is covered by Red Hat's deprecation policy.
1.10. Task Management
1.11. Integration Use Case
1.12. Utilising the JBoss Enterprise SOA Platform in a Business Environment
Part I. Introduction
Chapter 2. Preliminaries
2.1. Intended Audience
2.2. Aim of This Book
2.3. Back Up Your Data
Warning
2.4. Red Hat Documentation Site
2.5. Variable Name: SOA_ROOT Directory
jboss-soa-p-5
directory. In the Standalone edition, though, it is the jboss-soa-p-standalone-5
directory.
SOA_ROOT
. Substitute either jboss-soa-p-5
or jboss-soa-p-standalone-5
as appropriate whenever you see this name.
2.6. Variable Name: PROFILE
Chapter 3. Introducing the JBoss Enterprise SOA Platform
3.1. Enterprise Service Bus
3.2. Core Components of the Enterprise Service Bus
- Message listening and message filtering code
- Message listeners act as routers that 'listen' for inbound messages (such as those on a JMS queue or topic, or on the file system). They then present the message to a processing pipeline that filters and routes it (via an outbound router) to another message end-point.
- Data transformation components
- These are based on Smooks and XSLT.
- A content-based router
- This infers a message's destination from the information in its body.
- A message repository
- This is used to save messages and/or events that have been exchanged via the ESB.
3.3. Integration Between EDS and the JBoss Enterprise SOA Platform
- Service-oriented architecture patterns and best practices
- Reporting and analytics enablement
- Master data services
- Data governance and compliance
- Real-time read and write access to heterogeneous data stores
- Fast application development by simplifying access to distributed data
- Centralized access control and auditing
3.4. Enterprise Data Services Overview
- EDS Service
- The EDS Service is positioned between business applications and one or more data sources. It coordinates integration of these data sources so they can be accessed by the business applications at runtime.
- Design Tools
- Various design tools are available to assist users in setting up an EDS Service for a particular data integration solution.
- Administration Tools
- Various management tools are available for administrators to configure and monitor a deployed EDS Service.
Figure 3.1. Enterprise Data Services Overview
3.5. Developing with Enterprise Data Services
jdbc:teiid:vdb_name@mm://localhost:31000
.
Part II. Theory
Chapter 4. Services and Messages
4.1. Services
4.1.1. Service
jboss-esb.xml
configuration file.
4.1.2. Action Pipeline
4.1.3. ESB-Awareness
4.1.4. Message Listeners
org.jboss.soa.esb.message.Message
format. Each gateway listener must have a corresponding ESB listener defined.
4.1.5. ServiceInvoker
org.jboss.soa.esb.client.ServiceInvoker
) manages the delivery of messages to the specified Services. It also manages the loading of end-point references and the selection of couriers, thereby providing a unified interface for message delivery.
4.1.6. InVM Transport
4.1.7. Creating Your First Service
<?xml version = "1.0" encoding = "UTF-8"?> <jbossesb xmlns="http://anonsvn.labs.jboss.com/labs/jbossesb/trunk/product/etc/schemas/xml/jbossesb-1.0.1.xsd"> <services> <service category="Retail" name="ShoeStore" description="Acme Shoe Store Service" invmScope="GLOBAL"> <actions> <action name="println" class="org.jboss.soa.esb.actions.SystemPrintln" /> </actions> </service> </services> </jbossesb>
ServiceInvoker invoker = new ServiceInvoker(“Retail”, “ShoeStore”); Message message = MessageFactory.getInstance().getMessage(); message.getBody().add(“Hi there!”); invoker.deliverAsync(message);
Retail:ShoeStore
service. The registry automatically handles the process of sending the message from the client to one of the available endpoints. The process of transporting the message is completely transparent to the client.
invmScope="GLOBAL"1
. To add additional endpoints to the service, you must add them explicitly.
4.1.8. Types of Message Listener
- Gateway Listener
- This type of listener configure a gateway endpoint, which is used to push ESB-unaware messages into an ESB bus. It changes the message into a form the ESB can understand by wrapping it inside an ESB Message before sending it to the action pipeline.
- ESB-Aware Listener
- This type of listener creates an “ESB Aware” endpoint and is used to exchange ESB Messages between ESB-aware components.
4.1.9. Gateway Listener
org.jboss.soa.esb.message.Message
format. This conversion happens in a variety of different ways, depending on the gateway type. Once the conversion has occurred, the gateway listener routes the data to its correct destination.
4.1.10. Adding a Gateway Listener to a Service
<?xml version = "1.0" encoding = "UTF-8"?> <jbossesb xmlns="http://anonsvn.labs.jboss.com/labs/jbossesb/ trunk/product/etc/schemas/xml/jbossesb-1.0.1.xsd"> <providers> <jms-provider name="JBossMQ" connection-factory="ConnectionFactory"> <jms-bus busid="shoeStoreJMSGateway"> <jms-message-filter dest-type="QUEUE" dest-name="queue/shoeStoreJMSGateway"/> </jms-bus> </jms-provider> </providers> <services> <service category="Retail" name="ShoeStore" description="Acme Shoe Store Service" invmScope="GLOBAL"> <listeners> <jms-listener name="shoeStoreJMSGateway" busidref="shoeStoreJMSGateway" is-gateway="true"/> </listeners> <actions> <action name="println" class="org.jboss.soa.esb.actions.SystemPrintln" /> </actions> </service> </services> </jbossesb>
ServiceInvoker
always prefers to use a service's local InVM endpoint if one is available.)
4.2. Messages
4.2.1. ESB Message
org.jboss.soa.esb.message
interface. This standardized format consists of a header, body (payload) and attachments. All ESB-aware clients and services communicate with one another using messages.
4.2.2. Components of an ESB Message
- Header
- The header contains such information as the destination end-point reference, the sender end-point reference, and where the reply goes. This is all general message-level functional information.
- Context
- This is additional information that further explains the message; for example, transaction or security data, the identity of the ultimate receiver or HTTP-cookie information.
- Body
- The actual contents of the message.
- Fault
- Any error information associated with the message.
- Attachment
- Any attachments (additional files) associated with the message.
- Properties
- Any message-specific properties.(For example, the jbossesb.message.id property specifies a unique value for each message).
<xs:complexType name="Envelope"> <xs:attribute ref="Header" use="required"/> <xs:attribute ref="Context" use="required"/> <xs:attribute ref="Body" use="required"/> <xs:attribute ref="Attachment" use="optional"/> <xs:attribute ref="Properties" use="optional"/> <xs:attribute ref="Fault" use="optional"/> </xs:complexType>
4.2.3. How Message Objects are Sent to the Queue
The JBoss Enterprise SOA Platform product uses a properties object that is populated with parameters to identify the presence of JNDI on the local server. It is then used as the parameter for a call to create a new Naming Context which is used to obtain the ConnectionFactory. The Connection Factory, in turn, creates the QueueConnection, which creates the QueueSession. This QueueSession creates a Sender object for the Queue. The Sender object is used to create an ObjectMessage for the sender and to then send it to the Queue.
4.2.4. Message Interface
org.jboss.soa.esb.message.Message
interface:
public interface Message { public Header getHeader (); public Context getContext (); public Body getBody (); public Fault getFault (); public Attachment getAttachment (); public URI getType (); public Properties getProperties (); public Message copy () throws Exception; }
4.2.5. Message Header
4.2.6. Message Header Format
public interface Header { public Call getCall (); public void setCall (Call call); }
org.jboss.soa.esb.addressing.Call
class:
public class Call { public Call (); public Call (EPR epr); public Call (Call copy); public void setTo (EPR epr); public EPR getTo () throws URISyntaxException; public void setFrom (EPR from); public EPR getFrom () throws URISyntaxException; public void setReplyTo (EPR replyTo); public EPR getReplyTo () throws URISyntaxException; public void setFaultTo (EPR uri); public EPR getFaultTo () throws URISyntaxException; public void setRelatesTo (URI uri); public URI getRelatesTo () throws URISyntaxException; public void copy(); public void setAction (URI uri); public URI getAction () throws URISyntaxException; public final boolean empty(); public void setMessageID (URI uri); public URI getMessageID () throws URISyntaxException; public String toString(); public String stringForum(); public boolean valid(); public void copy (Call from); }
org.jboss.soa.esb.addressing.Call
class supports both one-way and request-reply interaction patterns.
Table 4.1. org.jboss.soa.esb.addressing.Call
Properties
Property | Type | Required | Description |
---|---|---|---|
To | EPR | Yes | The message recipient's address. |
From | EPR | No | The endpoint from which the message originated. |
ReplyTo | EPR | No | An endpoint reference that identifies the intended receiver for replies to this message. If a reply is expected, a message must contain a [ReplyTo]. The sender must use the contents of the [ReplyTo] to formulate the reply message. If the [ReplyTo] is absent, the contents of the [From] may be used to formulate a message to the source. This property may be absent if the message has no meaningful reply. If this property is present, the [MessageID] property is required. |
FaultTo | EPR | No | An endpoint reference that identifies the intended receiver for faults related to this message. When formulating a fault message the sender must use the contents of the [FaultTo] of the message being replied to to formulate the fault message. If the [FaultTo] is absent, the sender may use the contents of the [ReplyTo] to formulate the fault message. If both the [FaultTo] and [ReplyTo] are absent, the sender may use the contents of the [From] to formulate the fault message. This property may be absent if the sender cannot receive fault messages (for example, it is a one-way application message). If this property is present, the [MessageID] property is required. |
Action | URI | Yes | An identifier that uniquely (and opaquely) identifies the semantics implied by this message. |
MessageID | URI | Depends | A URI that uniquely identifies this message in time and space. No two messages with a distinct application intent may share a [MessageID] property. A message may be retransmitted for any purpose including communications failure and may use the same [MessageID] property. The value of this property is an opaque URI whose interpretation beyond equivalence is not defined. If a reply is expected, this property must be present. |
Warning
Note
4.2.7. The To Field
4.2.8. Message Context
4.2.9. Message Body
Warning
4.2.10. Message Payload
4.2.12. Message Body Format
public interface Body { public static final String DEFAULT_LOCATION = "org.jboss.soa.esb.message.defaultEntry"; public void add (String name, Object value); public Object get (String name); public byte[] getContents(); public void add (Object value); public Object get (); public Object remove (String name); public void replace (Body b); public void merge (Body b); public String[] getNames (); }
Important
add
option and give it a unique name. If your clients and services want a location for a byte array, you can use the one that the JBoss ESB itself uses: ByteBody.BYTES_LOCATION.
Warning
4.2.13. Message Fault
4.2.14. Fault Message Format
public interface Fault { public URI getCode (); public void setCode (URI code); public String getReason (); public void setReason (String reason); public Throwable getCause (); public void setCause (Throwable ex); }
4.2.15. Message Properties
public interface Properties { public Object getProperty(String name); public Object getProperty(String name, Object defaultVal); public Object setProperty(String name, Object value); public Object remove(String name); public int size(); public String[] getNames(); }
Note
java.util.Properties
have not been implemented within the JBoss Enterprise Service Bus. This is because they would restrict the types of client and service that could be used. Web Services stacks do not implement them for the same reasons. To overcome this limitation, embed java.util.Properties
within the current abstraction.
4.2.16. Message Attachment
4.2.17. Message Attachment Interface
public interface Attachment { Object get(String name); Object put(String name, Object value); Object remove(String name); String[] getNames(); Object itemAt (int index) throws IndexOutOfBoundsException; Object removeItemAt (int index) throws IndexOutOfBoundsException Object replaceItemAt(int index, Object value) throws IndexOutOfBoundsException; void addItem (Object value); void addItemAt (int index, Object value) throws IndexOutOfBoundsException; public int getUnnamedCount(); public int getNamedCount(); }
Note
4.2.18. Choosing the Right Method
- The developer defines the contract that the clients will use in order to interact with their service. As part of that contract, both functional and non-functional aspects of the service will be specified; for example, that it is an airline reservation service (functional) and that it is transactional in nature (non-functional).The developer will also define the operations (messages) that the service can understand. The format (such as Java Serialized Message or XML) is defined as part of the message definition. (In the example case, they will be the transaction context, seat number, customer name and so forth.) When you define the content, you can specify where in the message the service can find the payload. (This can be in the form of attachments or specific named objects, or even the default named object if one so wishes.) It is entirely up to the service developer to determine. The only restriction is that objects and attachments must have a globally-unique name, otherwise one service or action may inadvertently pick up a partial payload meant for another (if the same message body is being forwarded along on multiple "hops").
- Users can obtain the service's contract definition (either through either the UDDI registry or via an out-of-band communication) which defines where in the message the payload must be placed. Information put in other locations will almost certainly be ignored, resulting in the incorrect operation of the service.
4.2.19. Advice on Adding Data to the Body of a Message
MessagePayloadProxy
. This class handles the default settings but it also allows you to over-ride the defaults. .
- get-payload-location: this is the location from which to obtain the message payload.
- set-payload-location: this where you set the location for the message payload to go.
Note
Note
Note
4.2.20. Configure for Legacy Message Payload Exchange
Procedure 4.1. Task
- Open the
jbossesb-properties.xml
file in a text editor:vi SOA_ROOT/jboss-soa-p-5/jboss-as/server/PROFILE/deploy/jbossesb.sar/jbossesb-properties.xml
- Scroll down to the section entitled "Core".
- Set the use.legacy.message.payload.exchange.patterns property to “true”.
- Save the file and exit.
4.2.21. Extensions to the Message Body
Extensions Types
org.jboss.soa.esb.message.body.content.TextBody
- the content of the Body is an arbitrary string, and can be manipulated via the getText and setText methods.
org.jboss.soa.esb.message.body.content.ObjectBody
- the content of the Body is a serialized object, and can be manipulated via the getObject and setObject methods.
org.jboss.soa.esb.message.body.content.MapBody
- the content of the Body is a Map(String, Serialized), and can be manipulated via the setMap and other methods.
org.jboss.soa.esb.message.body.content.BytesBody
- the content of the body is a byte stream that contains arbitrary Java data-types. It can be manipulated using the various setter and getter methods for the data-types. Once created, the BytesMessage should be placed into either a read-only or write-only mode, depending upon how it needs to be manipulated. It is possible to change between these modes (using readMode and writeMode), but each time the mode is changed the buffer pointer will be reset. In order to ensure that all of the updates have been pushed into the body, it is necessary to call flush when finished.
create
method associated with each of the various body types. An example is createTextBody
. Use this to create and initialize a message of that specific type. Once created, manipulate the message directly by editing the raw body or by using its interface's methods. The body's structure is maintained even after transmission so that it can be manipulated by the message recipient using the methods of the interface that created it.
Note
4.2.22. End-Point Reference
4.2.23. Logical EPR
4.2.24. Logical EPR Use
Logical EPR
because it makes no assumptions about the end-point reference user (which is usually, but not necessarily always, the Enterprise Service Bus itself.) The LogicalEPR
's client can use the service name and category details that have been provided to look up the physical endpoint for that service. The client will do so at the time it intends to use the service. The client will also be able to select a physical end-point type to suit the situation.
4.2.25. FaultTo Field
4.2.26. Dead Letter Queue
4.2.27. ReplyTo Field
ReplyTo
defaults requires system administrators to specifically configure the JBoss Enterprise Service Bus' behaviour.)
4.2.28. Table of ReplyTo Field Settings
Table 4.2. Default ReplyTo by transport
Transport | ReplyTo |
---|---|
JMS | a queue with a name based on the one used to deliver the original request: <request queue name>_reply. |
JDBC | A table in the same database with a name based on the one used to deliver the original request: <request table name>_reply_table. The new table needs the same columns as the request table. |
files | No administration changes are required for either local or remote files. Responses are saved in the same directory as the request but with a unique suffix to ensure that only the original sender will pick up the response. |
4.2.29. Advice on Serializing Messages
- the data is to be stored
- the message is to be sent between different ESB processes
- you are debugging.
org.jboss.soa.esb.message.Message
interface from the org.jboss.soa.esb.message.format.MessageFactory
class:
public abstract class MessageFactory { public abstract Message getMessage (); public abstract Message getMessage (URI type); public abstract void reset(); public static MessageFactory getInstance (); }
- MessageType.JBOSS_XML
- This implementation uses an XML representation of the message. The schema for the message is defined in the
schemas/message.xsd
file. Arbitrary objects may be added to the message: in other words, they do not have to be serializable. Therefore, it may be necessary to provide a mechanism to marshal and un-marshal such objects to and from XML when the message needs to be serialized. Do this through theorg.jboss.soa.esb.message.format.xml.marshal.MarshalUnmarshalPlugin
:public interface MarshalUnmarshalPlugin { public static final String MARSHAL_UNMARSHAL_PLUGIN = "org.jboss.soa.esb.message.format.xml.plugin"; public boolean canPack(final Object value); public boolean marshal (Element doc, Object param) throws MarshalException; public Object unmarshal (Element doc) throws UnmarshalException; public URI type (); }
- MessageType.JAVA_SERIALIZED
- This is the default. This implementation requires that every component of the message be serializable. It also requires that the message recipients have sufficient information (via the Java classes) to be able to de-serialize it. Its URI is urn:jboss/esb/message/type/JAVA_SERIALIZED.It uses an XML representation of the message. The message's schema is defined in the
schemas/message.xsd
file. Its URI is urn:jboss/esb/message/type/JBOSS_XML.It also requires that all of the contents be Java-serializable. Any attempt to add a non-serializable object to the message will result in anIllegalParameterException
error.Its URI isurn:jboss/esb/message/type/JAVA_SERIALIZED
.
Important
org.jboss.soa.esb.message.format.MessagePlugin
:
public interface MessagePlugin { public static final String MESSAGE_PLUGIN = "org.jboss.soa.esb.message.format.plugin"; public Object createBodyType(Message msg, String type); public Message getMessage (); public URI getType (); }
jbossesb-properties.xml
file. (Use the property names that have the org.jboss.soa.esb.message.format.plugin extension.)
4.2.30. Change the Default Message Type
Procedure 4.2. Task
- Set the org.jboss.soa.esb.message.default.uri property to the name of the desired URI. (The default is JBOSS_XML.)
- Save the file and exit.
4.2.31. Register a Marshaling Plug-In
Procedure 4.3. Task
- Open the
jbossesb-properties.xml
file in a text editor:vi SOA_ROOT/jboss-soa-p-5/jboss-as/server/PROFILE/deploy/jbossesb.sar/jbossesb-properties.xml
- Add the name of the plug-in. (It must start with this prefix: MARSHAL_UNMARSHAL_PLUGIN.)
- Save the file and exit.
Part III. Developing
Chapter 5. Building and Using Services
5.1. Message Listener Configuration Properties
listener
configuration needs to supply information for:
- the
registry
(see theservice-category
,service-name
,service-description
andEPR-description
tag names.) If you set the optionalremove-old-service
tag name totrue
, the Enterprise Service Bus will remove any pre-existing service entry from theregistry
and then add this new instance. Always use this functionality with care as the entire service will be removed, including every end-point reference. - the instantiation of the
listener
class (see thelistenerClass
tag name). - the endpoint reference that the
listener
will service. This is transport-specific. The following example corresponds to a Java Message Service endpoint reference (see theconnection-factory
,destination-type
,destination-name
,jndi-type
,jndi-URL
andmessage-selector
tag names). - the
action pipeline
. This needs one or more <action> elements, each of which must contain theclass
tag name. These will determine whichaction
class will be instantiated for that link in thechain
.
<?xml version = "1.0" encoding = "UTF-8"?> <jbossesb xmlns="http://anonsvn.labs.jboss.com/labs/jbossesb/trunk/product/etc/schemas/xml/jbossesb-1.0.1.xsd" parameterReloadSecs="5"> <providers> <jms-provider name="JBossMQ" connection-factory="ConnectionFactory" jndi-URL="jnp://127.0.0.1:1099" jndi-context-factory="org.jnp.interfaces.NamingContextFactory" jndi-pkg-prefix="org.jboss.naming:org.jnp.interfaces"> <jms-bus busid="quickstartGwChannel"> <jms-message-filter dest-type="QUEUE" dest-name="queue/quickstart_helloworld_Request_gw"/> </jms-bus> <jms-bus busid="quickstartEsbChannel"> <jms-message-filter dest-type="QUEUE" dest-name="queue/quickstart_helloworld_Request_esb"/> </jms-bus> </jms-provider> </providers> <services> <service category="FirstServiceESB" name="SimpleListener" description="Hello World"> <listeners> <jms-listener name="JMS-Gateway" busidref="quickstartGwChannel" maxThreads="1" is-gateway="true"/> <jms-listener name="helloWorld" busidref="quickstartEsbChannel" maxThreads="1"/> </listeners> <actions> <action name="action1" class="org.jboss.soa.esb.samples. quickstart.helloworld.MyJMSListenerAction" process="displayMessage" /> <action name="notificationAction" class="org.jboss.soa.esb.actions.Notifier"> <property name="okMethod" value="notifyOK" /> <property name="notification-details"> <NotificationList type="ok"> <target class="NotifyConsole"/> </NotificationList> <NotificationList type="err"> <target class="NotifyConsole"/> </NotificationList> </property> </action> </actions> </service> </services> </jbossesb>
listener
object (the jms-listener tag), which will wait for those incoming ESB messages that are serialized within an interface. It then delivers each incoming message to an action pipeline
consisting of two steps (<action> elements):
- action1:
MyJMSListenerAction
(an example follows). - notificationAction: an
org.jboss.soa.esb.actions.SystemPrintln
class.
5.2. Characteristics of Filesystem Gateway Listeners
5.3. Pipeline Interceptor
org.jboss.soa.esb.listeners.message.PipelineInterceptor
is an interface that you can use to configure an interceptor which will be passed to the service configuration and the message at the start of the pipeline, at the end of the pipeline, at service instantiation, or at the point at which the pipeline fails due to an exception.
5.4. Working with Pipeline Interceptors
public void processMessage (Message msg, ConfigTree config)
which is called at the interception points defined in thejbossesb-properties.xml
configuration file.
jbossesb-properties.xml
file (located in the jbossesb.sar
archive) using the following properties:
- org.jboss.soa.esb.pipeline.failure.interceptors
- org.jboss.soa.esb.pipeline.instantiate.interceptors
- org.jboss.soa.esb.pipeline.start.interceptors
- org.jboss.soa.esb.pipeline.end.interceptors
Note
jbossesb-properties.xml
file on each ESB instance that is deployed in your environment. This will ensure that every instance can process the same meta-data.
org.jboss.soa.esb.listeners.message.GenericPipelineInterceptor
, which prints the message and demonstrates the general concept. It is up to you to provide the concrete implementation to use.
5.5. Routers
5.6. Router Configuration
5.7. Content-Based Router
5.8. Static-Based Router
5.9. Notifier
5.10. ServiceInvoker
org.jboss.soa.esb.client.ServiceInvoker
) manages the delivery of messages to the specified Services. It also manages the loading of end-point references and the selection of couriers, thereby providing a unified interface for message delivery.
5.11. Developing with the ServiceInvoker
public class ServiceInvoker { public ServiceInvoker(Service service) throws MessageDeliverException; public ServiceInvoker(String serviceCategory, String serviceName) throws MessageDeliverException; public ServiceInvoker(Service service, List<PortReference.Extension> extensions); public Message deliverSync(Message message, long timeoutMillis) throws MessageDeliverException, RegistryException, FaultMessageException; public void deliverAsync(Message message) throws MessageDeliverException; public Service getService(); public String getServiceCategory(); }
5.12. RegistryException
5.13. FaultMessageException
5.14. MessageDeliverException
5.15. Java Message Service
5.16. JMS Transacted Session
5.17. IncompatibleTransactionScopeException
5.18. InVM
5.18.1. InVM Transport
5.18.2. InVM Limitations
<service category="ServiceCat" name="Service2" description="Test Service"> <property name="inVMPassByValue" value="true" /> <actions mep="RequestResponse"> <action name="action" class="org.jboss.soa.esb.mock.MockAction" /> </actions> </service>
5.18.3. Developing with the InVM
<service category="ServiceCat" name="ServiceName" description="Test Service"> <actions mep="RequestResponse"> <action name="action" class="org.jboss.soa.esb.listeners.SetPayloadAction"> <property name="payload" value="Tom Fennelly" /> </action> </actions> </service>
- GLOBAL: (Default) The service can be invokable over the InVM transport from within the same Classloader scope.
- NONE: The service cannot be invoked over the InVM transport.
Note
Warning
Note
5.18.4. Set an InVM Scope for an Individual Service
Procedure 5.1. Task
- Open the file in a text editor.
- Set the service element's invmScope attribute:
<service category="ServiceCat" name="ServiceName" invmScope="GLOBAL" description="Test Service"> <actions mep="RequestResponse"> <action name="action" class="org.jboss.soa.esb.listeners.SetPayloadAction"> <property name="payload" value="Tom Fennelly" /> </action> </actions> </service>
- Save the file and exit.
5.18.5. Set the Default InVM Scope for a Deployment
Procedure 5.2. Task
- Open the
jbossesb-properties.xml
in your text editor:vi jbossesb-properties.xml
- Set the “core:jboss.esb.invm.scope.default” configuration property. (If left defined, the default scope is “GLOBAL”.)
- Save the file and exit.
5.18.6. Change the Number of Listener Threads Associated with an InVM Transport
Procedure 5.3. Task
- Open the file in a text editor.
- Edit the file like this:
<service category="HelloWorld" name="Service2" description="Service 2" invmScope="GLOBAL"> <property name="maxThreads" value="100" /> <listeners>... <actions>...
- Save the file and exit.
5.18.7. Lock-Step Delivery
5.18.8. Lock-Step Delivery Settings
- inVMLockStep
- This is a Boolean value. It controls whether or not Lock-Step Delivery is enabled.
- inVMLockStepTimeout
- This determines the maximum number of milliseconds for which message delivery will be blocked while waiting for a message to be retrieved.
<service category="ServiceCat" name="Service2" description="Test Service"> <property name="inVMLockStep" value="true" /> <property name="inVMLockStepTimeout" value="4000" /> <actions mep="RequestResponse"> <action name="action" class="org.jboss.soa.esb.mock.MockAction" /> </actions> </service>
Note
5.19. Load Balancing
5.19.1. Load Balancing
5.19.2. Configure a Load-Balancing Policy
Procedure 5.4. Task
- Open the global configuration file in a text editor:
vi SOA_ROOT/jboss-as/server/PROFILE/deployers/esb.deployers/jbossesb-properties.xml
. - Scroll down to the org.jboss.soa.esb.loadbalancer.policy property. Set it with the policy you wish to use.
- Save the file and exit.
5.19.3. Load Balancing Policies
Table 5.1. Load balancing Policies Available
Policy Name | Description |
---|---|
first available | If a healthy service binding is found it will be used until it dies. The next end-point reference in the list will then be used. There is no load balancing between the two service instances with this policy. |
round robin | A standard load-balancing policy whereby each end-point reference is utilised in list order. |
random robin | This is like the round robin, but the selection is randomized. |
Note
5.20. Service Contract Definition
5.20.1. Service Contract
5.20.2. Declaring Service Contract Schemas
Table 5.2. Service Contract Attributes
Name | Description | Type |
---|---|---|
inXsd | The resource containing the schema for the request message, representing a single element. | xsd:string |
outXsd | The resource containing the schema for the response message, representing a single element. | xsd:string |
faultXsd | A comma separated list of schemas, each representing one or more fault elements. | xsd:string |
requestLocation | The location of the request contents within the body, if not the default location. | xsd:string |
responseLocation | The location of the response contents within the body, if not the default location. | xsd:string |
5.20.3. Message Validation
5.21. Exposing ESB Services via Web Service End-Points
5.21.1. Exposing ESB Services via Web Service End-points
Table 5.3. Web Service Attributes
Name | Description |
---|---|
false | No web service endpoint will be published. |
true | A web service endpoint will be published (default). |
Table 5.4. WS-Addressing Values
Value | Description |
---|---|
false | No support for WS-Addressing (default). |
true | Require WS-Addressing support. |
Table 5.5. WS-Addressing Properties
Property | Description |
---|---|
org.jboss.soa.esb.gateway.ebws.messageID | The WS-Addressing message id. |
org.jboss.soa.esb.gateway.ebws.relatesTo | A String array containing the WS-Addressing RelatesTo URIs. |
org.jboss.soa.esb.gateway.ebws.relationshipType | A String array containing the WS-Addressing Relationship Types corresponding to the RelatesTo URIs. |
<service category="ServiceCat" name="ServiceName" description="Test Service"> <actions mep="RequestResponse" inXsd="/request.xsd" outXsd="/response.xsd" webservice="false" validate="true"> <!-- .... > </actions> </service>
<service category="ServiceCat" name="ServiceName" description="Test Service"> <actions mep="RequestResponse" inXsd="/request.xsd" outXsd="/response.xsd" validate="true" requestLocation="REQUEST" responseLocation="RESPONSE"> <!-- .... --> </actions> </service>
Chapter 6. Other Components
6.1. Message Store
Note
6.2. Smooks
6.3. Visitor Logic in Smooks
6.4. Data Transformation
Clients and services usually communicate using the same vocabulary. However, there are times when this will not be the case and you will require an "on-the-fly" transformation mechanism to translate from one format to another. It is unrealistic to assume that a single data format will suit every business object, particularly in a large-scale or long-running deployment. Therefore, a data transformation mechanism has been provided.
6.5. Content-Based Router
6.6. Content Based Routing Using the JBoss Rules Engine
action classes
, these being:
- a routing rule set, written in the
JBoss Rules
engine's DRL language (alternatively, you can use the DSL language if you prefer it); - the message content. This is the data that goes into the JBoss Rules engine (it comes in either XML format or as objects embedded in the message);
- the destination (which is derived from the resultant information coming out of the engine).
Note
content-based router
, a rule-set will evaluate its content and return a set of service destinations.
- org.jboss.soa.esb.actions.ContentBasedRouter: This action class implements the content-based routing pattern. It routes a message to one or more destination services, based on the message content and the rule set against which it is evaluating that content. The content-based router throws an exception when no destinations are matched for a given rule set or message combination. This action will terminate any further pipeline processing, so always position it last in your pipeline.
- org.jboss.soa.esb.actions.ContentBasedWiretap: This implements the WireTap pattern. The
WireTap
is an enterprise integration pattern that sends a copy of the message to a control channel. TheWireTap
is identical in functionality to the standard content-based router, however it does not terminate the pipeline. It is this latter characteristic which makes it suitable to be used as a wire-tap, hence its name. For more information, see http://www.eaipatterns.com/WireTap.html. - org.jboss.soa.esb.actions.MessageFilter: This implements the message filter pattern. The message filter pattern is used in cases where messages can simply be dropped if certain content requirements are not met. In other words, it functions identically to the content-based router except that it does not throw an exception if the rule set does not match any destinations, it simply filters the message out. For more information, see http://www.eaipatterns.com/Filter.html.
6.7. Service Registry
6.8. jUDDI Registry
6.9. jUDDI and the JBoss Enterprise SOA Platform
The JBoss Enterprise SOA Platform product includes a pre-configured installation of a jUDDI registry. You can use a specific API to access this registry through your custom client. However, any custom client that you build will not covered by your SOA Platform support agreement. You can access the full set of jUDDI examples, documentation and APIs from: http://juddi.apache.org/.
Chapter 7. Tutorial on Developing Messages
7.1. Overview
Conceptually, the message is a critical aspect of the SOA development approach. Messages contain the application-specific data sent between clients and services. The data in a message represents an important aspect of the "contract" between a service and its clients. In this section entails the best practices to use for this component.
- reserveSeat
- This takes a flight and seat number and returns a success or failure indication.
- querySeat
- This takes a flight and seat number and returns an indication of whether or not the seat is currently reserved.
- upgradeSeat
- This takes a flight number and two seat numbers (the currently reserved seat and the one the passenger will move to).
Note
7.2. Message Structure
opcode
(operation code) will appear in the body as a string (reserve
, query
, upgrade
) at the location called org.example.flight.opcode
. Any other string value (or the absence of a value) will result in the message being considered illegal.
Important
- “org.example.flight.seatnumber” for the seat number, which will be an integer.
- “org.example.flight.flightnumber” for the flight number, which will be a String.
- “org.example.flight.upgradenumber” for the upgraded seat number, which will be an integer.
Table 7.1. Operation Parameters
Operation | opcode | seatnumber | flightnumber | upgradenumber |
---|---|---|---|---|
reserveSeat | String: reserve | integer | String | N/A |
querySeat | String: query | integer | String | N/A |
upgradeSeat | String: upgrade | integer | String | integer |
7.3. Developing the Service
class AirlineReservationSystem { public void reserveSeat (...); public void querySeat (...); public void upgradeSeat (...); }
Note
@Process public Message process (Message message) throws Exception { String opcode = message.getBody().get(“org.example.flight.opcode”); if (opcode.equals(“reserve”)) reserveSeat(message); else if (opcode.equals(“query”)) querySeat(message); else if (opcode.equals(“upgrade”)) upgradeSeat(message); else throw new InvalidOpcode(); return null; }
Note
7.4. Decode the Payload
Procedure 7.1. Task
- The process method is only the start. Now we must provide methods to decode the incoming Message payload (the Body):
public void reserveSeat (Message message) throws Exception { String seatNumber = message.getBody().get(“org.example.flight.seatnumber”); String flight = message.getBody().get(“org.example.flight.flightnumber”); boolean success = airlineReservationSystem.reserveSeat(seatNumber, flight); // now create a response Message Message responseMessage = ... responseMessage.getHeader().getCall().setTo( message.getHeader().getCall().getReplyTo() ); responseMessage.getHeader().getCall().setRelatesTo( message.getHeader().getCall().getMessageID() ); // now deliver the response Message }
This code illustrates how the information within the body is extracted and then used to invoke a method on some business logic. In the case of reserveSeat, a response is expected by the client. This response message is constructed using any information returned by the business logic as well as delivery information obtained from the original received message. In this example, we need the To address for the response, which we take from the ReplyTo field of the incoming message. We also need to relate the response with the original request and we accomplish this through the RelatesTo field of the response and the MessageID of the request. - Code every operation supported by the service similarly.
7.5. Construct the Client
Procedure 7.2. Task
- As soon as we have the Message definitions supported by the service, we can construct the client code. The business logic used to support the service is never exposed directly by the service (that would break one of the important principles of SOA: encapsulation). This is essentially the inverse of the service code:
ServiceInvoker flightService = new ServiceInvoker(...); Message request = // create new Message of desired type request.getBody().add(“org.example.flight.seatnumber”, ”1”); request.getBody().add(“ org.example.flight.flightnumber”, “BA1234”); request.getHeader().getCall().setMessageID(1234); request.getHeader().getCall().setReplyTo(myEPR); Message response = null; do { response = flightService.deliverSync(request, 1000); if (response.getHeader().getCall().getRelatesTo() == 1234) { // it's out response! break; } else response = null; // and keep looping } while !maximumRetriesExceeded();
Note
Much of the above will be recognizable to readers who have worked with traditional client/server stub generators. In those systems, the low-level details (such as the opcodes and the parameters) are hidden behind higher-level stub abstractions. SOA Platform has integration with RESTEasy that enables a user to develop annotation based REST style web services. These hide the low level details such as opcodes and parameters.
7.6. Configuring a Remote Service Invoker
commons-codec-1.3.jar |
commons-collections.jar |
commons-configuration-1.5.jar |
commons-lang-2.4.jar |
commons-logging.jar |
concurrent.jar |
hornetq-core-client.jar |
hornetq-jms.jar |
javassist.jar |
jboss-aop-client.jar |
jboss-common-core.jar |
jboss-javaee.jar |
jboss-logging-spi.jar |
jboss-mdr.jar |
jboss-remoting.jar |
jbossall-client.jar |
jbossesb-config-model-1.0.1.jar |
jbossesb-config-model-1.1.0.jar |
jbossesb-config-model-1.2.0.jar |
jbossesb-config-model-1.3.0.jar |
jbossesb-config-model-1.3.1.jar |
jbossesb-registry.jar |
jbossesb-rosetta.jar |
jbossjmx-ant.jar |
jbossts-common.jar |
juddi-client-3.1.3.jar |
log4j.jar |
netty.jar |
scout-1.2.6.jar |
serializer.jar |
trove.jar |
uddi-ws-3.1.3.jar |
Note
$SOA_HOME/jboss-as/client/
, $SOA_HOME/jboss-as/common/lib/
and $SOA_HOME/jboss-as/server/$SOA_CONF/deployers/esb.deployer/lib/
directories.
jbossesb-properties.xml
META-INF/uddi.xml
7.7. Start the JBoss Enterprise SOA Platform
The following software must be installed:
- JBoss Enterprise SOA Platform
Procedure 7.3. Start the JBoss Enterprise SOA Platform
Start the SOA server in a server window
Red Hat Enterprise Linux
- Open a terminal and navigate to the
bin
directory by entering the commandcd SOA_ROOT/jboss-as/bin
. - Enter
./run.sh
to start the SOA server. (Because you are not specifying a server profile, "default" will be used.)
Microsoft Windows
- Open a terminal and navigate to the
bin
directory by entering the commandchdir SOA_ROOT\jboss-as\bin
. - Enter
run.bat
to start the SOA server. (Because you are not specifying a server profile, "default" will be used.)
The server starts. Note that this will take approximately two minutes, depending on the speed of your hardware.
Note
less SOA_ROOT/jboss-as/server/PROFILE/log/server.log
. As another check, open a web browser and go to http://localhost:8080. Make sure you can login to the admin console with the user name and password you have set.
7.8. Deploy the "Hello World" Quickstart on Your Test Server
Prerequisites
- Check that the setting in
SOA_ROOT/jboss-as/samples/quickstarts/conf/quickstarts.properties-example
matches the server configuration (default
in a testing environment).
Procedure 7.4. Deploy the "Hello World" Quickstart
- Check that the server has fully launched.
- Open a second terminal window and navigate to the directory containing the quick start:
cd SOA_ROOT/jboss-as/samples/quickstarts/helloworld
(orchdir SOA_ROOT\jboss-as\samples\quickstarts\helloworld
in Microsoft Windows). - Run
ant deploy
to deploy the quickstart. Look for messages such as this to confirm if the deployment was successful:deploy-esb: [copy] Copying 1 file to /jboss/local/53_DEV2/jboss-soa-p-5/jboss-as/server/default/deploy deploy-exploded-esb: quickstart-specific-deploys: [echo] No Quickstart specific deployments being made. display-instructions: [echo] [echo] ****************** [echo] Quickstart deployed to target JBoss ESB/App Server at '/jboss/local/53_DEV2/jboss-soa-p-5/jboss-as/server/default/deploy'. [echo] 1. Check your ESB Server console to make sure the deployment was executed without errors. [echo] 2. Run 'ant runtest' to run the Quickstart. [echo] 3. Check your ESB Server console again. The Quickstart should have produced some output. [echo] ****************** deploy: BUILD SUCCESSFUL
Also, check for this in theSOA_ROOT/jboss-as/server/default/log/server.log
:10:58:52,998 INFO [NamingHelper] JNDI InitialContext properties:{} 11:00:58,154 INFO [QueueService] Queue[/queue/quickstart_helloworld_Request_esb] started, fullSize=200000, pageSize=2000, downCacheSize=2000 11:00:58,186 INFO [QueueService] Queue[/queue/quickstart_helloworld_Request_gw] started, fullSize=200000, pageSize=2000, downCacheSize=2000 11:00:58,427 INFO [EsbDeployment] Starting ESB Deployment 'Quickstart_helloworld.esb'
- Run the quickstart by issuing this command:
ant runtest
. When the quickstart is run, messages such as this are written to theSOA_ROOT/jboss-as/server/default/log/server.log
:11:03:02,190 INFO [STDOUT] &&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&& 11:03:02,191 INFO [STDOUT] Body: Hello World 11:03:02,191 INFO [STDOUT] &&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&& 11:03:02,192 INFO [STDOUT] Message structure: 11:03:02,192 INFO [STDOUT] [Hello World].
The words "Hello World" will appear on the server terminal. This message will also be appended to the SOA_ROOT/jboss-as/server/default/log/server.log
file.
7.9. Test the Configuration of the Remote Client
Prerequisites
- The server must have been started and the Hello World quick start must have been deployed
Procedure 7.5. Task
- Run this test code:
package org.jboss.esb.client; import import import import org.jboss.soa.esb.client.ServiceInvoker; org.jboss.soa.esb.listeners.message.MessageDeliverException; org.jboss.soa.esb.message.Message; org.jboss.soa.esb.message.format.MessageFactory; public class EsbClient { public static void main(String[] args) { System.setProperty("javax.xml.registry.ConnectionFactoryClass", "org.apache.ws.scout.registry.ConnectionFactoryImpl"); try { Message message = MessageFactory.getInstance().getMessage(); message.getBody().add("Sample payload"); ServiceInvoker invoker = new ServiceInvoker("FirstServiceESB", "SimpleListener"); invoker.deliverAsync(message); } catch (final MessageDeliverException e) { e.printStackTrace(); } } }
7.10. Verify That a Remote Client's Configuration is Correct
Prerequisites
- The JBoss Enterprise SOA Platform must be running and the HelloWorld quick start must be deployed.
Procedure 7.6. Task
- Run this code:
package org.jboss.esb.client; import org.jboss.soa.esb.client.ServiceInvoker; import org.jboss.soa.esb.listeners.message.MessageDeliverException; import org.jboss.soa.esb.message.Message; import org.jboss.soa.esb.message.format.MessageFactory; public class EsbClient { public static void main(String[] args) { System.setProperty("javax.xml.registry.ConnectionFactoryClass", "org.apache.ws.scout.registry.ConnectionFactoryImpl"); try { Message message = MessageFactory.getInstance().getMessage(); message.getBody().add("Sample payload"); ServiceInvoker invoker = new ServiceInvoker("FirstServiceESB", "SimpleListener"); invoker.deliverAsync(message); } catch (final MessageDeliverException e) { e.printStackTrace(); }
7.11. Further Advice for When Building Clients and Services
- when developing an action, ensure any payload information specific to it is maintained in unique message body locations.
- try not to expose any backend service implementation details within the message as this will make it difficult to change the implementation without affecting clients. Use message definitions (contents, formats and so on) which are "implementation-agnostic" as this will help to keep the coupling loose.
- for stateless services, use the
ServiceInvoker
as it handles fail-over "opaquely." - When building request/response applications, use the correlation information (MessageID and RelatesTo) within the Message Header.
- consider using the Header Action field for the main service opcode.
- If using asynchronous interactions in which there is no delivery address for responses, consider sending any errors to the MessageStore so that they can be monitored later.
- until the JBoss Enterprise SOA Platform provides better automatic support for service contract definition and publication, consider maintaining a separate repository of these definitions, and make it available to both developers and users.
Chapter 8. Advanced Topics
8.1. Node
8.2. The Bus
8.3. Delivery Channel
8.4. Run the Same Service on More than One Node in a Cluster
Procedure 8.1. Task
- To run the same service on more than one node in a cluster, wait until the Registry's cache revalidates.
8.5. Remove Failed End-Point References from the Registry
Procedure 8.2. Task
- Open the
jbossesb-properties.xml
in a text editor:vi SOA_ROOT/jboss-as/server/PROFILE/deployers/esb.deployers/jbossesb-properties.xml
. - Scroll down to the section that contains org.jboss.soa.esb.failure.detect.removeDeadEPR. Set this property to true.
- Save the file and exit.
Warning
Note that the default setting is false because this feature should be used with extreme care. If it is employed, the end-point reference for a service that is simply overloaded and, therefore, slow to respond may, inadvertently, be removed by mistake. There will be no further interactions with these "orphaned" services you may have to restart them.
8.6. How Services Work
Read this section to learn in more detail how services, end-point references, listeners and actions actually work.
... <service category="FirstServiceESB" name="SimpleListener" description="Hello World"> <listeners> <jms-listener name="helloWorld" busidref="quickstartEsbChannel" maxThreads="1"/> </listeners> <actions> <action name="action1" class="org.jboss.soa.esb.actions.SystemPrintln"/> </actions> </service> ...
Note
8.7. Application Service
8.8. How Service Replication Works
helloworld.esb
and deploy it to Node2 as well as on Node1? Assume you are using jUDDI for your registry and that you have configured all our nodes to access one central jUDDI database. Node2 will find that the FirstServiceESB - SimpleListener Service
is already registered. Therefore, it will add a second ServiceBinding to this service so there are now two ServiceBindings for this service. Hence, if Node1 goes down, Node2 will keep on working.
Note
8.9. JBossMessaging
8.10. Cluster
8.11. Stateless Service Failover
8.12. Enable JMS Clustering
Procedure 8.3. Task
- Read the documentation on clustering for JBoss Messaging at http://community.jboss.org/wiki/JBossMessaging.
8.13. Protocol Clustering
When you cluster your JMS you remove a single point of failure from your architecture.
Note
Note
8.14. Running the Same Service Across Different Nodes in a Cluster
If you would like to run the same service on more than one node in a cluster you have to wait for the service registry cache to revalidate. After that, the service will run across the clustered environment.
8.15. Configure the Registry Cache Time-Out Value
Procedure 8.4. Task
- Open the
deploy/jbossesb.sar/jbossesb-properties.xml
file in your text editor:vi deploy/jbossesb.sar/jbossesb-properties.xml
- Set the cache time-out value:
<properties name="core"> <property name="org.jboss.soa.esb.registry.cache.life" value="60000"/> </properties>
Note that 60 000 milliseconds (sixty seconds) is the default value. - Save the file and exit.
8.16. Channel Fail-Over
... <service category="FirstServiceESB" name="SimpleListener" description="Hello World"> <listeners> <jms-listener name="helloWorld" busidref="quickstartEsbChannel" maxThreads="1"/> <jms-listener name="helloWorld2" busidref="quickstartFtpChannel2" maxThreads="1"/> </listeners> ...
... <service category="FirstServiceESB" name="SimpleListener" description="Hello World"> <listeners> <jms-listener name="helloWorld" busidref="quickstartEsbChannel" maxThreads="1"/> <jms-listener name="helloWorld2" busidref="quickstartJmsChannel2" maxThreads="1"/> <ftp-listener name="helloWorld3" busidref="quickstartFtpChannel3" maxThreads="1"/> <ftp-listener name="helloWorld4" busidref="quickstartFtpChannel3" maxThreads="1"/> </listeners> ...
Note
8.17. Deactivate Automatic Fail-Over
Procedure 8.5. Task
- Open the JBossESB property file in a text editor.
- Set the org.jboss.soa.esb.exceptionOnDeliverFailure property to true
- Save the file and exit.
Note
Alternatively this can be configured on a per message basis by setting the same property in the specific message in question to true. In both cases the default is false.
8.18. Load Balancing
8.19. Configure a Load-Balancing Policy
Procedure 8.6. Task
- Open the global configuration file in a text editor:
vi SOA_ROOT/jboss-as/server/PROFILE/deployers/esb.deployers/jbossesb-properties.xml
. - Scroll down to the org.jboss.soa.esb.loadbalancer.policy property. Set it with the policy you wish to use.
- Save the file and exit.
8.20. Load Balancing Policies
Table 8.1. Load balancing Policies Available
Policy Name | Description |
---|---|
first available | If a healthy service binding is found it will be used until it dies. The next end-point reference in the list will then be used. There is no load balancing between the two service instances with this policy. |
round robin | A standard load-balancing policy whereby each end-point reference is utilised in list order. |
random robin | This is like the round robin, but the selection is randomized. |
Note
8.21. Transactions and the Action Pipeline
8.22. Rollbacks
8.23. Rollbacks and the JMS JCA Listener
<configuration xmlns="urn:hornetq" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:hornetq /schema/hornetq-configuration.xsd"> <address-settings> <address-setting match="jms.queue.MyServiceQueue"> <max-delivery-attempts>5</max-delivery-attempts> <redelivery-delay>1000</redelivery-delay> <max-size-bytes>10240</max-size-bytes> </address-setting> </address-settings> </configuration>
8.24. Message Re-delivery
- If you are trying to deliver the message synchronously it will send the message to the DeadLetterService, which by default will store to the DLQ MessageStore, and it will send a failure back to the caller. Processing will stop. Note that you can configure the DeadLetterService in the jbossesb.esb if for instance you want it to go to a JMS queue, or if you want to receive a notification.
- If you are trying to deliver the message asynchronously (recommended), it too will send the message to the DeadLetterService, but the message will get stored to the RDLVR MessageStore. The Redeliver Service (jbossesb.esb) will retry sending the message until the maximum number of redelivery attempts is exceeded. In that case the message will get stored to the DLQ MessageStore and processing will stop.
Note
8.25. Scheduling
8.25.1. Quartz Scheduler
8.25.2. Configuring Quartz Scheduler
org.quartz.scheduler.instanceName = DefaultQuartzScheduler org.quartz.scheduler.rmi.export = false org.quartz.scheduler.rmi.proxy = false org.quartz.scheduler.wrapJobExecutionInUserTransaction = false org.quartz.threadPool.class = org.quartz.simpl.SimpleThreadPool org.quartz.threadPool.threadCount = 2 org.quartz.threadPool.threadPriority = 5 org.quartz.threadPool.threadsInheritContextClassLoaderOfInitializingThread = true org.quartz.jobStore.misfireThreshold = 60000 org.quartz.jobStore.class = org.quartz.simpl.RAMJobStore
<schedule-provider name="schedule"> <property name=”org.quartz.threadPool.threadCount” value=”5” /> <cron-schedule scheduleid="cron-trigger" cronExpression="0/1 * * * * ?" /> </schedule-provider>
8.25.3. Scheduling Services
- Bus Providers
- These supply messages to action processing pipelines via messaging protocols such as JMS and HTTP. This provider type is “triggered” by the underlying messaging provider.
- Schedule Providers
- These supply messages to action processing pipelines based on a schedule driven model such as when the underlying message delivery mechanism (for example, the file system) offers no support for triggering the enterprise service bus when messages are available for processing, a scheduler periodically triggers the listener to check for new messages.
org.jboss.soa.esb.listeners.ScheduledEventMessageComposer
interface..
Important
8.25.4. Simple Schedule
- scheduleid
- A unique identifier string for the schedule. Used to reference a schedule from a listener.
- frequency
- The frequency (in seconds) with which all schedule listeners should be triggered.
- execCount
- The number of times the schedule should be executed.
- startDate
- The schedule start date and time. The format of this attribute value is that of the XML Schema type “dateTime”. See http://books.xmlschemata.org/relaxng/ch19-77049.html.
- endDate
- The schedule end date and time. The format of this attribute value is that of the XML Schema type “dateTime”. See http://books.xmlschemata.org/relaxng/ch19-77049.html.
<providers> <schedule-provider name="schedule"> <simple-schedule scheduleid="1-sec-trigger" frequency="1" execCount="5" /> </schedule-provider> </providers>
8.25.5. Cron Schedule
- scheduleid
- A unique identifier string for the schedule. Used to reference a schedule from a listener
- cronExpression
- CRON expression
- startDate
- The schedule start date and time. The format of this attribute value is that of the XML Schema type “dateTime”. See http://books.xmlschemata.org/relaxng/ch19-77049.html.
- endDate
- The schedule end date and time. The format of this attribute value is that of the XML Schema type “dateTime”. See http://books.xmlschemata.org/relaxng/ch19-77049.html.
<providers> <schedule-provider name="schedule"> <cron-schedule scheduleid="cron-trigger" cronExpression="0/1 * * * * ?" /> </schedule-provider> </providers>
8.25.6. Scheduled Listener
event-processor
class, which can be an implementation of one of org.jboss.soa.esb.schedule.ScheduledEventListener
or org.jboss.soa.esb.listeners.ScheduledEventMessageComposer
.
- ScheduledEventListener
- Event Processors that implement this interface are simply triggered through the “onSchedule” method. No action processing pipeline is executed.
- ScheduledEventMessageComposer
- Event Processors that implement this interface are capable of “composing” a message for the action processing pipeline associated with the listener.
- name: The name of the listener instance
- event-processor: The event processor class that is called on every schedule trigger. See above for implementation details.
- One of:
- name: The name of the listener instance.
- scheduleidref: The scheduleid of the schedule to use for triggering this listener.
- schedule-frequency: Schedule frequency (in seconds). A convenient way of specifying a simple schedule directly on the listener.
8.25.7. Sample Configuration Combining the Scheduled Listener and Cron Scheduler
<?xml version = "1.0" encoding = "UTF-8"?> <jbossesb xmlns="http://anonsvn.labs.jboss.com/labs/jbossesb/trunk/product/etc/schemas/xml/jbossesb-1.0.1.xsd"> <providers> <schedule-provider name="schedule"> <cron-schedule scheduleid="cron-trigger" cronExpression="0/1 * * * * ?" /> </schedule-provider> </providers> <services> <service category="ServiceCat" name="ServiceName" description="Test Service"> <listeners> <scheduled-listener name="cron-schedule-listener" scheduleidref="cron-trigger" event-processor="org.jboss.soa.esb.schedule.MockScheduledEventMessageComposer" /> </listeners> <actions> <action name="action" class="org.jboss.soa.esb.mock.MockAction" /> </actions> </service> </services> </jbossesb>
Chapter 9. Fault Tolerance and Reliability
9.1. System Reliability
There are many components and services within the JBoss Enterprise SOA Platform. The failure of some of them may go unnoticed to some or all of your applications depending upon when the failure occurs. For example, if the registry service crashes after your consumer has successfully obtained all the EPR information for the services it needs to function, the crash will have no adverse affect on your application. However, if it fails before this point, your application will not be able to progress. Therefore, in any determination of reliability guarantees, it is necessary to consider when failures occur and what type of failures they could be.
9.2. Fault Tolerance
9.3. Dependability
9.4. Message Loss
JMSEpr
), it is possible to guarantee that messages are received and processed in the presence of failures. If a failure occurs during processing by the service, the message will be placed back on the JMS queue for later re-processing. However, transacted sessions can be significantly slower than non-transacted sessions and so should be used with caution.
Note
9.5. Failed End-Points
9.6. Supported Crash Recovery Modes
9.7. Message Failure, Component by Component
- Gateways
- Once a message is accepted by a gateway it will not be lost unless sent within the ESB using an unreliable transport. JMS, FTP and SQL are JBossESB transports can be configured to either reliably deliver the message or ensure it is not removed from the system. Unfortunately, HTTP cannot be configured in this way.
- ServiceInvoker
- The ServiceInvoker will place undeliverable messages in the re-delivery queue if they have been sent asynchronously. Synchronous message delivery that fails will be indicated to the sender immediately. In order for the ServiceInvoker to function correctly, the transport must indicate a failure to deliver to the sender unambiguously. A simultaneous failure of the sender and receiver may result in the message being lost.
- JMS Broker
- Messages that cannot be delivered to the JMS broker will be placed within the re-delivery queue. For enterprise deployments, a clustered JMS broker is recommended.
- Action Pipelining
- It is important to differentiate between a message being received by the container in which services reside and it being processed by the ultimate destination. It is possible for messages to be delivered successfully, only for an error or crash during processing within the Action pipeline to cause its loss. As mentioned, it is possible to configure some of the JBossESB transports so that they do not delete received messages when they are processed. This so they will not be lost in the event of an error or crash.
9.8. Ways in Which You Can Minimize the Risk of Failures
- Try to develop stateless and idempotent services. If this is not possible, use MessageID to identify Messages so your application can detect retransmission attempts. If retrying Message transmission, use the same MessageID. Services that are not idempotent and would suffer from redoing the same work if they receive a retransmitted Message, should record state transitions against the MessageID, preferably using transactions. Applications based around stateless services tend to scale better as well.
- If developing stateful services, use transactions and a (preferably clustered) JMS implementation.
- Cluster your Registry and use a clustered/fault-tolerant back-end database, to remove any single points of failure.
- Ensure that the Message Store is backed by a highly available database.
- Clearly identify which services and which operations on services need higher reliability and fault tolerance capabilities than others. This will allow you to target transports other than JMS at those services, potentially improving the overall performance of applications. Because JBossESB allows services to be used through different EPRs concurrently, it is also possible to offer these different qualities of service (QoS) to different consumers based on application specific requirements.
- Because network partitions can make services appear as though they have failed, avoid transports that are more prone to this type of failure for services that cannot cope with being misidentified as having crashed.
- In some situations (for example, HTTP) the crash of a server after it has dealt with a message but before it has responded could result in another server doing the same work. This is because it is not possible to differentiate between a machine that fails after the service receives the message and process it, and one where it receives the message and doesn't process it.
- Using asynchronous (one-way) delivery patterns will make it difficult to detect failures of services: there is typically no notion of a lost or delayed Message if responses to requests can come at arbitrary times. If there are no responses at all, then it obviously makes failure detection more problematical and you may have to rely upon application semantics to determine that Messages did not arrive (for example, the amount of money in the bank account does not match expectations). When using either the ServiceInvoker or Couriers to delivery asynchronous Messages, a return from the respective operation (e.g., deliverAsync) does not mean the Message has been acted upon by the service.
- The message store is used by the redelivery protocol. However, as mentioned this is a best-effort protocol for improved robustness and does not use transactions or reliable message delivery. This means that certain failures may result in messages being lost entirely (they do not get written to the store before a crash), or delivered multiple times (the redelivery mechanism pulls a message from the store, delivers it successfully but there is a crash that prevents the message from being removed from the store.) Upon recovery the message will be delivered again.
- Some transports, such as FTP, can be configured to retain messages that have been processed, although they will be uniquely marked to differentiate them from un-processed messages. The default approach is often to delete messages once they have been processed, but you may want to change this default to allow your applications to determine which messages have been dealt with upon recovery from failures.
Chapter 10. Defining Service Configurations
10.1. Introduction to Configuring the Product
The JBoss Enterprise SOA Platform's configuration settings are based on the jbossesb-1.3.0 XSD schema (http://anonsvn.jboss.org/repos/labs/labs/jbossesb/trunk/product/etc/schemas/xml/jbossesb-1.3.0.xsd). This XSD is always the definitive reference for configuring the product.Introductory text goes here.
- <globals>
- <providers>: Defines all the message <bus> providers used by the message <listener>s, defined within the <services> section of the model.
- <services>: Defines all of the services under the control of a single instance of JBoss ESB. Each <service> instance contains either a “Gateway” or “Message Aware” listener definition.
Note
10.2. Providers
10.3. Types of Providers
- Bus Providers: These specify provider details for “Event Driven” providers, that is, for listeners that are “pushed” messages. Examples of this provider type would be the <jms-provider>.
- Schedule Provider: Provider configurations for schedule-driven listeners (that is, listeners that “pull” messages.)
<jms-provider>
can contain multiple <bus>
definitions. The <provider>
can also be decorated with <property>
instances relating to provider specific properties that are common in <bus>
instances defined on that <provider>
. For example, JMS may have “connection-factory”, “jndi-context-factory” and so on. Likewise, each <bus>
instance can be decorated with <property>
instances specific to that <bus>
instance. (For example, JMS has “destination-type”, “destination-name” and so forth.)
<providers> <jms-provider name="JBossMQ" connection-factory="ConnectionFactory"> <jms-bus busid="Reconciliation"> <jms-message-filter dest-type="QUEUE" dest-name="queue/B" /> </jms-bus> </jms-provider> </providers>>
Important
10.4. Services
10.5. Attributes of a Service
Table 10.1. Service Attributes
Name | Description | Type | Required |
---|---|---|---|
name | The name under which the service is registered in the Service Registry. | xsd:string | true |
category | The service category under which the service is registered in the registry. | xsd:string | true |
description | Human readable description of the service stored in the registry. | xsd:string | true |
10.6. Attributes of a Listener
Table 10.2. Listener Attributes
Name | Description | Type | Required |
---|---|---|---|
name | The name of the listener. This attribute is required primarily for logging purposes. | xsd:string | true |
busrefid | Reference to the busid of the <bus> through which the listener instance receives messages. | xsd:string | true |
maxThreads | The maximum number of concurrent message processing threads that the listener can have active. | xsd:int | True |
is-gateway | Whether or not the listener instance is a “Gateway” or “Message Aware” Listener.
A message bus defines the details of a specific message channel or transport.
| xsd:boolean | true |
Note
<?xml version = "1.0" encoding = "UTF-8"?> <jbossesb xmlns="http://anonsvn.jboss.org/repos/labs/labs/jbossesb/trunk/product/etc/schemas/xml/jbossesb-1.3.0.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://anonsvn.jboss.org/repos/labs/labs/jbossesb/trunk/product/etc/schemas/xml/jbossesb-1.3.0.xsd http://anonsvn.jboss.org/repos/labs/labs/jbossesb/trunk/product/etc/schemas/xml/jbossesb-1.3.0.xsd" parameterReloadSecs="5"> <providers> <jms-provider name="JBossMQ" connection-factory="ConnectionFactory"> <jms-bus busid="Reconciliation"> <jms-message-filter dest-type="QUEUE" dest-name="queue/B" /> </jms-bus> <!-- busid --> <jms-bus busid="ReconciliationEsb"> <jms-message-filter dest-type="QUEUE" dest-name="queue/C" </jms-bus> </jms-provider> </providers> <services> <service category="Bank" name="Reconciliation" description="Bank Reconciliation Service"> <listeners> <!-- busidref --> <jms-listener name="Bank-Listener" busidref="Reconciliation" is-gateway="true"/> <jms-listener name="Bank-Esb" busidref="ReconciliationEsb"/> </listeners> <actions> .... </actions> </service> </services> </jbossesb>
10.7. Actions
10.8. Attributes of an Action
Table 10.3. Action Attributes
Name | Description | Type | Required |
---|---|---|---|
name | The name of the action. This attribute is required primarily for logging purposes. | xsd:string | true |
class | The action class must extend one of: org.jboss.soa.esb.actions.AbstractActionLifecycle, org.jboss.soa.esb.actions.ActionPipelineProcessor. | xsd:string | true |
process | The name of the “process” method that will be reflectively called for message processing.(Default is the “process” method.) | xsd:int | false |
<action>
instances appear in the <actions>
set. The message returned from each <action>
is used as the input message to the next <action>
in the list.
org.jboss.soa.esb.actions.ActionProcessor
class. All implementations of this interface must contain a public constructor of the following form:
public ActionZ(org.jboss.soa.esb.helpers.ConfigTree configuration);
<actions> <action name="MyAction-1" class="com.acme.MyAction1"/> <action name="MyAction-2" class="com.acme.MyAction2"> <property name="propA" value="propAVal" /> </action> <action name="MyAction-3" class="com.acme.MyAction3"> <property name="propB" value="propBVal" /> <property name="propC"> <!-- Free form child content... --> <some-free-form-element>zzz<some-free-form-element> </property> </action> </actions>
10.9. Implementing a Transport-Specific Configuration
<provider>
, <bus>
and <listener>
(that is, JMS, SQL and so forth.) Using one of these special variants allows you to have stronger validation on the configuration. These specializations explicitly define the configuration requirements for each of the transports supported by the product out-of-the-box.
Note
Important
- Define the provider configuration e.g. <jms-provider>.
- Add the bus configurations to the new provider (for example, <jms-bus>), and assign a unique busid attribute value.
- Define your <services> as "normal," adding transport-specific listener configurations (such as <jms-listener>) that reference (using busidref) the new bus configurations you just made. (For example, <jms-listener> referencing a <jms-bus>.)
- JMS: <jms-provider>, <jms-bus>, <jms-listener> and <jms-message-filter>: The <jms-message-filter> can be added to either the <jms-bus> or <jms-listener> elements. Where the <jms-provider> and <jms-bus> specify the JMS connection properties, the <jms-message-filter> specifies the actual message QUEUE/TOPIC and selector details.
- SQL: <sql-provider>, <sql-bus>, <sql-listener> and <sql-message-filter>: The <sql-message-filter> can be added to either the <sql-bus> or <sql-listener> elements. Where the <sql-provider> and <sql-bus> specify the JDBC connection properties, the <sql-message-filter> specifies the message/row selection and processing properties.
- FTP: <ftp-provider>, <ftp-bus>, <ftp-listener> and <ftp-message-filter>: The <ftp-message-filter> can be added to either the <ftp-bus> or <ftp-listener> elements. Where the <ftp-provider> and <ftp-bus> specify the FTP access properties, the <ftp-message-filter> specifies the message/file selection and processing properties
- Hibernate: <hibernate-provider>, <hibernate-bus>, <hibernate-listener> : The <hibernate-message-filter> can be added to either the <hibernate-bus> or <hibernate-listener> elements. Where the <hibernate-provider> specifies file system access properties like the location of the hibernate configuration property, the <hibernate-message-filter> specifies what classnames and events should be listened to.
- File system: <fs-provider>, <fs-bus>, <fs-listener> and <fs-message-filter> The <fs-message-filter> can be added to either the <fs-bus> or <fs-listener> elements. Where the <fs-provider> and <fs-bus> specify the File System access properties, the <fs-message-filter> specifies the message/file selection and processing properties.
- schedule: <schedule-provider>. This is a special type of provider and differs from the bus based providers listed above. See Scheduling for more.
- JMS/JCA Integration : <jms-jca-provider>: This provider can be used in place of the <jms-provider> to enable delivery of incoming messages using JCA inflow. This introduces a transacted flow to the action pipeline, and thereby encompasses actions within a JTA transaction.
Table 10.4. JMS Message Filter Configuration
Property Name | Description | Required |
---|---|---|
dest-type | The type of destination, either QUEUE or TOPIC | Yes |
dest-name | The name of the Queue or Topic | Yes |
selector | Allows multiple listeners to register with the same queue/topic which will filter on this message-selector. | No |
persistent | Indicates if the delivery mode for JMS should be persistent or not. Set as true or false. (Default is true.) | No |
acknowledge-mode | The JMS Session acknowledge mode. Can be one of AUTO_ACKNOWLEDGE, CLIENT_ACKNOWLEDGE, DUPS_OK_ACKNOWLEDGE. Default is AUTO_ACKNOWLEDGE | No |
jms-security-principal | JMS destination username. This will be used when creating a connection to the destination. | No |
jms-security-credential | JMS destination password. This will be used when creating a connection to the destination. | No |
<jms-bus busid="quickstartGwChannel"> <jms-message-filter dest-type="QUEUE" dest-name="queue/quickstart_jms_secured_Request_gw" jms-security-principal="esbuser" jms-security-credential="esbpassword"/> </jms-bus>
Table 10.5. JMS Listener configuration
Property Name | Description | Required |
---|---|---|
name | The listener name. | Yes |
busrefid | The ID of the JMS bus on which to listen. | No |
is-gateway | Is this JMS Listener instance a gateway, or is it a message aware listener. | No. Default is false. |
maxThreads | The maximum number of threads to use when listening for messages on the JMS bus. Only relevant if is-gateway is false. | No. Default is 1 |
clientId | Client ID to be associated with the JMS connection. Used to associate a connection and its objects with state maintained on behalf of the client by a provider. (For example, durable subscriptions.) | No. If a clientId is required (e.g. when a durableSubscriptionName is specified), but is not specified, it will default to the listener name. |
durableSubscriptionName | Durable subscription name. | No. Only relevant for JMS Topics. |
10.10. Configuring the File System Provider
Note
Table 10.6. File System Message Filter Configuration
Property | Description | Required |
---|---|---|
directory | The directory that will be monitored for incoming files. | Yes |
input-suffix | Suffix used to filter for incoming files. Must be one character or greater, with a ".", such as ".esbIn". | Yes |
work-suffix | The suffix used when a file is being processed by the ESB. The default is ".esbInProcess". | No |
post-suffix | The suffix used when a file has been successfully processed by the ESB. The default is ".esbDone". | No |
post-delete | If true, the file will be deleted after it is processed. In this case, post-directory and post-suffix have no effect. Defaults to true. | No |
post-directory | The directory to which the file will be moved after it is processed by the ESB. Defaults to the value of directory above. | Yes |
post-rename | If true, the file will be renamed after it is processed. Note that the post-rename and post-delete options are mutually exclusive. | No |
error-delete | If true, the file will be deleted if an error occurs during processing. In this case, error-directory and error-suffix have no effect. This defaults to "true." | No |
error-directory | The FTP directory to which the file will be moved after when an error occurs during processing. This defaults to the value of directory above. | Yes |
error-suffix | The suffix which will be added to the file name after an error occurs during processing. Defaults to .esbError . | No |
10.11. Configuring an FTP Provider
Table 10.7. FTP Provider Configuration
Property | Description | Required |
---|---|---|
hostname | Can be a combination of <host:port> of just <host> which will use port 21. | Yes |
username | Username that will be used for the FTP connection. | Yes |
password | Password for the above user | Yes |
directory | The FTP directory that is monitored for incoming new files | Yes |
input-suffix | The file suffix used to filter files targeted for consumption by the ESB (note: add the dot, so something like '.esbIn'). This can also be specified as an empty string to specify that all files should be retrieved. | Yes |
work-suffix | The file suffix used while the file is being process, so that another thread or process won't pick it up too. Defaults to .esbInProcess. | No |
post-delete | If true, the file will be deleted after it is processed. Note that in that case post-directory and post-suffix have no effect. Defaults to true. | No |
post-directory | The FTP directory to which the file will be moved after it is processed by the ESB. Defaults to the value of directory above. | No |
post-suffix | The file suffix which will be added to the file name after it is processed. Defaults to .esbDone . | No |
error-delete | If true, the file will be deleted if an error occurs during processing. Note that in that case error-directory and error-suffix have no effect. This defaults to "true." | No |
error-directory | The FTP directory to which the file will be moved after when an error occurs during processing. This defaults to the value of directory above. | No |
error-suffix | The suffix which will be added to the file name after an error occurs during processing. Defaults to .esbError . | No |
protocol | The protocol, can be one of:
| No |
passive | Indicates that the FTP connection is in passive mode. Setting this to "true" means the FTP client will establish two connections to the ftpserver. Defaults to false, meaning that the client will tell the FTP Server the port to which it should connect. The FTP Server then establishes the connection to the client. | No |
read-only | If true, the FTP Server does not permit write operations on files. Note that, in this case, the following properties have no effect: work-suffix, post-delete,post-directory, post-suffix, error-delete, error-directory, and error-suffix. Defaults to false. See section Read-only FTP Listener for more information. | No |
certificate-url | The URL to a public server certificate for FTPS server verification or to a private certificate for SFTP client verification. An SFTP certificate can be located as a resource embedded within a deployment artifact | No |
certificate-name | The common name for a certificate for FTPS server verification | No |
certificate-passphrase | The pass-phrase of the private key for SFTP client verification. | No |
Note
Table 10.8. Read-only FTP Listener Configuration
Name | Description |
---|---|
scheduleidref | Schedule used by the FTP listener. See Service Scheduling. |
remoteFileSystemStrategy-class | Override the remote file system strategy with a class that implements: org.jboss.soa.esb.listeners.gateway.remotestrategies.RemoteFileSystemStrategy . Defaults to org.jboss.soa.esb.listeners.gateway.remotestrategies.ReadOnlyRemoteFileSystemStrategy |
remoteFilesystemStrategy-configFile | Specify a JBoss TreeCache configuration file on the local file system or one that exists on the classpath. Defaults to looking for a file named /ftpfile-cache-config.xml which it expects to find in the root of the classpath |
removeFilesystemStrategy-cacheListener | Specifies an JBoss TreeCacheListener implementation to be used with the TreeCache. Default is no TreeCacheListener. |
maxNodes | The maximum number of files that will be stored in the cache. 0 denotes no limit |
timeToLiveSeconds | Time to idle (in seconds) before the node is swept away. 0 denotes no limit |
maxAgeSeconds | Time an object should exist in TreeCache (in seconds) regardless of idle time before the node is swept away. 0 denotes no limit |
<ftp-listener name="FtpGateway" busidref="helloFTPChannel" maxThreads="1" is-gateway="true" schedule-frequency="5"> <property name="remoteFileSystemStrategy-configFile" value="./ftpfile-cache-config.xml"/> <property name="remoteFileSystemStrategy-cacheListener" value= "org.jboss.soa.esb.listeners.gateway.remotestrategies.cache.DeleteOnEvictTreeCacheListener"/> </ftp-listener>
<region name="/ftp/cache"> <attribute name="maxNodes">5000</attribute> <attribute name="timeToLiveSeconds">1000</attribute> <attribute name="maxAgeSeconds">86400</attribute> </region>
Table 10.9. Configuration
Property | Description | Comments |
---|---|---|
maxNodes | The maximum number of files that will be stored in the cache. | 0 denotes no limit |
timeToLiveSeconds | Time to idle (in seconds) before the node is swept away. | 0 denotes no limit |
maxAgeSeconds | Time an object should exist in TreeCache (in seconds) regardless of idle time before the node is swept away | 0 denotes no limit |
Note
10.12. UDP Gateway
10.13. Configuring the UDP Gateway
Table 10.10. UDP Gateway Configuration
Property | Description | Comments |
---|---|---|
Host | The hostname/ip to which to listen. | Mandatory. |
Port | The port to which to listen. | Mandatory. |
handlerClass | A concrete implemenation of org.jboss.soa.esb.listeners.gateway.mina.MessageHandler. | Optional. Default is org.jboss.soa.esb.listeners.gateway.mina.DefaultMessageHandler. |
is-gateway | UDPGatewayListener can only act as a gateway. | Mandatory. |
<udp-listener name="udp-listener" host="localhost" port="9999" handlerClass="org.jboss.soa.esb.listeners.gateway.mina.DefaultMessageHandler" is-gateway="true" <udp-listener/>
10.14. JBoss Remoting Gateway
10.15. Configuring the JBoss Remoting Gateway
<jbr-provider name="socket_provider" protocol="socket" host="localhost"> <jbr-bus busid="socket_bus" port="64111"/> </jbr-provider>
<listeners> <jbr-listener name="soc" busidref="socket_bus" is-gateway="true"/> </listeners>
Important
Table 10.11. Configuration
Name | Description | Default |
---|---|---|
synchronous | Is the target Service to be invoked Synchronously. | True |
serviceInvokerTimeout | Asynchronous invocation timeout. | 20000 |
asyncResponse | Asynchronous response. | "<ack/> |
securityNS | This is the namespace for the version of Web Service Security that should be used. This namespace is used to match security headers in SOAP messages. This is to allow the Enterprise Service Bus to extract security information from these headers. | http://docs.oasis-open.org/wss/2004/01/oasis-200401http-wss-wssecurity-secext-1.0.xsd |
<jbr-provider name="https_provider" protocol="https" host="localhost"> <!-- Https/SSL settings --> <property name="jbr-KeyStoreURL" value="/keys/myKeystore" /> <property name="jbr-KeyStorePassword" value="keys_ssl_pass" /> <property name="jbr-TrustStoreURL" value="/keys/myKeystore" /> <property name="jbr-TrustStorePassword" value="keys_ssl_pass" /> <property name="jbr-ClientAuthMode" value="need" /> <property name="serviceInvokerTimeout" value="20000" /> <jbr-bus busid="https_bus" port="9433"/> </jbr-provider>
Note
Message.Properties
as instances of org.jboss.soa.esb.message.ResponseHeader
class. If you require the Gateway to set specific response headers, the enterprise service bus message provided to the gateway response decompose (for example, after a synchronous invocation of the target service) must contain instances of the ResponseHeader
class, set on the Message.Properties
.
10.17. Configuring the HTTP Gateway
<service category="Vehicles" name="Cars" description="" invmScope="GLOBAL"> <listeners> <http-gateway name="Http" /> </listeners> <actions mep="RequestResponse"> <!-- Service Actions.... --> </actions> </service>
default
HTTP bus provider. This is because it does not define a busrefid attribute. It uses the service category and name to construct the HTTP end-point address of the following format:
http://<host>:<port>/<.esbname>/http/Vehicles/Cars
<service category="Vehicles" name="Cars" description="" invmScope="GLOBAL"> <listeners> <http-gateway name="Http" urlPattern="esb-cars/*" /> </listeners> <actions mep="RequestResponse"> <!-- Service Aactions.... --> </actions> </service>
http://<host>:<port>/<.esbname>/http/esb-cars/*
<http-gateway name="Http" urlPattern="esb-cars/*"> <property name="allowedPorts" value="8080,8081"> </http-gateway>
- http://<host>:8080/*
- http://<host>:8081/*
jbossesb-properties.xml
file's “core:org.jboss.soa.esb.mime.text.types” configuration property to decide whether the payload is to be decoded for the service as a string or whether it is to remain as a byte array, with the service handling the decoding itself through an action.
- text/*
- application/xml
- application/*-xml
HttpRequest requestInfo = HttpRequest.getRequest(message);
Table 10.12. Properties
Property | Description |
---|---|
queryParams | A java.util.Map<String, String[]> containing the query parameters. Note the values are String[] so as to support multi-valued parameters. |
headers | A java.util.List<HttpHeader> containing the request headers. |
authType | The name of the authentication scheme used to protect the endpoint, or null if not authenticated. Same as the value of the CGI variable AUTH_TYPE. |
characterEncoding | The name of the character encoding used in the body of this request, or null if the request does not specify a character encoding. |
contentType | Content Type (MIME Type) of the body of the request, or null if the type is not known. Same as the value of the CGI variable CONTENT_TYPE. |
contextPath | The portion of the request URI that indicates the context of the request. The context path always comes first in a request URI. The path starts with a "/" character but does not end with a "/" character. For endpoints in the default (root) context, this returns "". The container does not decode this string. (See Servlet Spec.) |
pathInfo | Any extra path information associated with the URL the client sent when it made this request. The extra path information follows the endpoint path but precedes the query string and will start with a "/" character. This method returns null if there was no extra path information. Same as the value of the CGI variable PATH_INFO. (See Servlet Spec.) |
pathInfoToken | A List<String> containing the tokens of the pathInfo. |
queryString | Query String (See Servlet Spec) |
requestURI | The part of this request URL from the protocol name up to the query string. The web container does not decode this String. (See Servlet Spec) |
requestPath | The part of this request URL that calls the endpoint. Does not include any additional path information or a query string. Same as the value of the CGI variable SCRIPT_NAME. This method will return just "http") if the urlPattern was "/*". (See Servlet Spec) |
localAddr | The IP address of the interface on which the request was received. |
localName | The host name of the IP interface on which the request was received. |
method | HTTP Method |
protocol | Name and version of the HTTP protocol |
remoteAddr | The IP address of the client or last proxy that sent the request. Same as the value of the CGI variable REMOTE_ADDR. |
remoteHost | The fully qualified name of the client or the last proxy that sent the request. If the engine cannot or chooses not to resolve the hostname (to improve performance), this will be the dotted-string form of the IP address. Same as the value of the CGI variable REMOTE_HOST. |
remoteUser | The login of the user making this request, if the user has been authenticated, or null if the user has not been authenticated. Whether the username is sent along with each subsequent request depends on the client and type of authentication. Same as the value of the CGI variable REMOTE_USER. |
contentLength | The length, in bytes, of the request body and made available by the input stream, or -1 if the length is not known. For HTTP servlets, same as the value of the CGI variable CONTENT_LENGTH. |
requestSessionId | The session ID specified by the client, or null if non specified. |
scheme | Scheme being used, whether it be “http” or “https.”. |
serverName | The host name of the server to which the request was sent. It is the value of the part before ":" in the “Host” header value, if any, or the resolved server name, or the server IP address. |
<listeners> <http-gateway name="Http" urlPattern="esb-cars/*"> <asyncResponse /> </http-gateway> </listeners>
<listeners> <http-gateway name="Http" urlPattern="esb-cars/*"> <asyncResponse statusCode="202" /> </http-gateway> </listeners>
<listeners> <http-gateway name="Http" urlPattern="esb-cars/*"> <asyncResponse statusCode="202"> <payload classpathResource="/202-static-response.xml" content-type="text/xml" characterEncoding="UTF-8" /> <asyncResponse> </http-gateway> </listeners>
Table 10.13.
Property | Description | Required |
---|---|---|
classpathResource |
Specifies the path to a file on the classpath that contains the response payload.
| Required |
contentType |
Specifies the content/mime type of the payload data specified by the classpathResource attribute.
| Required |
characterEncoding |
The character encoding of the data specified by the classpathResource attribute.
| Optional |
HttpResponse responseInfo = new HttpResponse(HttpServletResponse.SC_OK); responseInfo.setContentType("text/xml"); // Set other response info ... // Set the HttpResponse instance on the ESB response Message instance responseInfo.setResponse(responseMessage);
Table 10.14.
Property | Description |
---|---|
responseCode |
The HTTP Response/Status Code (http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html)to be set on the gateway response.
|
contentType |
The response payload MIME Type.
|
encoding |
The response payload content encoding.
|
length |
The response payload content length.
|
headers |
A java.util.List<HttpHeader> containing the request headers.
|
Note
Note
<listeners> <http-gateway name="Http" urlPattern="esb-cars/*"> <property name="synchronousTimeout" value="120000"/> </http-gateway> </listeners>
<http-gateway name="http-gateway"> <exception> <mapping class="com.acme.AcmeException" status="503" /> </exception> </http-gateway>
<http-provider name="http"> <!-- Global exception mappings file... --> <exception mappingsFile="/http-exception-mappings.properties" /> </http-provider>
10.18. Securing the HTTP Gateway
10.19. Secure the HTTP Gateway
Procedure 10.1. Task
- Open the
jbossesb-properties.xml
file in your text editor:vi jbossesb-properties.xml
- Specify a <http-bus> in the <http-provider> section of the file.
- Reference the <http-bus> from the <http-gateway> using the "busrefid" attribute.
Note
See the "http-gateway" quick start for an example of a full configuration. - Save the file and exit.
10.20. Further HTTP Gateway Security
<http-bus busid="secureSalesDeletes"> <allowed-roles> <role name="friend" /> </allowed-roles> <protected-methods> <method name="DELETE" /> </protected-methods> </http-bus>
Table 10.15.
Methods Specified | Roles Specified | Log-in Required |
---|---|---|
No |
No
| No |
No |
Yes
| For All Methods |
Yes |
Yes
| For Specified Methods Only |
Yes |
No
| No. Specified methods blocked to all. |
<http-provider name="http"> <http-bus busid="secureFriends"> <allowed-roles> <role name="friend" /> </allowed-roles> <protected-methods> <method name="DELETE" /> </protected-methods> </http-bus> <auth method="BASIC" domain="java:/jaas/JBossWS" /> </http-provider>
<http-bus busid="secureFriends" transportGuarantee="CONFIDENTIAL"> <!-- etc etc --> </http-bus>
10.21. Apache Camel
10.22. Camel Gateway
10.23. Configuring the Camel Gateway
Note
camel-core.jar
. You will have to add any other dependencies (including other camel-* jars or third party jars) you require into server//deployers/esb.deployer/lib
- not your ESB archive. For more information on using non-core Camel components, see http://community.jboss.org/wiki/CamelGatewayUsingNon-coreComponents/.
jbossesb-1.3.0.xsd
) schema, in your jboss-esb.xml
file, you will see a new <camel-provider> section appear under Providers:
<camel-provider name="..."> <camel-bus busid="..."> <from uri="..."/> <from uri="..."/> </camel-bus> </camel-provider>
<camel-gateway name="..." busidref="..."/>
<camel-gateway name="..."> <from uri=""/> <from uri=""/> </camel-gateway>
<camel-gateway name="..." from-uri="..."/>
<camel-bus name="..." busid="..." from-uri="..."/>
Note
Note
Note
<camel-gateway name="..." from-uri="..." async="false" timeout="30000"/>
- The async attribute (defaults to “false”) says whether the underlying ServiceInvoker should invoke the associated Service synchronously or asynchronously.
- The timeout attribute (defaults to “30000”), defines how many milliseconds the ServiceInvoker should wait on a synchronous invocation before giving up.
Note
10.24. Transitioning from the Old Configuration Model to the New
org.jboss.soa.esb.helpers.ConfigTree
. The new configuration model is XSD-based. However, the underlying component configuration pattern is still through an instance of org.jboss.soa.esb.helpers.ConfigTree. This means that, at the moment, the XSD-based configurations are mapped/transformed into ConfigTree-style configurations.
- Read all of the docs on the new configuration model. Don't assume you can infer the new configurations based on your knowledge of the old.
- The only location where free-form markup is supported in the new configuration is on the <property> element/type. This type is allowed on <provider>, <bus> and <listener> types (and sub-types). However, the only location in which <property> based free form markup is mapped into the ConfigTree configurations is where the <property> exists on an <action>. In this case, the <property> content is mapped into the target ConfigTree <action>. Note however, if you have 1+ <property> elements with free form child content on an <action>, all this content will be concatenated together on the target ConfigTree <action>.
- When developing new Listener/Action components, you must ensure that the ConfigTree based configuration these components depend on can be mapped from the new XSD based configurations. An example of this is how in the ConfigTree configuration model, you could decide to supply the configuration to a listener component via attributes on the listener node, or you could decide to do it based on child nodes within the listener configuration – all depending on how you were feeling on the day. This type of free form configuration on <listener> components is not supports on the XSD to ConfigTree mapping. In other words, the child content in the above example would not be mapped from the XSD configuration to the ConfigTree style configuration. In fact, the XSD configuration simply would not accept the arbitrary content, unless it was in a <property> and even in that case (on a <listener>), it would simply be ignored by the mapping code.
10.25. Configuring the Enterprise Service Bus
org.jboss.soa.esb.parameters.ParamRepositoryFactory
:
public abstract class ParamRepositoryFactory { public static ParamRepository getInstance(); }
org.jboss.soa.esb.parameters.ParamRepository
interface which allows for different implementations:
public interface ParamRepository { public void add(String name, String value) throws ParamRepositoryException; public String get(String name) throws ParamRepositoryException; public void remove(String name) throws ParamRepositoryException; }
org.jboss.soa.esb.parameters.ParamFileRepository
) which expects to be able to load the parameters from a file. The implementation to use this may be over-ridden using the org.jboss.soa.esb.paramsRepository.class
property.
Note
Chapter 11. Data Decoding: Mime Decoders
11.1. Message Composer
MessageComposer
interface and is responsible for constructing an ESB message instance and sending it to the associated service. The Message Coder is supported by every time of gateway.
11.2. Mime Decoder
MimeDecoder
interface. It can be used by a MessageComposer
implementation to decode a binary array, transforming it into a specific type of Java Object. (The type of object is determined by the “mime type” of the binary-encoded data.)
11.3. Implement a Mime Decoder
Procedure 11.1. Task
- Create a class that activates the
org.jboss.soa.esb.listeners.message.mime.MimeDecoder
interface. - Add the @MimeType annotation to the class, specifying the mime type as the annotation value.
- Define the newly created class in the
META-INF/org/jboss/soa/esb/listeners/message/mime/decoders.lst
file:@MimeType("text/plain") public class TextPlainMimeDecoder implements MimeDecoder, Configurable { private Charset encodingCharset; public void setConfiguration(ConfigTree configTree) throws ConfigurationException { AssertArgument.isNotNull(configTree, "configTree"); String encoding = configTree.getAttribute("encoding", "UTF-8"); encodingCharset = Charset.forName(encoding); } public Object decode(byte[] bytes) throws MimeDecodeException { try { return new String(bytes, encodingCharset.name()); } catch (UnsupportedEncodingException e) { throw new MimeDecodeException("Unexpected character encoding error.", e); } } }
Note
This file needs to be present on the classpath at runtime. If your module doesn't have this file, add it to your module source/resources and it will be located at runtime. - Optionally, if the MimeDecoder implementation needs access to the listener configuration (for additional configuration information), have the class implement the
org.jboss.soa.esb.Configurable
interface.
11.4. ConfigTree
jboss-esb.xml
file.
11.5. Mime Decoder Implementations Available Out-of-the-Box
- text/plain
- The TextPlainMimeDecoder handles “text/plain” data, decoding a byte[] to a String (default) or char[].
Table 11.1. Properties
Property | Description | Comments |
---|---|---|
encoding |
Character encoding of the text/plain data encoded in the byte[].
| Default “UTF-8” |
decodeTo |
How the text/plain data is to be decoded:
| Default “STRING” |
11.6. Using Mime Decoders in Gateway Implementations
MimeDecoder.Factory
class factory method:
this.mimeDecoder = MimeDecoder.Factory.getInstanceByConfigTree(config);
<fs-listener name="FileGateway1" busidref="fileChannel1" is-gateway="true" poll-frequency-seconds="10"> <property name="mimeType" value="text/plain" /> <property name="encoding" value="UTF-8" /> </fs-listener> <fs-listener name="FileGateway2" busidref="fileChannel2" is-gateway="true" poll-frequency-seconds="10"> <property name="mimeDecoder" value="com.acme.mime.ImageJPEGMimeDecoder” /> </fs-listener>
Object decodedPayload = mimeDecoder.decode(payloadBytes);
Chapter 12. Web Services Support
12.1. JBoss Web Services
12.2. JBoss Web Services Support
- SOAPProcessor: The SOAPProcessor action allows you to expose JBossWS 2.x and higher web service end-points through endpoints (listeners) running on the ESB (“SOAP onto the bus”). This allows you to use JBossESB to expose web service end-points (wrapper web services) for services that don't expose a web service Interface.
- SOAPClient: The SOAPClient action allows you to make invocations on web service endpoints (“SOAP off the bus”).
Chapter 13. Actions Available for Use Out of the Box
13.1. Out-of-the-Box Actions
13.2. JBoss Enterprise SOA Platform Out-of-the-Box Actions
- Transformers and Converters
- Use transformer and converter actions to change message data from one form to another.
- Business Process Management
- Use the business process management actions when integrating your software with the jBPM.
- Scripting
- Use scripting actions to automate tasks written in the supported scripting languages.
- Services
- Use service actions when integrating your code with Enterprise Java Beans.
- Routing
- Use routing actions when moving message data to destination services.
- Notifier
- Use notifier actions when sending data to ESB-unaware destinations.
- Web Services/SOAP
- Use web service actions when you need to support web services.
13.3. Transformer Actions
13.3.1. Transformers
13.3.2. ByteArrayToString
Input Type | byte[ ] |
Class | org.jboss.soa.esb.actions.converters.ByteArrayToString |
byte[]
based message payload and converts it into a java.lang.String
object instance.
Table 13.1. ByteArrayToString Properties
Property | Description | Required |
---|---|---|
encoding |
The binary data encoding on the message byte array. Defaults to
UTF-8 .
| No |
Example 13.1. Sample Configuration
<action name="transform" class="org.jboss.soa.esb.actions.converters.ByteArrayToString"> <property name="encoding" value="UTF-8" /> </action>
13.3.3. LongToDateConverter
Input Type
| java.lang.Long /long
|
Output Type
| java.util.Date
|
Class
| org.jboss.soa.esb.actions.converters.LongToDateConverter
|
java.util.Date
object instance.
Example 13.2. Sample Configuration
<action name="transform" class="org.jboss.soa.esb.actions.converters.LongToDateConverter">
13.3.4. ObjectInvoke
Input Type | User Object |
Output Type | User Object |
Class | org.jboss.soa.esb.actions.converters.ObjectInvoke |
Table 13.2. ObjectInvoke Properties
Property | Description | Required |
---|---|---|
class-processor |
The runtime class name of the processor class used to process the message payload.
| Yes |
class-method |
The name of the method on the processor class used to process the method.
| No |
Example 13.3. Sample Configuration
<action name="invoke" class="org.jboss.soa.esb.actions.converters.ObjectInvoke"> <property name="class-processor" value="org.jboss.MyXXXProcessor"/> <property name="class-method" value="processXXX" /> </action>
13.3.5. ObjectToCSVString
Input Type | User Object |
Output Type | java.lang.String |
Class | org.jboss.soa.esb.actions.converters.ObjectToCSVString |
Table 13.3. ObjectToCSVString Properties
Property | Description | Required |
---|---|---|
bean-properties |
List of Object bean property names used to get CSV values for the output CSV String. The Object should support a getter method for each of listed properties.
| Yes |
fail-on-missing-property |
Flag indicating whether or not the action should fail if a property is missing from the Object, that is if the Object does not support a getter method for the property. Default value is
false .
| No |
Example 13.4. Sample Configuration
<action name="transform" class="org.jboss.soa.esb.actions.converters.ObjectToCSVString"> <property name="bean-properties" value="name,address,phoneNumber"/> <property name="fail-on-missing-property" value="true" /> </action>
13.3.6. ObjectToXStream
Input Type | User Object |
Output Type | java.lang.String |
Class | org.jboss.soa.esb.actions.converters.ObjectToXStream |
Table 13.4. ObjectToXStream Properties
Property | Description | Required |
---|---|---|
class-alias |
Class alias used in call to
XStream.alias(String, Class) prior to serialization. Defaults to the input Object's class name.
| No |
exclude-package |
Exclude the package name from the generated XML. Default is
true . Not applicable if a class-alias is specified.
| No |
aliases |
Specify additional aliases in order to help XStream to convert the XML elements into Objects.
| No |
namespaces |
Specify namespaces that should be added to the XML generated by XStream. Each namespace-uri is associated with a local-part which is the element on which this namespace should appear.
| No |
xstream-mode |
Specify the XStream mode to use. Possible values are
XPATH_RELATIVE_REFERENCES (the default), XPATH_ABSOLUTE_REFERENCES , ID_REFERENCES or NO_REFERENCES .
| No |
fieldAliases |
Field aliases to be added to Xstream.
| No |
implicit-collections |
Which will be registered with Xstream
| No |
converters |
List of converters that will be registered with Xstream
| No |
Example 13.5. Sample Configuration
<action name="transform" class="org.jboss.soa.esb.actions.converters.ObjectToXStream"> <property name="class-alias" value="MyAlias" /> <property name="exclude-package" value="true" /> <property name="aliases"> <alias name="alias1" class="com.acme.MyXXXClass1" /> <alias name="alias2" class="com.acme.MyXXXClass2" /> <alias name="xyz" class="com.acme.XyzValueObject"/> <alias name="x" class="com.acme.XValueObject"/> ... </property> <property name="namespaces"> <namespace namespace-uri="http://www.xyz.com" local-part="xyz"/> <namespace namespace-uri="http://www.xyz.com/x" local-part="x"/> ... </property> <property name="fieldAliases"> <field-alias alias="aliasName" definedIn="className" fieldName="fieldName"/> <field-alias alias="aliasName" definedIn="className" fieldName="fieldName"/> ... </property> <property name="implicit-collections"> <implicit-collection class="className" fieldName="fieldName" fieldType="fieldType" itemType="itemType"/> ... </property> <property name="converters"> <converter class="className" fieldName="fieldName" fieldType="fieldType"/> ... </property> </action>
13.3.7. XStreamToObject
Input Type | java.lang.String |
Output Type | User Object (specified by "incoming-type" property) |
Class | org.jboss.soa.esb.actions.converters.XStreamToObject |
Table 13.5. XStreamToObject Properties
Property | Description | Required |
---|---|---|
class-alias |
Class alias used during serialization. Defaults to the input Object's class name.
| No |
exclude-package |
Flag indicating whether or not the XML includes a package name.
| YES |
incoming-type |
Class type.
| Yes |
root-node |
Specify a different root node than the actual root node in the XML. Takes an XPath expression.
| No |
aliases |
Specify additional aliases to help XStream to convert the XML elements to Objects
| No |
attribute-aliases |
Specify additional attribute aliases to help XStream to convert the XML attributes to Objects
| No |
fieldAliases |
Field aliases to be added to Xstream.
| No |
implicit-collections |
Which will be registered with Xstream
| No |
converters |
Specify converters to help Xstream to convert the XML elements and attributes to Objects.
| No |
Example 13.6. Sample Configuration
<action name="transform" class="org.jboss.soa.esb.actions.converters.XStreamToObject"> <property name="class-alias" value="MyAlias" /> <property name="exclude-package" value="true" /> <property name="incoming-type" value="com.acme.MyXXXClass" /> <property name="root-node" value="/rootNode/MyAlias" /> <property name="aliases"> <alias name="alias1" class="com.acme.MyXXXClass1/> <alias name="alias2" class="com.acme.MyXXXClass2/> ... </property> <property name="attribute-aliases"> <attribute-alias name="alias1" class="com.acme.MyXXXClass1"/> <attribute-alias name="alias2" class="com.acme.MyXXXClass2"/> ... </property> <property name="fieldAliases"> <field-alias alias="aliasName" definedIn="className" fieldName="fieldName"/> <field-alias alias="aliasName" definedIn="className" fieldName="fieldName"/> ... </property> <property name="implicit-collections"> <implicit-colletion class="className" fieldName="fieldName" fieldType="fieldType" itemType="itemType"/> ... </property> <property name="converters"> <converter class="className" fieldName="fieldName" fieldType="fieldType"/> ... </property> </action>
13.3.8. XsltAction
Table 13.6. XsltAction
Properties
Property | Description | Required |
---|---|---|
get-payload-location
|
Message Body location containing the message payload.
If unspecified the Default Payload Location is used.
|
NO
|
set-payload-location
|
Message Body location where result payload is to be placed.
If unspecified the Default Payload Location is used.
|
No
|
templateFile
|
Path to the XSL Template file. It can be defined with a file path within the deployed archive, or as a URL.
|
Yes
|
resultType
|
The type of Result to be set as the result Message payload.
This property controls the output result of the transformation. The following values are currently available:
When the message payload is a
SourceResult object and resultType is not set to SOURCERESULT , the result is returned as the type specified in resultType. The developer is responsible for ensuring the types are compatible.
|
No
|
failOnWarning
|
If
true will cause a transformation warning to cause an exception to be thrown. If false the failure will be logged.
Defaults to True.
|
No
|
uriResolver
|
Fully qualified class name of a class that implements
URIResolver . This will be set on the tranformation factory.
|
No
|
factory.feature.*
|
Factory features that will be set for the tranformation factory. The feature name, which are fully qualified URIs, should be specified after the factory.feature. prefix. E.g. factory.feature.http://javax.xml.XMLConstants/feature/secure-processing
|
No
|
Factory.attribute.*
|
Factory attributes that will be set for the tranformation factory. The attribute name should be specified after the factory.attribute. prefix. E.g. factory.attribute.someVendorAttributename
|
NO
|
validation |
If true will cause an invalid source document to cause an exception to be thrown. If false validation will not occur, although well-formed documents are enforced. .
Default value is
. false
| No |
schemaFile |
The input schema file (XSD) to use, located on the classpath. .
| No |
schemaLanguage |
The input schema language to use.
| No |
13.3.9. Validating XsltActions
- Disabled (the default)This can be explicitly configured to
false
or omitted to disable validation.<property name="validation" value="false"/>
- DTD
<property name="validation" value="true"/> <property name="schemaLanguage" value="http://www.w3.org/TR/REC-xml"/>
Alernatively:<property name="validation" value="true"/> <property name="schemaLanguage" value=""/>
- W3C XML Schema or RELAX NG
<property name="validation" value="true"/>
Alternatively:<property name="validation" value="true"/> <property name="schemaLanguage" value="http://www.w3.org/2001/XMLSchema"/>
or<property name="validation" value="true"/> <property name="schemaLanguage" value="http://relaxng.org/ns/structure/1.0"/>
- W3C XML Schema or RELAX NG with included schemaFile
<property name="validation" value="true"/> <property name="schemaFile" value="/example.xsd"/>
or<property name="validation" value="true"/> <property name="schemaLanguage" value="http://www.w3.org/2001/XMLSchema"/> <property name="schemaFile" value="/example.xsd"/>
Aleternatively:<property name="validation" value="true"/> <property name="schemaLanguage" value="http://relaxng.org/ns/structure/1.0"/> <property name="schemaFile" value="/example.rng"/>
- If the XML is well-formed and valid:
- The transformation will be performed.
- The pipeline will continue.
- If the XML is malformed:
- an error will be logged
- SAXParseException -> ActionProcessingException
- pipeline stops
- If the XML is well-formed but invalid:
- If validation is not enabled:
- The transformation may fail.
- The pipeline will continue.
- If validation is enabled:
- an error will be logged
- SAXParseException -> ActionProcessingException
- pipeline stops
13.3.10. Smooks
13.3.11. Using Smooks
- Use the
SmooksAction
component to "plug" Smooks into an ESB action pipeline.Note
You will find a number of quick-starts that demonstrate transformations in thesamples/quick starts
directory. (The name of each transformation of these quick starts is prefixed with the wordtransform_
.)
13.3.12. SmooksTransformer
Important
Class | org.jboss.soa.esb.actions.converters.SmooksTransformer |
Table 13.7. SmooksTransformer Resource Configuration
Property | Description | Required |
---|---|---|
resource-config |
The
Smooks resource configuration file.
| Yes |
Table 13.8. SmooksTransformer Message Profile Properties (Optional)
Property | Description | Required |
---|---|---|
from |
Message Exchange Participant name. Message Producer.
| No |
from-type |
Message type/format produced by the "from" message exchange participant.
| No |
to |
Message Exchange Participant name. Message Consumer.
| No |
to |
Message Exchange Participant name. Message Consumer.
| No |
to-type |
Message type/format consumed by the “to” message exchange participant.
| No |
Message.Properties
class).
Example 13.7. Sample Configuration: Default Input/Output
<action name="transform" class="org.jboss.soa.esb.actions.converters.SmooksTransformer"> <property name="resource-config" value="/smooks/config-01.xml" /> </action>
Example 13.8. Sample Configuration: Named Input/Output
<action name="transform" class="org.jboss.soa.esb.actions.converters.SmooksTransformer"> <property name="resource-config" value="/smooks/config-01.xml" /> <property name="get-payload-location" value="get-order-params" /> <property name="set-payload-location" value="get-order-response" /> </action>
Example 13.9. Sample Configuration: Using Message Proiles
<action name="transform" class="org.jboss.soa.esb.actions.converters.SmooksTransformer"> <property name="resource-config" value="/smooks/config-01.xml" /> <property name="from" value="DVDStore:OrderDispatchService" /> <property name="from-type" value="text/xml:fullFillOrder" /> <property name="to" value="DVDWarehouse_1:OrderHandlingService" /> <property name="to-type" value="text/xml:shipOrder" /> </action>
Message.Body
under their beanId.
13.3.13. SmooksAction
org.jboss.soa.esb.smooks.SmooksAction
class is the second generation action class for executing Smooks processes. (Note that it can do more than just transform messages).
Important
Example 13.10. SmooksAction
<action name="transform" class="org.jboss.soa.esb.smooks.SmooksAction"> <property name="smooksConfig" value="/smooks/order-to-java.xml" /> </action>
Table 13.9. SmooksAction Optional Configuration Properties
Property | Description | Default |
---|---|---|
get-payload-location |
Message Body location containing the message payload.
| Default Payload Location |
set-payload-location |
Message Body location where result payload is to be placed.
| Default Payload Location |
mappedContextObjects |
Comma separated list of Smooks ExecutionContext objects to be mapped into the EXECUTION_CONTEXT_ATTR_MAP_KEY Map on the ESB Message Body. Default is an empty list. Objects must be Serializable.
| |
resultType |
The type of Result to be set as the result Message payload.
| STRING |
javaResultBeanId |
Only relevant when
resultType=JAVA
The Smooks bean context beanId to be mapped as the result when the resultType is "JAVA". If not specified, the whole bean context bean Map is mapped as the JAVA result.
| |
reportPath |
The path and file name for generating a Smooks Execution Report. This is a development aid and should not to be used in production.
|
MessagePayloadProxy
class to obtain and set the payload onto the message. Therefore, unless otherwise configured via the get-payload-location and set-payload-location action properties, the SmooksAction obtains and sets the Message payload on the default message location by using the Message.getBody().get() and Message.getBody().set(Object) methods.
13.3.14. Use SmooksAction to Process XML, EDI, CSV and "Other Type" Message Payloads
Procedure 13.1. Task
- Supply a source message. It must be one of the following:
- String,
- InputStream,
- Reader, or
- byte array
- Configure Smooks (via the Smooks configuration file, not the Enterprise Service Bus configuration file) for processing the message type in question. For example, configure a parser if you are not dealing with an XML Source (such as EDI or CSV).
13.3.15. Specifying the SmooksAction Result Type
<action name="transform" class="org.jboss.soa.esb.smooks.SmooksAction"> <property name="smooksConfig" value="/smooks/order-to-java.xml" /> <property name="resultType" value="JAVA" /> <property name="javaResultBeanId" value="order" /> </action>
13.3.16. PersistAction
Input Type | Message |
Output Type | The input Message |
Class | org.jboss.soa.esb.actions.MessagePersister |
Table 13.10. PersistAction Properties
Property | Description | Required |
---|---|---|
classification |
This is used to classify where the Message will be stored. If the Message Property
org.jboss.soa.esb.messagestore.classification is defined on the message, it will be used instead. Otherwise, a default may be provided at instantiation time.
| Yes |
message-store-class |
The implementation of the
MessageStore .
| Yes |
terminal |
If the Action is to be used to terminate a pipeline then this should be "true" (the default). If not, then set this to "false" and the input message will be returned from processing.
| No |
<action name="PersistAction" class="org.jboss.soa.esb.actions.MessagePersister"> <property name="classification" value="test"/> <property name="message-store-class" value="org.jboss.internal.soa.esb.persistence.format.db.DBMessageStoreImpl"/> </action>
13.4. Business Process Management Actions
13.4.1. jBPM
13.4.2. JBPM Integration
13.4.3. jBPM BpmProcessor
Input Type | org.jboss.soa.esb.message.Message generated by AbstractCommandVehicle.toCommandMessage() |
Output Type | Message – same as the input message |
Class | org.jboss.soa.esb.services.jbpm.actions.BpmProcessor |
- NewProcessInstanceCommand
- StartProcessCommand
- CancelProcessInstanceCommand
- GetProcessInstanceVariablesCommand
Table 13.11. BpmProcessor Properties
Property | Description | Required |
---|---|---|
command |
The jBPM command being invoked. Required Allowable values:
| Yes |
processdefinition |
Required property for the New- and Start-ProcessInstanceCommands if the process-definition-id property is not used. The value of this property should reference a process definition that is already deployed to jBPM and of which you want to create a new instance. This property does not apply to the Signal- and CancelProcessInstance-Commands.
| Depends |
process-definition-id |
Required property for the New- and Start-ProcessInstanceCommands if the processdefinition property is not used. The value of this property should reference a processdefintion id in jBPM of which you want to create a new instance. This property does not apply to the Signal- and CancelProcessInstance commands.
| Depends |
actor |
Optional property to specify the jBPM actor id, which applies to the New- and StartProcessInstanceCommands only.
| No |
key |
Optional property to specify the value of the jBPM key. For example one can pass a unique invoice id as the value for this key. On the jBPM side this key is as the “business” key id field. The key is a string based business key property on the process instance. The combination of business key and process definition must be unique if a business key is supplied. The key value can hold an MVEL expression to extract the desired value from the EsbMessage. For example if you have a named parameter called “businessKey” in the body of your message you would use “body.businessKey”. Note that this property is used for the New- and StartProcessInstanceCommands only
| No |
transition-name |
Optional property. This property only applies to the StartProcessInstance- and Signal Commands, and is of use only if there are more then one transition out of the current node. If this property is not specified, the default transition out of the node is taken. The default transition is the first transition in the list of transition defined for that node in the jBPM processdefinition.xml.
| No |
esbToBpmVars |
Optional property for the New- and StartProcessInstanceCommands and the SignalCommand. This property defines a list of variables that need to be extracted from the EsbMessage and set into jBPM context for the particular process instance. The list consists of mapping elements. Each mapping element can have the following attributes:
| No |
13.5. Scripting Actions
13.5.1. Scripting Actions
13.5.2. Groovy
13.5.3. GroovyActionProcessor
Class | org.jboss.soa.esb.actions.scripting.GroovyActionProcessor |
Table 13.12. GroovyActionProcessor Properties
Property | Description | Required |
---|---|---|
script |
Path (on classpath) to Groovy script.
| |
supportMessageBasedScripting |
Allow scripts within the message.
| |
cacheScript |
Should the script be cached. Defaults to
true .
| No |
Table 13.13. GroovyAction Processor Script Binding Variables
Variable | Description |
---|---|
message |
The Message
|
payloadProxy |
Utility for message payload (MessagePayloadProxy).
|
config |
The action configuration (ConfigTree).
|
logger |
The GroovyActionProcessor's static Log4J logger (Logger). The logging category is jbossesb.<esb_archive_name>.<category>.<service>
|
<action name="process" class="org.jboss.soa.esb.scripting.GroovyActionProcessor"> <property name="script" value="/scripts/myscript.groovy"/> </action>
13.5.4. Bean Scripting Framework (BSF)
13.5.5. ScriptingAction
Class | org.jboss.soa.esb.actions.scripting.ScriptingAction |
- The Bean Scripting Framework does not provide an API to precompile, cache and reuse scripts. Because of this, each execution of the ScriptingAction will go through the compile step again. Please keep this in mind while evaluating your performance requirements.
- When including BeanShell scripts in your application, Red Hat advises you should use a .beanshell extension instead of .bsh, otherwise the JBoss BSHDeployer might pick it up.
Table 13.14. ScriptingAction Properties
Property | Description | Required |
---|---|---|
script |
Path (on classpath) to script.
| |
supportMessageBasedScripting |
Allow scripts within the message.
| |
language |
Optional script language (overrides extension deduction).
| No |
Table 13.15. ScriptingAction Processor Script Binding Variables
Variable | Description |
---|---|
message |
The Message
|
payloadProxy |
Utility for message payload (MessagePayloadProxy)
|
config |
The action configuration (ConfigTree)
|
logger |
The ScriptingAction's static Log4J logger (Logger)
|
<action name="process" class="org.jboss.soa.esb.scripting.ScriptingAction"> <property name="script" value="/scripts/myscript.beanshell"/> </action>
13.6. Service Actions
13.6.1. Service Actions
13.6.2. EJBProcessor
Input Type | EJB method name and parameters |
Output Type | EJB specific object |
Class | org.jboss.soa.esb.actions.EJBProcessor |
Table 13.16. EJBProcessor Properties
Property | Description | Required |
---|---|---|
ejb3 |
When calling to an EJB3.x session bean.
| |
ejb-name |
The identity of the EJB. Optional when ejb3 is true.
| |
jndi-name |
Relevant JNDI lookup.
| |
initial-context-factory |
JNDI lookup mechanism.
| |
provider-url |
Relevant provider.
| |
method |
EJB method name to call.
| |
lazy-ejb-init |
Whether EJBs should be lazily initialised at runtime rather than at deploy time. Default is false.
| No |
ejb-params |
The list of parameters to use when calling the method and where in the input Message they reside.
| |
esb-out-var |
The location of the output. Default value is DEFAULT_EJB_OUT.
| No |
Example 13.11. Sample Configuration for EJB 2.x
<action name="EJBTest" class="org.jboss.soa.esb.actions.EJBProcessor"> <property name="ejb-name" value="MyBean" /> <property name="jndi-name" value="ejb/MyBean" /> <property name="initial-context-factory" value="org.jnp.interfaces.NamingContextFactory" /> <property name="provider-url" value="localhost:1099" /> <property name="method" value="login" /> <!-- Optional output location, defaults to "DEFAULT_EJB_OUT" <property name="esb-out-var" value="MY_OUT_LOCATION"/> --> <property name="ejb-params"> <!-- arguments of the operation and where to find them in the message --> <arg0 type="java.lang.String">username</arg0> <arg1 type="java.lang.String">password</arg1> </property> </action>
Example 13.12. Sample Configuration for EJB 3.x
<action name="EJBTest" class="org.jboss.soa.esb.actions.EJBProcessor"> <property name="ejb3" value="true" /> <property name="jndi-name" value="ejb/MyBean" /> <property name="initial-context-factory" value="org.jnp.interfaces.NamingContextFactory" /> <property name="provider-url" value="localhost:1099" /> <property name="method" value="login" /> <!-- Optional output location, defaults to "DEFAULT_EJB_OUT" <property name="esb-out-var" value="MY_OUT_LOCATION"/> --> <property name="ejb-params"> <!-- arguments of the operation and where to find them in the message --> <arg0 type="java.lang.String">username</arg0> <arg1 type="java.lang.String">password</arg1> </property> </action>
13.7. Routing Actions
13.7.1. Routing Actions
13.7.2. Aggregator
Class | org.jboss.soa.esb.actions.Aggregator |
[UUID] ":" [message-number] ":" [message-count]
Table 13.17. Aggregator Properties
Property | Description | Required |
---|---|---|
timeoutInMillis |
Timeout time in milliseconds before the aggregation process times out.
| No |
<action class="org.jboss.soa.esb.actions.Aggregator" name="Aggregator"> <property name="timeoutInMillies" value="60000"/> </action>
13.7.3. Streaming Aggregator
Class | org.jboss.soa.esb.actions.StreamingAggregator |
org.jboss.soa.esb.actions.aggregator.AggregateDetails
object.
[SeriesUUID] ":" [message-sequence] ":" [sequence-count]
Table 13.18. Aggregator Properties
Property | Description | Required |
---|---|---|
timeoutInMillis |
Timeout time in milliseconds before the aggregation process times out.
| No |
<action class="org.jboss.soa.esb.actions.StreamingAggregator" name="Aggregator"> <property name="timeoutInMillies" value="60000"/> </action>
13.7.4. EchoRouter
13.7.5. HttpRouter
Class | org.jboss.soa.esb.actions.routing.http.HttpRouter |
Table 13.19. Apache Commons HttpRouter
Property | Description | Required |
---|---|---|
unwrap |
Setting this to
true (the default) will extract the message payload from the Message object before sending. false will send the serialized Message as either XML or Base64 encoded JavaSerialized object, based on the MessageType.
| No |
endpointUrl |
The endpoint to which the message will be forwarded.
| Yes |
http-client-property |
The HttpRouter uses the HttpClientFactory to create and configure the HttpClient instance. You can specify the configuration of the factory by using the file property which will point to a properties file on the local file system, classpath or URI based. See example below to see how this is done.
| No |
method |
Currently only supports GET and POST.
| Yes |
responseType |
Specifies in what form the response should be sent back. Either STRING or BYTES. Default value is STRING.
| No |
headers |
To be added to the request. Supports multiple <header name="test" value="testvalue" /> elements.
| No |
MappedHeaderList |
A comma separated list of header names that should be propagated to the target endpoint. The value for the headers will be retrieved from those present on a request entering the enterprise service bus via the http-gateway or within the properties of the current message.
| No |
<action name="httprouter" class="org.jboss.soa.esb.actions.routing.http.HttpRouter"> <property name="endpointUrl"value="http://host:80/blah"> <http-client-property name="file" value="/ht.props"/> </property> <property name="method" value="GET"/> <property name="responseType" value="STRING"/> <property name="headers"> <header name="blah" value="blahval" ></header> </property> </action>
13.7.6. Java Message Service
13.7.7. JMSRouter
Class | org.jboss.soa.esb.actions.routing.JMSRouter |
Table 13.20. JMSRouter
Property | Description | Required |
---|---|---|
unwrap |
Setting this to
true will extract the message payload from the Message object before sending. false (the default) will send the serialized Message object.
| No |
jndi-context-factory |
The JNDI context factory to use. The default is
org.jnp.interfaces.NamingContextFactory .
| No |
jndi-URL |
The JNDI URL to use. The default is
127.0.0.1:1099 .
| No |
jndi-pkg-prefix |
The JNDI naming package prefixes to use. The default is
org.jboss.naming:org.jnp.interfaces
| No |
connection-factory |
The name of the ConnectionFactory to use. Default is
ConnectionFactory .
| No |
persistent |
The JMS DeliveryMody,
true (the default) or false .
| No |
priority |
The JMS priority to be used. Default is
javax.jms.Message.DEFAULT_PRIORITY .
| No |
time-to-live |
The JMS Time-To-Live to be used. The default is
javax.jms.Message.DEFAULT_TIME_TO_LIVE .
| No |
security-principal |
The security principal to use when creating the JMS connection.
| Yes |
security-credentials |
The security credentials to use when creating the JMS connection.
| Yes |
property-strategy |
The implementation of the JMSPropertiesSetter interface, if overriding the default.
| No |
message-prop |
Properties to be set on the message are prefixed with
message-prop .
| No |
jndi-prefixes |
A comma separated String of of prefixes. Properties that have these prefixes will be added to the JNDI environment.
| No |
13.7.8. EmailRouter
Class | org.jboss.soa.esb.actions.routing.email.EmailRouter |
Table 13.21. EmailRouter Properties
Property | Description | Required |
---|---|---|
unwrap |
true will extract the message payload from the Message object before sending. false (the default) will send the serialized Message object.
| |
host |
The host name of the SMTP server. If not specified will default to the property 'org.jboss.soa.esb.mail.smtp.host' in jbossesb-properties.xml.
| |
port |
The port for the SMTP server. If not specified will default to the property 'org.jboss.soa.esb.mail.smtp.port' in jbossesb-properties.xml.
| |
username |
The username for the SMTP server. If not specified will default to the property 'org.jboss.soa.esb.mail.smtp.user' in jbossesb-properties.xml.
| |
password |
The password for the above username on the SMTP server. If not specified will default to the property 'org.jboss.soa.esb.mail.smtp.password' in jbossesb-properties.xml.
| |
auth |
If true will attempt to authenticate the user using the AUTH command. If not specified will default to the property 'org.jboss.soa.esb.mail.smtp.auth' in jbossesb-properties.xml
| |
from |
The from email address.
| |
sendTo |
The destination email account.
| |
subject |
The subject of the email.
| |
messageAttachmentName |
filename of an attachment containing the message payload (optional). If not specified the message payload will be included in the message body.
| |
message |
a string to be prepended to the ESB message contents which make up the e-mail message (optional)
| |
ccTo |
comma-separated list of email addresses (optional)
| |
attachment |
Child elements that contain files that will be added as attachments to the email sent.
|
<action name="send-email" class="org.jboss.soa.esb.actions.routing.email.EmailRouter"> <property name="unwrap" value="true" /> <property name="host" value="smtpHost" /> <property name="port" value="25" /> <property name="username" value="smtpUser" /> <property name="password" value="smtpPassword" /> <property name="from" value="jbossesb@xyz.com" /> <property name="sendTo" value="system2@xyz.com" /> <property name="subject" value="Message Subject" /> </action>
13.7.9. Content-Based Router
13.7.10. The RegexProvider
13.7.11. XPath Domain-Specific Language
Note
- First, define the expressions in the
XPathLanguage.dsl
file and use the following code to reference it in the rule set:expander XPathLanguage.dsl
- The XPath Language makes sure the message is in
JBOSS_XML
and that the following items have been defined:xpathMatch
<element> : this yieldstrue
if an element by this name is matched.xpathEquals
<element> , <value> : this yieldstrue
if the element is found and its value equals the value.xpathGreaterThan
<element> , <value> : this yieldstrue
if the element is found and its value is greater than the value.xpathLessThan
<element> , <value> : this yieldstrue
if the element is found and its value is lower then the value.
Note
Thefun_cbr
quick-start demonstrates this use of XPath.Note
It is possible to define a completely different domain-specific language.
13.7.12. ContentBasedRouter
Class | org.jboss.soa.esb.actions.ContentBasedRouter |
- XPath: Simple XPath rules, defined inline on the action, or externally in a .properties format file.
- Drools: Drools rules files (DSL). Out of the box support for an XPath based DSL.
Table 13.22. ContentBasedRouter Properties
Property | Description | Required |
---|---|---|
cbrAlias |
Content Based Routing Provider alias. Supported values are "Drools" (default), "Xpath" and "Regex".
| |
ruleSet |
Externally defined rule file. It will be a Drools DSL file if the Drools rule provider is in use, or a .properties rule file if the XPath or Regex provider is in use.
| |
ruleLanguage |
CBR evaluation Domain Specific Language (DSL) file. Only relevant for the Drools rule provider.
| |
ruleReload |
Flag indicating whether or not the rules file should be reloaded each time. Default is “false”.
| |
ruleAuditType |
Optional property to have Drools perform audit logging. The log can be read into the Drools Eclipse plugin and inspected. Valid values are CONSOLE, FILE and THREADED_FILE. The default is that no audit logging will be performed.
| |
ruleAuditFile |
Optional property to define the filepath for audit logging. Only applies to FILE or THREADED_FILE ruleAuditType. The default is "event". Note that JBoss Drools will append ".log" for you. The default location for this file is "." - the current working directory (which for JBoss is in its bin/ directory).
| |
ruleAuditInterval |
Optional property to define how often to flush audit events to the audit log. Only applies to the THREADED_FILE ruleAuditType. The default is 1000 (milliseconds).
| |
destinations |
Container property for the <route-to> configurations. If the rules are defined externally, this configuration will have the following format:
<route-to destination-name="express" service-category="ExpressShipping" service-name="ExpressShippingService"/>
If the rules are defined inline in the configuration, this configuration will have the following format (not supported for the Drools provider):
<route-to service-category="ExpressShipping" service-name="ExpressShippingService" expression="/order[@statusCode='2']" /> | |
namespaces |
Container property for the <namespace> configurations where required (for example, for the XPath ruleprovider). The <namespace> configurations have the following format:
<namespace prefix="ord" uri="http://acme.com/order" /> |
Table 13.23. ContentBasedRouter "process" methods
Property | Description | Required |
---|---|---|
process |
Do not append aggregation data to the message.
| |
split |
Append aggregation data to the message.
|
Example 13.13. Sample Configuration XPATH (inline)
<action process="split" name="ContentBasedRouter" class="org.jboss.soa.esb.actions.ContentBasedRouter"> <property name="cbrAlias" value="XPath"/> <property name="destinations"> <route-to service-category="ExpressShipping" service-name="ExpressShippingService" expression="/order['status='1']" /> <route-to service-category="NormalShipping" service-name="NormalShippingService" expression="/order['status='2']" /> </property> </action>
Example 13.14. Sample Configuration XPATH (external)
<action process="split" name="ContentBasedRouter" class="org.jboss.soa.esb.actions.ContentBasedRouter"> <property name="cbrAlias" value="XPath"/> <property name="ruleSet" value="xpath-rules.properties"/> <property name="ruleReload" value="true"/> <property name="destinations"> <route-to destination-name="express" service-category="ExpressShipping" service-name="ExpressShippingService"/> <route-to destination-name="normal" service-category="NormalShipping" service-name="NormalShippingService"/> </property> </action>
13.7.13. StaticRouter
Class | org.jboss.soa.esb.actions.StaticRouter |
Table 13.24. StaticRouter Properties
Property | Description |
---|---|
destinations |
Container property for the <route-to> configurations.
<route-to destination-name="express" service-category="ExpressShipping" service-name="ExpressShippingService"/>> |
Table 13.25. StaticRouter Process Methods
method | Description |
---|---|
process |
Do not append aggregation data to message.
|
split |
Append aggregation data to message.
|
<action name="routeAction" class="org.jboss.soa.esb.actions.StaticRouter"> <property name="destinations"> <route-to service-category="ExpressShipping" service-name="ExpressShippingService"/> <route-to service-category="NormalShipping" service-name="NormalShippingService"/> </property> </action>
13.7.14. SyncServiceInvoker
Class | org.jboss.soa.esb.actions.SyncServiceInvoker |
Table 13.26. SyncServiceInvoker Properties
Property | Description | Required |
---|---|---|
service-category |
Service Category.
| Yes |
service-name |
Service Name.
| Yes |
failOnException |
Should the action fail on an exception from the target service invocation. If set to "false", the action will simply return the input message to the pipeline, allowing the service to continue processing. If you need to know the failure state, leave this parameter set to true and use the normal "faultTo" mechanism by allowing the pipeline to fail (default is "true").
| No |
suspendTransaction |
This action will fail if executed in the presence of an active transaction. The transaction can be suspended if this property is set to "true". Default is "false".
| No |
ServiceInvokerTimeout |
Invoker timeout in milliseconds. In the event of a timeout, an exception will occur, causing the action to behave according to the "failOnException" configuration. The default is 30000.
| No |
<action name="route” class="org.jboss.soa.esb.actions.SyncServiceInvoker"> <property name="service-category" value="Services" /> <property name="service-name" value="OM" /> </action>
13.7.15. StaticWireTap
Class | org.jboss.soa.esb.actions.StaticWireTap |
Table 13.27. StaticWireTap Properties
Property | Description | Required |
---|---|---|
destinations |
Container property for the <route-to> configurations.
<route-to destination-name="express" service-category="ExpressShipping" service-name="ExpressShippingService"/> |
Table 13.28. StaticWireTap Process Methods
method | Description |
---|---|
process |
Do not append aggregation data to message.
|
<action name="routeAction" class="org.jboss.soa.esb.actions.StaticWiretap"> <property name="destinations"> <route-to service-category="ExpressShipping" service-name="ExpressShippingService"/> <route-to service-category="NormalShipping" service-name="NormalShippingService"/> </property> </action>
13.7.16. E.-Mail WireTap
Class | org.jboss.soa.esb.actions.routing.email.EmailWiretap |
Table 13.29. E.-Mail WireTap Properties
Property | Description |
---|---|
host |
The host name of the SMTP server. If not specified, will default to the property 'org.jboss.soa.esb.mail.smtp.host' in jbossesb-properties.xml.
|
port |
The port for the SMTP server. If not specified, will default to the property 'org.jboss.soa.esb.mail.smtp.port' in jbossesb-properties.xml.
|
username |
The username for the SMTP server. If not specified, will default to the property 'org.jboss.soa.esb.mail.smtp.user' in jbossesb-properties.xml.
|
password |
The password for the above username on the SMTP server. If not specified, will default to the property 'org.jboss.soa.esb.mail.smtp.password' in jbossesb-properties.xml.
|
auth |
If true will attempt to authenticate the user using the AUTH command. If not specified, will default to the property 'org.jboss.soa.esb.mail.smtp.auth' in jbossesb-properties.xml.
|
from |
The "from" email address.
|
sendTo |
The destination email account.
|
subject |
The subject of the email.
|
messageAttachmentName |
The filename of an attachment containing the message payload (optional). If not specified the message payload will be included in the message body.
|
message |
A string to be prepended to the ESB message contents which make up the e-mail message (optional).
|
ccTo |
Comma-separated list of email addresses (optional).
|
attachment |
Child elements that contain file that will be added as attachments to the email sent.
|
<action name="send-email" class="org.jboss.soa.esb.actions.routing.email.EmailWiretap"> <property name="host" value="smtpHost" /> <property name="port" value="25" /> <property name="username" value="smtpUser" /> <property name="password" value="smtpPassword" /> <property name="from" value="jbossesb@xyz.com" /> <property name="sendTo" value="systemX@xyz.com" /> <property name="subject" value="Important message" /> </action>
13.8. Notifier Actions
13.8.1. Notifier Action
13.8.2. Notifier
Class | org.jboss.soa.esb.actions.Notifier |
<action name="notify" class="org.jboss.soa.esb.actions.Notifier" okMethod="notifyOK"> <property name="destinations"> <NotificationList type="OK"> <target class="NotifyConsole" /> <target class="NotifyFiles" > <file name="@results.dir@/goodresult.log" /> </target> </NotificationList> <NotificationList type="err"> <target class="NotifyConsole" /> <target class="NotifyFiles" > <file name="@results.dir@/badresult.log" /> </target> </NotificationList> </property> </action>
13.8.3. NotifyConsole
Class | NotifyConsole |
Example 13.15. NotifyConsole
<target class="NotifyConsole" />
13.8.4. NotifyFiles
Class | NotifyFiles |
Purpose | Performs a notification by writing the contents of the ESB message to a specified set of files. |
Attributes | none |
Child | file |
Child Attributes |
|
<target class="NotifyFiles" > <file append="true" URI="anyValidURI"/> <file URI="anotherValidURI"/> </target>
13.8.5. NotifySqlTable
Class | NotifySqlTable |
Purpose | Performs a notification by inserting a record into an existing database table. The database record contains the ESB message contents and, optionally, other values specified using nested <column> elements. |
Attributes |
|
Child | column |
Child Attributes |
|
<target class="NotifySqlTable" driver-class="com.mysql.jdbc.Driver" connection-url="jdbc:mysql://localhost/db" user-name="user" password="password" table="table" dataColumn="messageData"> <column name="aColumnlName" value="aColumnValue"/> </target>
13.8.6. NotifyQueues
Class | NotifyQueues |
Purpose | Performs a notification by translating the ESB message (including its attached properties) into a JMS message and sending the JMS message to a list of Queues. Additional properties may be attached using the <messageProp> element. |
Attributes | none |
Child | queue |
Child Attributes |
|
Child | messageProp |
Child Attributes |
|
<target class="NotifyQueues" > <messageProp name="aNewProperty" value="theValue"/> <queue jndiName="queue/quickstarts_notifications_queue" /> </target>
13.8.7. NotifyTopics
Class | NotifyTopics |
Purpose | Performs a notification by translating the ESB message (including its attached properties) into a JMS message and publishing the JMS message to a list of Topics. Additional properties may be attached using the <messageProp> element. |
Attributes | none |
Child | topic |
Child Attributes |
|
Child | messageProp |
Child Attributes |
|
<target class="NotifyTopics" > <messageProp name="aNewProperty" value="theValue"/> <queue jndiName="queue/quickstarts_notifications_topic" /> </target>
13.8.8. NotifyEmail
Class | NotifyEmail |
Purpose | Sends a notification e-mail containing the ESB message content and, optionally, any file attachments. |
Attributes | None. |
Child | Topic. |
Child Attributes |
|
Child | Attachment. Optional |
Child Text | The name of the file to be attached. |
<target class="NotifyEmail" from="person@somewhere.com" sendTo="person@elsewhere.com" subject="theSubject"> <attachment>attachThisFile.txt</attachment> </target>
13.8.9. NotifyFTP
Class | NotifyFTP |
Purpose | Performs a notification by creating a file containing the ESB message content and transferring it via FTP to a remote file system. |
Attributes | None. |
Child | FTP |
Child Attributes |
|
<target class="NotifyFTP" > <ftp URL="ftp://username:pwd@server.com/remote/dir" filename="someFile.txt" /> </target>
13.8.10. NotifyFTPList
Class | NotifyFTPList |
Purpose |
NotifyFTPList extends NotifyFTP and adds the ability to take a single file name or list of file names located in the ESB Message object.
The file(s) in the Message payload should contain a list of files (full paths). This list will be iterated over and every file in the list will be sent to the configured destination FTP server directory if the "listFiles" property is false. If "listFiles" is true, the file(s) are read line by line, with each line containing the name of a file to be transferred.
So, you can supply:
|
Attributes | None. |
Child | FTP. |
Child Attributes |
|
<target class="NotifyFTPList"> <ftp URL="ftp://username:password@localhost/outputdir" filename="{org.jboss.soa.esb.gateway.file}"> listFiles="true" deletelistFile="true" </target>
13.8.11. NotifyTCP
Class | NotifyTCP |
Purpose |
Send message via TCP. Each connection is maintained only for the duration of the notification.
Only supports sending of string data payloads explicitly (as a String, or encoded as a byte array (byte[]).
|
Attributes | None. |
Child | Destination (supports multiple destinations). |
Child Attributes |
|
<target class="NotifyTcp" > <destination URI="tcp://myhost1.net:8899" /> <destination URI="tcp://myhost2.net:9988" /> </target>
13.9. SOAP Client Actions
13.9.1. Simple Object Access Protocol (SOAP)
13.9.2. SOAPProcessor
13.9.3. SOAPProcessor Action Configuration
<action name="JBossWSAdapter" class="org.jboss.soa.esb.actions.soap.SOAPProcessor"> <property name="jbossws-endpoint" value="ABI_OrderManager" /> <property name="jbossws-context" value="ABIV1OrderManager_war" /> <property name="rewrite-endpoint-url" value="true" /> </action>
- jbossws-endpoint
- This is the JBossWS endpoint that the SOAPProcessor is exposing. Mandatory.
- jbossws-context
- This optional property is the context name of the Webservice's deployment and can be used to uniquely identify the JBossWS endpoint.
- rewrite-endpoint-url
- The optional "rewrite-endpoint-url" property is there to support load balancing on HTTP endpoints, in which case the Webservice endpoint container will have been configured to set the HTTP(S) endpoint address in the WSDL to that of the Load Balancer. The "rewrite-endpoint-url" property can be used to turn off HTTP endpoint address rewriting in these situations. It has no effect for non-HTTP protocols. Default is true.
Important
13.9.4. Use the SOAPProcessor Action
Prerequisites
- The soap.esb service. This is available in the product's
lib
directory.
Procedure 13.2. Task
- Write a thin service wrapper web service (for example, a JSR 181 implementation) that wraps calls to a target service that does not have a web service end-point.Expose the target service via end-points running on the enterprise service bus.
13.9.5. SOAPClient
<action name="soap-wise-client-action" class="org.jboss.soa.esb.actions.soap.wise.SOAPClient"> <property name="wsdl" value="http://host:8080/OrderManagement?wsdl"/> <property name="SOAPAction" value="http://host/OrderMgmt/SalesOrder"/> <property name="wise-config"> <wise-property name="wise.tmpDir" value="/tmp" /> <wise-property name="wise.jaxb.bindings" value="some.xjb,additional.xml" /> </property> </action>
Table 13.30. SOAPClient Optional Properties
Property | Description |
---|---|
wsdl |
The WSDL to be used.
|
operationName |
The name of the operation as specified in the webservice WSDL.
|
SOAPAction |
The endpoint operation, now superseded by operationName.
|
EndPointName |
The endpoint invoked. Webservices can have multiple endpoints. If it's not specified, the first name in wsdl will be used.
|
SmooksRequestMapper |
Specifies a Smooks config file to define the Java-to-Java mapping defined for the request.
|
SmooksResponseMapper |
Specifies a Smooks config file to define the Java-to-Java mapping defined for the response.
|
serviceName |
A symbolic service name used by Wise to cache object generation and/or use already generated object. If it isn't provided, Wise uses the servlet name of wsdl.
|
username |
Username used if the webservice is protected by BASIC Authentication HTTP.
|
password |
Password used if the webservice is protected by BASIC Authentication HTTP.
|
smooks-handler-config |
It's often necessary to be able to transform the SOAP request or response, especially in header. This may be to simply add some standard SOAP handlers. Wise supports JAXWS SOAP Handler, both custom or a predefined one based on Smooks.
Transformation of the SOAP request (before sending) is supported by configuring the SOAPClient action with a Smooks transformation configuration property.
|
custom-handlers |
It's also possible to provide a set of custom standard JAXWS SOAP Handler. The parameter accept a list of classes implementing SoapHandler interface. Classes have to provide a fully qualified name and be separated by semi-columns.
|
LoggingMessages |
It's useful for debugging purposes to view the SOAP messages sent and the response received. Wise achieves this goal using a JAX-WS handler which prints all messages exchanged on System.out. Boolean value.
|
wise-config |
A list of wise-property elements that can be used to configure Wise client. The wise-property element consists of name and value attributes. A special ESB property wise.jaxb.bindings can be used to specify JAXB customizations. It accepts a comma -eparated list of resource names included in the ESB archive.
|
Important
- Print "WARN [SOAPClient] Received status code '500' on HTTP SOAP (POST) request to..."
- Ignore the fault and just continue to the next action.
samples/quickstarts
directory.
- As a map instance set on the default body location
(Message.getBody().add(Map))
- As a map instance set on in a named body location
(Message.getBody().add(String, Map))
, where the name of that body location is specified as the value of the "get-payload-location" action property.
- With a set of objects that are accessed (for SOAP message parameters) using the OGNL framework.
- With a set of String based key-value pairs(<String, Object>), where the key is an OGNL expression identifying the SOAP parameter to be populated with the key's value.
13.9.6. Object Graph Navigation Library (OGNL)
13.9.7. Using the Object Graph Navigation Library
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:cus="http://schemas.acme.com"> <soapenv:Header/> <soapenv:Body> <cus:customerOrder> <cus:header> <cus:customerNumber>123456</cus:customerNumber> </cus:header> </cus:customerOrder> </soapenv:Body> </soapenv:Envelope>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:cus="http://schemas.active-endpoints.com/sample/customerorder/2006/04/CustomerOrder.xsd" xmlns:stan="http://schemas.active-endpoints.com/sample/standardtypes/2006/04/StandardTypes.xsd"> <soapenv:Header/> <soapenv:Body> <cus:customerOrder> <cus:items> <cus:item> <cus:partNumber>FLT16100</cus:partNumber> <cus:description>Flat 16 feet 100 count</cus:description> <cus:quantity>50</cus:quantity> <cus:price>490.00</cus:price> <cus:extensionAmount>24500.00</cus:extensionAmount> </cus:item> <cus:item> <cus:partNumber>RND08065</cus:partNumber> <cus:description>Round 8 feet 65 count</cus:description> <cus:quantity>9</cus:quantity> <cus:price>178.00</cus:price> <cus:extensionAmount>7852.00</cus:extensionAmount> </cus:item> </cus:items> </cus:customerOrder> </soapenv:Body> </soapenv:Envelope>
Warning
13.9.8. SOAP Operation Parameters
- as a map instance set on the default body location
(Message.getBody().add(Map))
- as a map instance set on in a named body location
(Message.getBody().add(String, Map))
, where the name of that body location is specified as the value of the "paramsLocation" action property.
- With a set of Objects of any type. In this case a Smooks config has to be specified in action attribute SmooksRequestMapper and Smooks is used to make the Java-to-Java conversion
- With a set of String-based key-value pairs(<String, Object>), where the key is the name of the SOAP parameter as specified in wsdls (or in generated class) to be populated with the key's value. SOAP Response Message Consumption
- On the default body location (Message.getBody().add(Map))
- On in a named body location (Message.getBody().add(String, Map)), where the name of that body location is specified as the value of the "responseLocation" action property.
- With a set of objects of any type. In this case, a Smooks config have to be specified in action attribute SmooksResponseMapper and Smooks is used to make the Java-to-Java conversion
- With a set of String based key-value pairs(<String, Object>), where the key is the name of the SOAP answer as specified in wsdls (or in generated class) to be populated with the key's value. JAX-WS Handler for the SOAP Request/Response
- webservice_consumer_wise, shows basic usage.
- webservice_consumer_wise2, shows how to use'SmooksRequestMapper' and 'SmooksResponseMapper'.
- webservice_consumer_wise3, shows how to use 'smooks-handler-config'.
- webservice_consomer_wise4, shows usage of 'custom-handlers'.
13.9.9. Specify an End-Point Operation for the SOAPClient Action
Procedure 13.3. Task
- Specify the "wsdl" and "operation" properties on the SOAPClient action:
<action name="soapui-client-action" class="org.jboss.soa.esb.actions.soap.SOAPClient"> <property name="wsdl" value="http://localhost:18080/acme/services/RetailerCallback?wsdl"/> <property name="operation" value="SendSalesOrderNotification"/> </action>
13.9.10. Dealing with SOAP Response Messages
- On the default body location (Message.getBody().add(Map))
- In a named body location (Message.getBody().add(String, Map)), where the name of that body location is specified as the value of the "set-payload-location" action property.
- as an Object Graph created and populated by the XStream toolkit. We also plan to add support for unmarshaling the response using JAXB and JAXB Annotation Introductions.
- as a set of String based key-value pairs(<String, String>), where the key is an OGNL expression identifying the SOAP response element and the value is a String representing the value from the SOAP message.
- if Options one or two are not specified in the action configuration, the raw SOAP response message (String) is attached to the message.
13.9.11. Use XStream to Populate an Object Graph
Procedure 13.4. Task
- Configure XStream on an action:
<action name="soapui-client-action" class="org.jboss.soa.esb.actions.soap.SOAPClient"> <property name="wsdl" value="http://localhost:18080/acme/services/RetailerService?wsdl"/> <property name="operation" value="GetOrder"/> <property name="get-payload-location" value="get-order-params" /> <property name="set-payload-location" value="get-order-response" /> <property name="responseXStreamConfig"> <alias name="customerOrder" class="com.acme.order.Order" namespace="http://schemas.acme.com/services/CustomerOrder.xsd" /> <alias name="orderheader" class="com.acme.order.Header" namespace="http://schemas.acme.com/services/CustomerOrder.xsd" /> <alias name="item" class="com.acme.order.OrderItem" namespace="http://schemas.acme.com/services/CustomerOrder.xsd" /> </property> </action>
In the above example, there is also an example of how to specify non-default named locations for the request parameters Map and response object instance. - Specify any field name mappings and XStream annotated classes:
<property name="responseXStreamConfig"> <fieldAlias name="header" class="com.acme.order.Order" fieldName="headerFieldName" /> <annotation class="com.acme.order.Order" /> </property>
Field mappings can be used to map XML elements onto Java fields on occasions when the local name of the element does not correspond to the field name in the Java class.
13.9.12. Extract SOAP response data to an OGNL Keyed Map
Procedure 13.5. Task
- Replace the "responseXStreamConfig" property with the "responseAsOgnlMap" property:
<action name="soapui-client-action" class="org.jboss.soa.esb.actions.soap.SOAPClient"> <property name="wsdl" value="http://localhost:18080/acme/services/RetailerService?wsdl"/> <property name="operation" value="GetOrder"/> <property name="get-payload-location" value="get-order-params" /> <property name="set-payload-location" value="get-order-response" /> <property name="responseAsOgnlMap" value="true" /> </action>
Note
To return the raw SOAP message as a string, simply omit both the "responseXStreamConfig" and "responseAsOgnlMap" properties.
13.9.13. HttpClient
13.9.14. Configuring the HttpClient
- EasySSLProtocolSocketFactory can be used to create SSL connections that allow the target server to authenticate with a self-signed certificate.
- StrictSSLProtocolSocketFactory can be used to create SSL connections that can optionally perform host name verification in order to help preventing man-in-the-middle type of attacks.
- AuthSSLProtocolSocketFactory can be used to optionally enforce mutual client/server authentication. This is the most flexible implementation of a protocol socket factory. It allows for customization of most, if not all, aspects of the SSL authentication.
org.jboss.soa.esb.http.Configurator
class and providing a configure(HttpClient, Properties)
method.
Table 13.31. Out-of-the-box implementations
Configurator | Description | Required |
---|---|---|
HttpProtocol |
Configure the HttpClient host, port and protocol information, including the socket factory and SSL keystore information.
| Yes |
AuthBasic |
Configure HTTP Basic authentication for the HttpClient.
| No |
AuthNTLM |
Configure NTLM authentication for the HttpClient.
| No |
Table 13.32. Properties
Property | Description | Required |
---|---|---|
HttpProtocol |
Configure the HttpClient host, port and protocol information, including the socket factory and SSL keystore information.
| Yes |
target-host-url |
Target URL for http/https endpoint
| Yes |
https.proxyHost |
Proxy Host for https connections
| No |
https.proxyPort |
Proxy Port for https connections, defaulting to port 443
| No |
http.proxyHost |
Proxy Host for http connections
| No |
http.proxyPort |
Proxy Port for http connections, defaulting to port 80
| No |
protocol-socket-factory |
Override socket factory, implementing the
ProtocolSocketFactory or ProtocolSocketFactoryBuilder interface.
The default value for http is the httpclient
DefaultProtocolSocketFactory whereas the default value for https is the contributed StrictSSLProtocolSocketFactory .
There are two implementations of
ProtocolSocketFactoryBuilder provided in the ESB codebase, AuthSSLProtocolSocketFactoryBuilder and SelfSignedSSLProtocolSocketFactoryBuilder , for configuring the AuthSSLProtocolSocketFactory factory and self signed SSLContext respectively.
| No |
keystore |
KeyStore location
| No |
keystore-passw |
KeyStore password or encrypted file
| No |
keystore-type |
KeyStore type, defaulting to jks
| No |
truststore |
TrustStore location
| No |
truststore-passw |
TrustStore password or encrypted file
| No |
truststore-type |
TrustStore type, defaulting to jks
| No |
Table 13.33. Properties
Property | Description | Required |
---|---|---|
auth-username |
Authentication Username
| Yes |
auth-password |
Authentication Password
| Yes |
authscope-host |
Authentication Scope Host
| Yes |
authscope-port |
Authentication Scope Port
| Yes |
authscope-domain |
Authentication Scope Domain
| Yes |
Table 13.34. Properties
Property | Description | Required |
---|---|---|
ntauth-username |
Authentication Username
| Yes |
ntauth-password |
Authentication Password
| Yes |
ntauthscope-host |
Authentication Scope Host
| Yes |
ntauthscope-port |
Authentication Scope Port
| Yes |
ntauthscope-domain |
Authentication Scope Domain
| Yes |
ntauthscope-realm |
Authentication Scope Realm
| No |
13.9.15. Specify the HttpClientFactory Configuration on the SOAPClient
Procedure 13.6. Task
- Add an additional property to the "wsdl" property:
<property name="wsdl" value="https://localhost:18443/active-bpel/services/RetailerCallback?wsdl"> <http-client-property name="file" value="/localhost-https-18443.properties" > </http-client-property> </property>
Note
The "file" property value will be evaluated as a filesystem, classpath or URI based resource (in that order). This resource contains the HttpClient configuration in the standard Java properties format.
13.9.16. Configure the HttpClient Directly in the Action Configuration
Procedure 13.7. Task
- Set the properties directly in the action configuration:
<property name="http-client-properties"> <http-client-property name="http.proxyHost" value="localhost"/> <http-client-property name="http.proxyPort" value="8080"/> </property>
13.9.17. SOAPProxy
- it facilitates loose coupling between the client and service (since they are both completely unaware of each other.)
- it means the client no longer has a direct connection to the remote service's hostname/IP address.
- the client will see modified WSDL that changes the inbound/outbound parameters. At a minimum, the WSDL must be tweaked so that the client is pointed to the ESB's exposed end-point instead of the original, now proxied endpoint.
- it allows you to introduce a transformation of the SOAP envelope/body via the action pipeline both for the inbound request and outbound response.
- it makes service versioning possible since clients can connect to two or more proxy end-points on the enterprise service bus, each with its own WSDL and/or transformations and routing requirements, and the ESB will send the appropriate message to the appropriate endpoint and provide an ultimate response.
- it allows for complex context-based routing via ContentBasedRouter.
13.9.18. Using the SOAPProxy Action
- both a producer and consumer of web services.
- all that is required is a property pointing to the external wsdl.
- a way to allow the WSDL to be automatically transformed (via the optional wsdlTransform property.)
- a way to ensure that SOAP is not tied to HTTP. The WSDL is read, and if an HTTP transport is defined, that will be used.
- a way to optionally apply HttpRouter properties as overrides if you are using HTTP.
Table 13.35.
Property | Description | Required |
---|---|---|
wsdlTransform |
A <smooks-resource-list> xml config file allowing for flexible wsdl transformation.
| No |
wsdlCharset |
The character set the original wsdl (and imported resources) is encoded in UTF-8. It will be transformed to UTF-8 if it is a supported encoding by the underlying platform.
| No |
endpointUrl |
Example of an HttpRouter property, useful when domain name matching is important for SSL certs.
| No |
file |
Apache Commons HTTPClient properties file, useful when proxying to a web service via SSL.
| No |
clientCredentialsRequired |
Whether the Basic Auth credentials are required to come from the end client, or if the credentials specified inside file can be used instead. Default is "true".
| No |
wsdl |
The original wsdl url whose WS endpoint will get re-written and exposed as new wsdl from the ESB. Depending upon the
<definitions><service><port><soap:address location attribute's protocol (for example "http"), a protocol-specific SOAPProxyTransport implementation is used.
The value can reference a location based on five different schemes:
| Yes |
Example 13.16. Sample Configuration: Basic scenario
<action name="proxy" class="org.jboss.soa.esb.actions.soap.proxy.SOAPProxy"> <property name="wsdl" value="http://host/foo/HelloWorldWS?wsdl"/> </action>
Example 13.17. Sample Configuration: Basic Authentication and SSL
<action name="proxy" class="org.jboss.soa.esb.actions.soap.proxy.SOAPProxy"> <property name="wsdl" value="https://host/foo/HelloWorldWS?wsdl"/> <property name="endpointUrl" value="https://host/foo/HelloWorldWS"/> <property name="file" value="/META-INF/httpclient-8443.properties"/> <property name="clientCredentialsRequired" value="true"/> </action>
13.10. Miscellaneous Actions
13.10.1. SystemPrintln
System.out.println
). It formats the message contents as XML.
13.10.2. Using SystemPrintln
Input Type | java.lang.String |
Class | org.jboss.soa.esb.actions.SystemPrintln |
Properties |
|
<action name="action2" class="org.jboss.soa.esb.actions.ServiceLoggerAction"> <property name="text" value="Message arrived"/> <property name="log-payload-location" value="true"/> </action>
13.10.3. SchemaValidationAction
13.10.4. Using SchemaValidationAction
Input Type | java.lang.String |
Class | org.jboss.soa.esb.actions.validation.SchemaValidationAction |
Properties |
|
<action name="val" class="org.jboss.soa.esb.actions.validation.SchemaValidationAction"> <property name="schema" value="/com/acme/validation/order.xsd"/> </action>
13.10.5. ServiceLoggerAction
13.10.6. Using the ServiceLoggerAction
- Using the Debug level setting will result in the message being output.
- Using the trace level setting will result in the output of the message payload
Input Type | java.lang.String |
Class | org.jboss.soa.esb.actions.ServiceLoggerAction |
Properties |
|
<action name="servicelogger" class="org.jboss.soa.esb.actions.ServiceLoggerAction"> <property name="text" value="Reached here"/><br/> <property name="get-payload-location" value="true"/> </action>
Note
Chapter 14. Developing Your Own Actions
14.1. Developing Custom Actions
- Lifecycle actions, implementing
org.jboss.soa.esb.actions.ActionLifecycle
ororg.jboss.soa.esb.actions.ActionPipelineProcessor
- Java bean actions, implementing
org.jboss.soa.esb.actions.BeanConfiguredAction
- Annotated actions
- Legacy actions
- How the actions are configured
- When the actions are instantiated and the implications on thread safety
- Whether they have visibility of life-cycle events
- Whether the action methods are invoked directly or via reflection
14.2. Configuring an Action by Setting Properties for It
PrintMessage
action might use a property named message to indicate what to print and another property called repeatCount to indicate the number of times to print it. If so, the action configuration in the jboss-esb.xml
file should look like this:
<action name="PrintAMessage" class="test.PrintMessage"> <property name="information" value="Hello World!" /> <property name="repeatCount" value="5" /> </action>
14.3. Reflection
Note
14.4. Managed Lifecycle
14.5. Life-cycle Action
org.jboss.soa.esb.actions.ActionLifecycle
and org.jboss.soa.esb.actions.ActionPipelineProcessor
.
14.6. ActionLifecycle
initialise
and destroy
action pipeline life-cycle methods,
14.7. ActionPipelineProcessor
process
, processSuccess
and processException
message processing methods.
14.8. Implementing ActionLifecycle and ActionPipelineProcessor
initialise
and destroy
methods can be overridden to allow the action to perform resource management for the lifetime of the pipeline. (For example, caching resources needed in the initialise
method, then cleaning them up in the destroy
method.)
ConfigTree
instance as a parameter, representing the configuration of the specific action within the pipeline.
process
method. These are org.jboss.soa.esb.actions.AbstractActionPipelineProcessor
and org.jboss.soa.esb.actions.AbstractActionLifecycle
. Use them like this:
public class ActionXXXProcessor extends AbstractActionPipelineProcessor { public ActionXXXProcessor(final ConfigTree config) { // extract configuration } public void initialise() throws ActionLifecycleException { // Initialize resources... } public Message process(final Message message) throws ActionProcessingException { // Process messages in a stateless fashion... } public void destroy() throws ActionLifecycleException { // Cleanup resources... } }
14.9. Java Bean Action
14.10. Configuring a Java Bean Action
org.jboss.soa.esb.actions.BeanConfiguredAction
marker interface in order to make the action Bean populate automatically. Here is some sample code:
import org.jboss.soa.esb.message.Message; import org.jboss.soa.esb.actions.BeanConfiguredAction; public class PrintMessage implements BeanConfiguredAction { private String information; private Integer repeatCount; public void setInformation(String information) { this.information = information; } public void setRepeatCount(Integer repeatCount) { this.repeatCount = repeatCount; } public Message process(Message message) { for (int i=0; i < repeatCount; i++) { System.out.println(information); } return message; } }
Note
setRepeatCount()
method is automatically converted from the String representation specified in the XML.
BeanConfiguredAction
method of loading properties is a good choice for actions that take simple arguments, while the ConfigTree
method is a better option in situations when one needs to deal with the XML representation directly.
Important
process
methods invoked using reflection.
14.11. Annotated Action
ConfigTree
. A single instance of annotated actions will be instantiated on a "per-pipeline" basis (in other words, per-action configuration) and must be thread safe. The pipeline will always invoke the action methods using reflection.
14.12. Using Annotations
- @Process
- The simplest implementation involves creating an action with a a basic plain old Java object (POJO) with a single method, annotated with @Process:
public class MyLogAction { @Process public void log(Message message) { // log the message... } }
The @Process annotation serves to identify the class as a valid ESBaction
. In cases in which there are multiple methods in the class, it also identifies the method which is to be used for processing the message instance (or some part of the message. This is explained in more depth when the @BodyParam, @PropertyParam and @AttachmentParam annotations are discussed.)To configure an instance of thisaction
on apipeline
, use the same process as that for low/base levelaction
implementations (these being those that extendAbstractActionPipelineProcessor
or implementActionLifecycle
or one of its other sub-types or abstract implementations):<service .....> <actions> <action name="logger" class="com.acme.actions.MyLogAction" /> </actions> </service>
In cases in which multiple methods annotated with @Process are associated with theaction
implementation, use the process attribute to specify which of them is to be used for processing the message instance:<service .....> <actions> <action name="logger" class="com.acme.actions.MyLogAction" process="log" /> </actions> </service>
@Process methods can be implemented to return:- void. This means there will be no return value, as with the logger action implementation above.
- message: This is a message instance. This becomes the active/current instance on the action pipeline.
- another type. If the method does not return a message instance, the object instance that is returned will be set on the current message instance on the action pipeline.. Where you should set it on the message depends on the set-payload-location<action> configuration property, which default according to the normal
MessagePayloadProxy
rules.
Use @Process methods to specify parameters in a range of different ways. You can:- specify the message instance as a method parameter.
- specify one or more arbitrary parameter types. The Enterprise Service Bus framework will search for data of that type in the active/current pipeline message instance. Firstly, it will search the message body, then properties, then attachments and pass this data as the values for those parameters (or
null
if not found).
An example of the first option was depicted above in the logger action. Here is an example of the second option:public class OrderPersister { @Process public OrderAck storeOrder(OrderHeader orderHeader, OrderItems orderItems) { // process the order parameters and return an ack... } }
In this example, the @Process method is relying on a previous action in thepipeline
to create theOrderHeader
andOrderItem
object instances and attach them to the current message. (Perhaps a more realistic implementation would have a generic action implementation that decodes an XML or EDI payload to an order instance, which it would then returns. TheOrderPersister
would then take an order instance as its sole parameter.) Here is an example:public class OrderDecoder { @Process public Order decodeOrder(String orderXML) { // decode the order XML to an ORder instance... } } public class OrderPersister { @Process public OrderAck storeOrder(Order order) { // persist the order and return an ack... } }
Chain the two actions together in the service configuration:<actions> <action name="decode" class="com.acme.orders.OrderDecoder" /> <action name="persist" class="com.acme.orders.OrderPersister" /> </actions>
The code is easier to read in Option #2 because there are less annotations, but it carries a risk because the process of run-time "hunting" through the message for the appropriate parameter values is not completely deterministic. Due to this, Red Hat supports the @BodyParam, @PropertyParam and @AttachmentParam annotations.Use these @Process method parameter annotations to explicitly define from where in the message an individual parameter value for the @Process method is to be retrieved. As their names suggest, each of these annotations allow you to specify a named location (in the message body, properties or attachments) for a specific parameter:public class OrderPersister { @Process public OrderAck storeOrder( @BodyParam("order-header") OrderHeader orderHeader, @BodyParam("order-items") OrderItems orderItems) { // process the order parameters and return an ack... } }
If the message location specified does not contain a value, then null will be passed for this parameter (the @Process method instance can decide how to handle this). If, on the other hand, the specified location contains a value of the wrong type, aMessageDeliverException
will be thrown. - @ConfigProperty
- Most actions require some degree of custom configuration. In the ESB action configuration, the properties are supplied as <property> sub-elements of the <action> element:
<action name="logger" class="com.acme.actions.MyLogAction"> <property name="logFile" value="logs/my-log.log" /> <property name="logLevel" value="DEBUG" /> </action>
To utilise these properties, use the low/base level action implementations (do so by extendingAbstractActionPipelineProcessor
or by implementingActionLifecycle
). This involves working with theConfigTree
class, (which is supplied to the action via its constructor). In order to implement an action, follow these steps:- Define a constructor on the action class that supplies the
ConfigTree
instance. - Obtain all of the relevant action configuration properties from the
ConfigTree
instance. - Check for mandatory action properties and raise exceptions in those places where they are not specified on the <action> configuration.
- Decode all property values from strings (as supplied on the
ConfigTree
) to their appropriate types as used by the action implementation. For example, decidejava.lang.String
tojava.io.File
,java.lang.String
to Boolean,java.lang.String
to long and so forth. - Raise exceptions at those places where the configured value cannot be decoded to the target property type.
- Implement unit tests on all the different configuration possibilities to ensure that the tasks listed above were completed properly.
While the tasks above are generally straightforward, they can be laborious, error-prone and lead to inconsistencies across actions with regard to how configuration mistakes are handled. You may also be required to add a lot of code resulting in additional confusion.The annotated action addresses these problems via @ConfigProperty. Expand the MyLogActions implementation, which has two mandatory configuration properties: logFile and logLevel:public class MyLogAction { @ConfigProperty private File logFile; @ConfigProperty private LogLevel logLevel; public static enum LogLevel { DEBUG, INFO, WARN } @Process public void log(Message message) { // log the message at the configured log level... } }
Note
You can also define the @ConfigProperty annotation on "setter" methods (instead of on the field).That is all that needs to be done. When the Enterprise Service Bus deploys the action, it examines both the implementation and the maps found within the decoded value (including any support for enums, as with the LogLevel enum above). It finds the action fields possessing the @ConfigProperty annotation. The developer is not required to deal with theConfigTree
class at all or develop any extra code.By default, every class field possessing the @ConfigProperty annotation is mandatory. Non-mandatory fields are handled in one of these two ways:- by specifying
use = Use.OPTIONAL
on the field's @ConfigProperty annotation. - by specifying a defaultVal on the field's @ConfigProperty annotation. (This is optional.)
To make the log action's properties optional only, implement the action like this:public class MyLogAction { @ConfigProperty(defaultVal = "logs/my-log.log") private File logFile; @ConfigProperty(use = Use.OPTIONAL) private LogLevel logLevel; public static enum LogLevel { DEBUG, INFO, WARN } @Process public void log(Message message) { // log the message... } }
The @ConfigProperty annotation supports two additional fields:- name: use this to explicitly specify the name of the action configuration property to be used to populate the field of that name on the action instance.
- choice: use this field to constrain the configuration values allowed for itself. This can also be achieved using an enumeration type (as with the LogLevel).
The name field might be used in various situations such as when migrating an old action (that uses the low/base level implementation type) to the newer annotation-based implementation, only to find that the old configuration name for a property (which cannot be changed for backward-compatibility reasons) does not map to a valid Java field name. Taking the log action as an example, imagine that this was the old configuration for the log action:<action ...> <property name="log-file" value="logs/my-log.log" /> <property name="log-level" value="DEBUG" /> </action>
The property names here do not map to valid Java field names, so specify the name on the @ConfigProperty annotation:public class MyLogAction { @ConfigProperty(name = "log-file") private File logFile; @ConfigProperty(name = "log-level") private LogLevel logLevel; public static enum LogLevel { DEBUG, INFO, WARN } @Process public void log(Message message) { // log the message... } }
The bean configuration's property values are decoded from their string values. To then match them against the appropriate POJO bean property type, these simple rules are used:- If the property type has a single-argument string constructor, use that.
- If it is a "primitive," use its object type's single-argument string constructor. For example, if it is an int, use the Integer object.
- If it is an enum, use
Enum.valueOf
to convert the configuration string to its enumeration value.
- @Initialize and @Destroy
- Sometimes action implementations need to perform initialization tasks at deployment time. They may also need to perform a clean-up whilst being undeployed. For these reasons, there are @Initialize and @Destroy method annotations.Here are some examples. At the time of deployment, the logging action may need to perform some checks (that, for example, files and directories exist). It may also perform some initialization tasks (such as opening the log file for writing). When it is undeployed, the action may need to perform some clean-up tasks (such as closing the file). Here is the code to perform these tasks:
public class MyLogAction { @ConfigProperty private File logFile; @ConfigProperty private LogLevel logLevel; public static enum LogLevel { DEBUG, INFO, WARN } @Initialize public void initializeLogger() { // Check if file already exists… check if parent folder // exists etc... // Open the file for writing... } @Destroy public void cleanupLogger() { // Close the file... } @Process public void log(Message message) { // log the message... } }
Note
All of the @ConfigProperty annotations will have been processed by the time the ESB deployer invokes the @Initialize methods. Therefore, the @Initialize methods can rely on these fields being ready before they execute the customised initialization.Note
There is no need to always use both of these annotations to specify methods. Only specify them if there is a need; in other words, if a method only needs initialization, only use the @Initialize annotation (You do not have to supply a "matching" method annotated with the @Destroy annotation).Note
It is possible to specify a single method and annotate it with both @Initialize and @Destroy.Note
You can optionally specify aConfigTree
parameter on @Initialize methods. Do this to have access to the actions which underlie theConfigTree
instance. - @OnSuccess and @OnException
- Use these annotations to specify those methods to be executed on a successful or failed execution, respectively, of that
pipeline
in which the action is configured:public class OrderPersister { @Process public OrderAck storeOrder(Order order) { // persist the order and return an ack... } @OnSuccess public void logOrderPersisted(Message message) { // log it... } @OnException public void manualRollback(Message message, Throwable theError) { // manually rollback... } }
In the cases of both of these annotations, the parameters passed to the methods are optional. You can supply none, some or all of the parameters shown above. The enterprise service bus' framework resolves the relevant parameters in each case.
14.13. Legacy Action
14.14. Behaviour and Attributes of a Legacy Action
- Configuration of the action is through the provision of a constructor with a single
ConfigTree
parameter. - The action will be instantiated for every message passing through the pipeline.
- The action has no knowledge of any of the lifecycle methods.
- The invocation of the
process
methods will always be done via reflection.
Chapter 15. Gateways and Connectors
15.1. Introduction to Gateways and Connectors
Not all clients interacting with the JBoss Enterprise SOA Platform will be able to understand its native protocols and message format. As such there is a need to be able to bridge between ESB-aware end-points (those that understand JBossESB) and ESB-unaware end-points (those that do not understand JBossESB). Such bridging technologies have existed for many years in a variety of distributed systems and are referred to as gateways and connectors.
15.2. Gateways
15.2.1. Gateway Listener
org.jboss.soa.esb.message.Message
format. This conversion happens in a variety of different ways, depending on the gateway type. Once the conversion has occurred, the gateway listener routes the data to its correct destination.
15.2.2. Differences Between a Gateway Listener and a Normal Listener
- Gateway classes can pick up arbitrary objects contained in files, JMS messages, SQL tables and so forth (each 'gateway class' is specialized for a specific transport), whereas JBossESB listeners can only process JBossESB normalized Messages as described in “The Message” section of this document. However, those Messages can contain arbitrary data.
- Only one action class is invoked to perform the 'message composing' action. ESB listeners are able to execute an action processing pipeline.
- Objects that are 'picked up' are used to invoke a single 'composer class' (the action) that will return an ESB message object. This will then be delivered to a target service that must be ESB-aware. The target service defined at configuration time will be translated at runtime into an EPR (or a list of EPRs) by the registry. The EPR returned by the registry is similar to the 'toEPR' contained in the header of ESB Messages. However, because incoming objects are 'ESB-unaware' with no dynamic way to determine the toEPR, this value is provided to the gateway at configuration time and included in all outgoing messages.There are a few off-the-shelf composer classes; the default 'file' composer class will just package the file contents into the message body. The same process occurs for JMS messages. The default message composing class for an SQL table row is to package contents of all columns specified in the configuration, into a java.util.Map.Although these default composer classes will be adequate for most uses, you can also provide your own. The only requirements are that they must have a constructor that takes a single ConfigTree argument, and that they must provide a 'Message composing' method (whereby the default name is 'process' but this can be configured differently in the 'process' attribute of the <action> element within the ConfigTree provided at constructor time). The processing method must take a single argument of type object, and return a message value.The FileGateway accepts the
file-filter-class
configuration attribute which allows you to define a FileFilter implementation that may be used to select the files used by the gateway in question. Initialization of user-defined FileFilter instances is performed by the gateway. If the instance is also of typeorg.jboss.soa.esb.listeners.gateway.FileGatewayListener.FileFilterInit
, theinit
method will be called and passed to the gateway ConfigTree instance.By default, the FileFilter implementations are defined and used by the FileGateway. If an input suffix is defined in the configuration, files matching that suffix will be returned. Alternatively, if there is no input suffix, any file is accepted as long as it does not match the work suffix, error suffix and post suffix.
15.2.3. Gateway Data Mappings
- JMS Gateway
- If the input message is a JMS TextMessage, then the associated String will be placed in the default named Body location. If it is an ObjectMessage or a BytesMessage then the contents are placed within the BytesBody.BYTES_LOCATION named "Body location".
- Local File Gateway
- This one places the contents within the BytesBody.BYTES_LOCATION named "Body location".
- Hibernate Gateway
- The contents are placed within the ListenerTagNames.HIBERNATE_OBJECT_DATA_TAG named "Body location".
- Remote File Gateway
- The contents are placed within the BytesBody.BYTES_LOCATION named "Body location".
Note
15.2.4. Changing Gateway Data Mappings
- File Gateways
- Instances of the
org.jboss.soa.esb.listeners.message.MessageComposer
interface are responsible for performing the conversion. To change the default behavior, provide an appropriate implementation that defines your own compose and decompose methods. Make sure that you provide the MessageComposer implementation in the configuration file by using the composer-class attribute name. - JMS and Hibernate Gateways
- These implementations use a reflective approach for defining composition classes. Provide your own message composer class and use the composer-class attribute name in the configuration file to inform the gateway which instance to use. You can use the composer-process attribute to inform the Gateway which operation of the class to call when it needs a message. This method must take an object and return a message. If not specified, a default name of process is assumed.
Note
15.3. Connectors
15.3.1. Java Connector Architecture (JCA)
- connections
- transactions
- security
- life-cycle
- work instances
- transaction inflow
- message inflow
15.3.2. Connecting via JCA
org.jboss.soa.esb.listeners.jca.InflowGateway
class:
public interface InflowGateway { public void setServiceInvoker(ServiceInvoker invoker); }
public class JmsEndpoint implements InflowGateway, MessageListener { private ServiceInvoker service; private PackageJmsMessageContents transformer = new PackageJmsMessageContents(); public void setServiceInvoker(ServiceInvoker invoker) { this.service = invoker; } public void onMessage(Message message) { try { org.jboss.soa.esb.message.Message esbMessage = transformer.process(message); service.deliverAsync(esbMessage); } catch (Exception e) { throw new RuntimeException(e); } } }
Note
org.jboss.soa.esb.listeners.jca.JmsEndpoint
. You can use this class over and over again with any JMS JCA inflow adapters.
15.3.3. Configuring a JCA Inflow Gateway
jboss-esb.xml
file:
<service category="HelloWorld_ActionESB" name="SimpleListener" description="Hello World"> <listeners> <jca-gateway name="JMS-JCA-Gateway" adapter="jms-ra.rar" endpointClass="org.jboss.soa.esb.listeners.jca.JmsEndpoint"> <activation-config> <property name="destinationType" value="javax.jms.Queue"/> <property name="destination" value="queue/esb_gateway_channel"/> </activation-config> </jca-gateway> ... </service>
<service category="HelloWorld_ActionESB" name="SimpleListener" description="Hello World"> <listeners> <jca-gateway name="JMS-JCA-Gateway" adapter="jms-ra.rar" endpointClass="org.jboss.soa.esb.listeners.jca.JmsEndpoint"> <activation-config> <property name="destinationType" value="javax.jms.Queue"/> <property name="destination" value="queue/esb_gateway_channel"/> </activation-config> </jca-gateway> ... </service>
Table 15.1. jca-gateway Configuration Attributes
Attribute | Required | Description |
---|---|---|
name | yes | The name of the gateway |
adapter | yes | The name of the adapter you are using. In JBoss it is the file name of the RAR you deployed, for example jms-ra.rar |
endpointClass | yes | The name of your end point class. |
messagingType | no | The message interface for the adapter. If you do not specify one, ESB will guess based on the endpoint class. |
transacted | no | Default to true. Whether or not you want to invoke the message within a JTA transaction. |
15.3.4. Mapping Standard Activation Properties
Table 15.2. Mapping Standard Activation Properties
Attribute | Location | Description |
---|---|---|
maxThreads | jms-listener | The maximum number of messages which can be processed concurrently. |
dest-name | jms-message-filter | The JMS destination name. |
dest-type | jms-message-filter | The JMS destination type, QUEUE or TOPIC. |
selector | jms-message-filter | The JMS message selector. |
providerAdapterJNDI | jms-jca-provider | The JNDI location of a Provider Adapter which can be used by the JCA inflow to access a remote JMS provider. This is a JBoss-specific interface, supported by the default JCA inflow adapter and may be used, if necessary, by other in-flow adapters. |
ActivationMapper
. interface. You can declare this class globally or within each individual deployment configuration.
jbossesb-properties.xml
file as it defines the default mapper used for the specified JCA adapter The name of the property to be configured is org.jboss.soa.esb.jca.activation.mapper.<adapter name> and the value is the class name of the ActivationMapper.
jms-ra.rar
:
<properties name="jca"> <property name="org.jboss.soa.esb.jca.activation.mapper.jms-ra.rar" value="org.jboss.soa.esb.listeners.jca.JBossActivationMapper"/> </properties>
<jms-listener name="listener" busidref="bus" maxThreads="100"> <property name="jcaActivationMapper" value="TestActivationMapper"/> </jms-listener>
<jms-bus busid="bus"> <property name="jcaActivationMapper" value="TestActivationMapper"/> <jms-message-filter dest-type="TOPIC" dest-name="DestName"/> </jms-bus>
<jms-jca-provider name="provider" connection-factory="ConnectionFactory"> <property name="jcaActivationMapper" value="TestActivationMapper"/> <jms-bus busid="bus"> <jms-message-filter dest-type="TOPIC" dest-name="DestName"/> </jms-bus> </jms-jca-provider>
Chapter 16. JAXB Annotation Introductions
16.1. JAXB Annotation Introductions
16.2. Using JAXB Annotation Introductions
META-INF/jaxb-intros.xml
file.
16.3. Writing JAXB Annotation Introduction Configurations
- @XmlType
- https://jaxb.dev.java.net/nonav/2.1.3/docs/api/javax/xml/bind/annotation/XmlType.html: This goes on the “Class” element.
- @XmlElement
- https://jaxb.dev.java.net/nonav/2.1.3/docs/api/javax/xml/bind/annotation/XmlElement.html: This goes on the “Field” and “Method” elements.
- @XmlAttribute
- https://jaxb.dev.java.net/nonav/2.1.3/docs/api/javax/xml/bind/annotation/XmlAttribute.html: This goes on the “Field” and “Method” elements.
<?xml version = "1.0" encoding = "UTF-8"?> <jaxb-intros xmlns="http://www.jboss.org/xsd/jaxb/intros"> <!-- The type namespaces on the customerOrder are different from the rest of the message... --> <Class name="com.activebpel.ordermanagement.CustomerOrder"> <XmlType propOrder="orderDate,name,address,items" /> <Field name="orderDate"> <XmlAttribute name="date" required="true" /> </Field> <Method name="getXYZ"> <XmlElement namespace="http://org.jboss.esb/quickstarts/bpel/ABI_OrderManager" nillable="true" /> </Method> </Class> <!-- More general namespace config for the rest of the message... --> <Class name="com.activebpel.ordermanagement.*"> <Method name="get.*"> <XmlElement namespace="http://ordermanagement.activebpel.com/jaws" /> </Method> </Class> </jaxb-intros>
Appendix A. Revision History
Revision History | |||
---|---|---|---|
Revision 5.3.1-78.400 | 2013-10-31 | Rüdiger Landmann | |
| |||
Revision 5.3.1-78 | Thu Feb 07 2013 | CS Builder Robot | |
|