|
[smooks-dev] [65] trunk/core/src/main/java/org/milyn/smooks/mule: - Wrote some Javadoc
Some parts of this message have been removed.
Learn more about Nabble's security policy.
[65] trunk/core/src/main/java/org/milyn/smooks/mule: - Wrote some Javadoc
- Revision
- 65
- Author
- mzeijen
- Date
- 2008-07-24 10:00:14 -0500 (Thu, 24 Jul 2008)
Log Message
- Wrote some Javadoc
- Refactered some strings to constants
Modified Paths
Diff
Modified: trunk/core/src/main/java/org/milyn/smooks/mule/MuleDispatcher.java (64 => 65)
--- trunk/core/src/main/java/org/milyn/smooks/mule/MuleDispatcher.java 2008-07-24 09:23:13 UTC (rev 64)
+++ trunk/core/src/main/java/org/milyn/smooks/mule/MuleDispatcher.java 2008-07-24 15:00:14 UTC (rev 65)
@@ -48,9 +48,81 @@
import org.w3c.dom.NodeList;
/**
+ * The MuleDispatcher is a Smooks Resource visitor to dispatch message
+ * parts to endpoints in Mule.
+ * <p/>
+ * <h3>Usage:</h3>
+ * A MuleDispatcher is defined as follows:
+ * <pre>
+ * <resource-config selector="order">
+ * <resource>org.milyn.smooks.mule.MuleDispatcher</resource>
+ * <param name="endpointName">order</param>
+ * <param name="beanId">order</param>
+ * </resource-config>
+ * </pre>
*
+ * <b>Required parameters:</b>
+ * <property name="endpointName" value="someEndpoint" />
+ *
+ * <b>Optional parameters:</b>
+ * <param name="beanId">someBeanId</param>
+ * <param name="resultBeanId">someBeanIdToBindTheResultTo</param>
+ * <param name="messagePropertiesBeanId">someBeanIdToGetTheMessagePropertiesFrom</param>
+ * <param name="messageProperties" >
+ * <property name="somePropertyName" value="somePropertyValue" type="someType" />
+ * </param>
+ * </pre>
+ *
+ * <h3>Description of configuration parameters</h3>
+ * <ul>
+ * <li><i>endpointName</i> - The name of the endpoint which will be used when routing the message. If no endpoint can be found under that name then an exception is thrown.
+ * <li><i>beanId</i> - The bean id of the bean which will be used as the message payload.
+ * <li><i>resultBeanId</i> - If the endpoint returns a result then the payload of that result is bounded to the resultBeanId.
+ * When the resultBeanId isn't set then the result is discarded. If the resultBeanId is set then the
+ * endpoint is forced to distpatch synchronous.
+ * <li><i>messagePropertiesBeanId</i> - Properties that will be set on the message before dispatching.
+ * The MuleDispatcher messageProperties attribute section explains how to set the message properties
+ * <li><i>messageProperties</i> - if true, non serializable attributes from the Smooks ExecutionContext will no be included. Default is true.
+ * </ul>
+ *
+ * <h3>MuleDispatcher messageProperties attribute</h3>
+ * Message properties are defined as folows:
+ * <pre>
+ * <resource-config selector="order">
+ * <resource>org.milyn.smooks.mule.MuleDispatcher</resource>
+ * <param name="endpointName">testEndpoint</param>
+ * <param name="beanId">test</param>
+ * <param name="messageProperties">
+ * <property name="prop1" value="prop1Value" />
+ * <property name="prop2">prop2Value</property>
+ * <property name="intProp" value="10" type="Integer" />
+ * <property name="dateProp" value="2008-07-11 12:30:56" type="DateTime" />
+ * </param>
+ * </resource-config>
+ *
+ * <resource-config selector="decoder:DateTime">
+ * <resource>org.milyn.javabean.decoders.DateDecoder</resource>
+ * <param name="format">yyyy-MM-dd HH:mm:ss</param>
+ * </resource-config>
+ * </pre>
+ *
+ * The following points explain the four properties:
+ * <ol>
+ * <li>The first property uses a attribute to set the value.
+ * <li>The second property uses the property element content to set the value.
+ * <li>The third property uses the type attribute to define a Integer type. This will convert the value into an Integer. This uses the standard DataDecoder feature from Smooks.
+ * <li>The fourth property uses the type attribute to define a custom configured Date type. This will convert the value into a Date. The configuration is set in the resource-config with the "decoder:DateTime" selector. This uses the standard DataDecoder feature from Smooks.
+ * </ol>
+ *
+ * <h3>Description of property attributes</h3>
+ * <ul>
+ * <li><i>name</i> - The message property name (required)
+ * <li><i>value</i> - The value of the property. The property element content can also be set. If both are set then the value attribute is used.
+ * <li><i>type</i> - The type of the property value. This uses the standard DataDecoder feature from Smooks. DataDecoders can be configured using
+ * a "decoder:decoderName" resource-config selector. The decoderName must be set as type then. (Default: String)
+ * </ul>
+ *
* @author <a href="mailto:maurice@...">Maurice Zeijen</a>
- *
*/
@VisitBeforeIf(condition = "parameters.containsKey('executeBefore') && parameters.executeBefore.value == 'true'")
@VisitAfterIf(condition = "!parameters.containsKey('executeBefore') || parameters.executeBefore.value != 'true'")
@@ -58,6 +130,16 @@
@VisitAfterReport(summary = "Dispatch to endpoint '${resource.parameters.endpointName}'.", detailTemplate = "reporting/MuleDispatcher.html")
public class MuleDispatcher implements DOMElementVisitor, SAXVisitBefore, SAXVisitAfter {
+ private static final String MESSAGE_PROPERTIES_PARAMETER_TYPE = "type";
+
+ private static final String MESSAGE_PROPERTIES_PARAMETER_VALUE = "value";
+
+ private static final String MESSAGE_PROPERTIES_ATTRIBUTE_NAME = "name";
+
+ private static final String MESSAGE_PROPERTIES_NODE_NAME = "property";
+
+ private static final String PARAMETER_MESSAGE_PROPERTIES = "messageProperties";
+
private static final Logger log = LoggerFactory.getLogger(MuleDispatcher.class);
@ConfigParam(use=Use.REQUIRED)
@@ -77,24 +159,40 @@
@Config
private SmooksResourceConfiguration config;
-
+ /**
+ * {@inheritDoc}
+ */
public void visitBefore(Element element, ExecutionContext executionContext) throws SmooksException {
dispatch(executionContext);
}
+ /**
+ * {@inheritDoc}
+ */
public void visitBefore(SAXElement element, ExecutionContext executionContext) throws SmooksException, IOException {
dispatch(executionContext);
}
+ /**
+ * {@inheritDoc}
+ */
public void visitAfter(Element element, ExecutionContext executionContext) throws SmooksException {
dispatch(executionContext);
}
+ /**
+ * {@inheritDoc}
+ */
public void visitAfter(SAXElement element, ExecutionContext executionContext) throws SmooksException, IOException {
dispatch(executionContext);
}
+ /**
+ * Dispatches a message to an endpoint
+ *
+ * @param executionContext
+ */
private void dispatch(ExecutionContext executionContext) {
Object payload = null;
if(beanId != null) {
@@ -131,6 +229,13 @@
}
}
+ /**
+ * Creates the message properties map from the static message properties and the possible
+ * properties from the Map found under the messageProperties bean Id.
+ *
+ * @param executionContext
+ * @return
+ */
@SuppressWarnings("unchecked")
private Map<String, Object> createMessagePropertiesMap(ExecutionContext executionContext) {
@@ -151,30 +256,38 @@
}
+ /**
+ * Processes the static message properties.
+ * Because these are static it is only done the first time. From that point on
+ * a cached result is used.
+ *
+ * @param executionContext
+ * @return
+ */
private HashMap<String, Object> getStaticMessageProperties(ExecutionContext executionContext) {
if(staticMessageProperties == null) {
HashMap<String, Object> lMessageProperties = new HashMap<String, Object>();
- Parameter messagePropertiesParam = config.getParameter("messageProperties");
+ Parameter messagePropertiesParam = config.getParameter(PARAMETER_MESSAGE_PROPERTIES);
if (messagePropertiesParam != null) {
Element messagePropertiesParamElement = messagePropertiesParam.getXml();
if(messagePropertiesParamElement != null) {
- NodeList properties = messagePropertiesParamElement.getElementsByTagName("property");
+ NodeList properties = messagePropertiesParamElement.getElementsByTagName(MESSAGE_PROPERTIES_NODE_NAME);
for (int i = 0; properties != null && i < properties.getLength(); i++) {
Element node = (Element)properties.item(i);
- String name = DomUtils.getAttributeValue(node, "name");
+ String name = DomUtils.getAttributeValue(node, MESSAGE_PROPERTIES_ATTRIBUTE_NAME);
if(StringUtils.isBlank(name)) {
throw new SmooksConfigurationException("The 'name' attribute isn't a defined or empty for the message property: " + node);
}
name = name.trim();
- String rawValue = DomUtils.getAttributeValue(node, "value");
+ String rawValue = DomUtils.getAttributeValue(node, MESSAGE_PROPERTIES_PARAMETER_VALUE);
if(rawValue == null) {
rawValue = DomUtils.getAllText(node, true);
if(StringUtils.isBlank(rawValue)) {
@@ -188,7 +301,7 @@
DataDecoder dataDecoder = null;
- String type = DomUtils.getAttributeValue(node, "type");
+ String type = DomUtils.getAttributeValue(node, MESSAGE_PROPERTIES_PARAMETER_TYPE);
if(type != null) {
type = type.trim();
@@ -214,6 +327,14 @@
return staticMessageProperties;
}
+ /**
+ * Retrieves the decoder of a certain type.
+ *
+ * @param executionContext
+ * @param type
+ * @return
+ * @throws DataDecodeException
+ */
private DataDecoder getDecoder(ExecutionContext executionContext, String type) throws DataDecodeException {
@SuppressWarnings("unchecked")
List<DataDecoder> decoders = executionContext.getDeliveryConfig().getObjects("decoder:" + type);
Modified: trunk/mule1/core/src/main/java/org/milyn/smooks/mule/NamedOutboundEndpointMuleDispatcher.java (64 => 65)
--- trunk/mule1/core/src/main/java/org/milyn/smooks/mule/NamedOutboundEndpointMuleDispatcher.java 2008-07-24 09:23:13 UTC (rev 64)
+++ trunk/mule1/core/src/main/java/org/milyn/smooks/mule/NamedOutboundEndpointMuleDispatcher.java 2008-07-24 15:00:14 UTC (rev 65)
@@ -29,6 +29,8 @@
import org.mule.umo.routing.CouldNotRouteOutboundMessageException;
/**
+ * This is the Mule 2.x implementation of the NamedEndpointMuleDispatcher. It
+ * is used by the Smook {@link MuleDispatcher} to actually dispatch a message.
*
* @author <a href="mailto:maurice@...">Maurice Zeijen</a>
*/
Modified: trunk/mule1/core/src/main/java/org/milyn/smooks/mule/Router.java (64 => 65)
--- trunk/mule1/core/src/main/java/org/milyn/smooks/mule/Router.java 2008-07-24 09:23:13 UTC (rev 64)
+++ trunk/mule1/core/src/main/java/org/milyn/smooks/mule/Router.java 2008-07-24 15:00:14 UTC (rev 65)
@@ -16,7 +16,7 @@
package org.milyn.smooks.mule;
-import static org.mule.config.i18n.MessageFactory.*;
+import static org.mule.config.i18n.MessageFactory.createStaticMessage;
import java.io.IOException;
import java.util.HashMap;
@@ -39,8 +39,79 @@
import org.xml.sax.SAXException;
/**
+ * The Router intended to be used with the Mule ESB.
+ * <p/>
+ * <h3>Usage:</h3>
+ * Declare the router in the Mule configuration file:
+ * <pre>
+ * <outbound-router>
+ * <router className="org.milyn.smooks.mule.Router">
+ * <endpoint name="order" address="jms://order.queue"/>
+ * <endpoint name="order-important" address="jms://order.important.queue"/>
+ * <properties>
+ * <property name="configFile" value="/router-smooks-config.xml" />
+ * </properties>
+ * </router>
+ * </outbound-router>
*
+ * <b>Required properties:</b>
+ * <property name="configFile" value="smooks-config.xml" />
+ *
+ * <b>Optional properties:</b>
+ * <property name="resultType" value="STRING" />
+ * <property name="reportPath" value="/tmp/smooks-report.html" />
+ * <property name="executionContextAsMessageProperty" value="false" />
+ * <property name="executionContextMessagePropertyKey" value="SmooksExecutionContext" />
+ * <property name="excludeNonSerializables" value="false" />
+ * </pre>
+ *
+ * <h3>Description of configuration properties</h3>
+ * <ul>
+ * <li><i>configFile</i> - the Smooks configuration file. Can be a path on the file system or on the classpath.
+ * <li><i>reportPath</i> - specifies the path and file name for generating a Smooks Execution Report. This is a development tool.
+ * <li><i>executionContextAsMessageProperty</i> - If set to "true" then the attributes map of the Smooks execution context is added to the message
+ * properties of every message that gets created by this router. The property key is defined with
+ * the executionContextMessagePropertyKey property. Default is "false"
+ * <li><i>executionContextMessagePropertyKey</i> - The property key under which the execution context is put. Default is "SmooksExecutionContext"
+ * <li><i>excludeNonSerializables</i> - if true, non serializable attributes from the Smooks ExecutionContext will no be included. Default is true.
+ * </ul>
+ *
+ * <h3>Defining Endpoints</h3>
+ * As normal with Mule router you must at least define one endpoint to route the messages to. For this router it is
+ * also required that you define the name of the router. That name is used as reference within the Smooks configuration
+ * so that it knows which endpoint to use.
+ *
+ * <h3>Using the Smooks MuleDispatcher</h3>
+ * Within the Smooks Router the {@link org.milyn.smooks.mule.MuleDispatcher} resource is used to actually route the message parts
+ * to one of the defined endpoints (using the endpoint name). The following example demonstrates how to configure a MuleDispatcher:
+ *
+ * <pre>
+ * <resource-config selector="order">
+ * <resource>org.milyn.smooks.mule.MuleDispatcher</resource>
+ * <param name="endpointName">orderEndpoint</param>
+ * <param name="beanId">orderBean</param>
+ * </resource-config>
+ * </pre>
+ *
+ * In this example Smooks calls the {@link MuleDispatcher} when it is in the visit after phase of the "order" element. The {@link MuleDispatcher}
+ * creates a new Mule message and it will use the object found under the beanId "orderBean" in the Smooks BeanMap as it's payload. It
+ * then dispatches that message to the endpoint with the name "orderEndpoint".
+ * <p/>
+ * More information on the configuration options of the {@link MuleDispatcher} can be found in the javadoc of the {@link MuleDispatcher} itself.
+ *
+ * <h3>Accessing Smooks ExecutionContext attributes</h3>
+ * When the {@link MuleDispatcher} dispatches a message and if the "executionContextAsMessageProperty" property
+ * is set to <code>true</code> then the MuleDispatcher will make the attributes that have been set in the
+ * ExecutionContext at that moment available for other actions in the Mule ESB by setting the attributes map as a property of the message.
+ * The attributes can be accessed by using the key defined under the property "executionContextMessagePropertyKey". Default
+ * "SmooksExecutionContext" is used, which is set under the constant {@link #MESSAGE_PROPERTY_KEY_EXECUTION_CONTEXT}.
+ * An example of accessing the attributes map is:
+ * <pre>
+ * umoEventContext.getMessage().get( SmooksTransformer.MESSAGE_PROPERTY_KEY_EXECUTION_CONTEXT );
+ * </pre>
+ *
* @author <a href="mailto:maurice@...">Maurice Zeijen</a>
+ *
*/
public class Router extends FilteringOutboundRouter {
Modified: trunk/mule1/core/src/main/java/org/milyn/smooks/mule/Transformer.java (64 => 65)
--- trunk/mule1/core/src/main/java/org/milyn/smooks/mule/Transformer.java 2008-07-24 09:23:13 UTC (rev 64)
+++ trunk/mule1/core/src/main/java/org/milyn/smooks/mule/Transformer.java 2008-07-24 15:00:14 UTC (rev 65)
@@ -37,58 +37,87 @@
import org.xml.sax.SAXException;
/**
- * SmooksTransformer intended to be used with the Mule ESB.
+ * The Transformer intended to be used with the Mule ESB.
* <p/>
* <h3>Usage:</h3>
* <pre>
- * Declare the tranformer in the Mule configuration file:
+ * Declare the transformer in the Mule configuration file:
* <transformers>
- * <transformer name="SmooksTransformer" className="org.milyn.smooks.mule.Transformer"/>
+ * <transformer name="SmooksTransformer" className="org.milyn.smooks.mule.Transformer">
+ * <properties>
+ * <property name="configFile" value="smooks-config.xml"/>
+ * </properties>
+ * </transformer>
* </transformers>
*
- * Configure the transformer with a router:
+ * Configure the router with a transformer:
* <inbound-router>
* <endpoint address="stream://System.in" transformers="SmooksTransformer"/>
* </inbound-router>
*
+ * Required properties:
+ * <property name="configFile" value="smooks-config.xml" />
+ *
* Optional properties:
- * <property name="smooksConfig" value="smooks-config.xml" />
* <property name="resultType" value="STRING" />
+ * <property name="javaResultBeanId" value="orderBean" />
+ * <property name="resultClass" value="javax.xml.transform.dom.DOMResult" />
+ * <property name="resultFactoryClass" value="your.package.SomeResultFactory" />
+ * <property name="reportPath" value="/tmp/smooks-report.html" />
+ * <property name="executionContextAsMessageProperty" value="false" />
+ * <property name="executionContextMessagePropertyKey" value="SmooksExecutionContext" />
* <property name="excludeNonSerializables" value="false" />
- * <property name="reportPath" value="/tmp/smooks-report.html" />
- * <property name="javaResultBeanId" value="orderBean" />
* </pre>
*
* <h3>Description of configuration properties</h3>
* <ul>
- * <li><i>smooksConfig</i> - the Smooks configuration file. Can be a path on the file system or on the classpath.
+ * <li><i>configFile</i> - the Smooks configuration file. Can be a path on the file system or on the classpath.
* <li><i>resultType</i> - type of result expected from Smooks ("STRING", "BYTES", "JAVA", "RESULT", "NORESULT"). Default is "STRING".
- * <li><i>excludeNonSerializables</i> - if true, non serializable attributes from the Smooks ExecutionContext will no be included. Default is true.
- * <li><i>reportPath</i> - specifies the path and file name for generating a Smooks Execution Report. This is a development tool.
* <li><i>javaResultBeanId</i> - specifies 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 result.
- * <li><i>resultClass</i> - specifies the Class to construct the {@link Result} Object from
- * <li><i>resultFactoryClass</i> - specifies the Factory class which will create the {@link Result} Object to be used as the result Source.
+ * <li><i>resultClass</i> - When the resultType is set to "RESULT" then this attribute defines the Result Class which will be used.
+ * The class must implement the {@link javax.xml.transform.Result} interface and must have an argumentless constructor.
+ * <li><i>resultFactoryClass</i> - When the resultType is set to "RESULT" then this attribute defines the ResultFactory Class which will be used
+ * to create the Result Class. The class must implement the {@link org.milyn.smooks.mule.ResultFactory} interface and
+ * must have an argumentless constructor.
+ * <li><i>reportPath</i> - specifies the path and file name for generating a Smooks Execution Report. This is a development tool.
+ * <li><i>executionContextAsMessageProperty</i> - If set to "true" then the attributes map of the Smooks execution context is added to the message properties.
+ * The property key is defined with the executionContextMessagePropertyKey property. Default is "false"
+ * <li><i>executionContextMessagePropertyKey</i> - The property key under which the execution context is put. Default is "SmooksExecutionContext"
+ * <li><i>excludeNonSerializables</i> - if true, non serializable attributes from the Smooks ExecutionContext will no be included. Default is true.
* </ul>
*
* <h3>Accessing Smooks ExecutionContext attributes</h3>
- * After Smooks has performed the filtering the transform method will make the attributes that have been set in the
- * the ExecutionContext available for other actions in the Mule ESB.
- * The attributes (Map) can be accessed by using the {@link #MESSAGE_PROPERTY_KEY_EXECUTION_CONTEXT} key like this:
+ * After Smooks finished filtering they payload and if the "executionContextAsMessageProperty" property is set to <code>true</code>
+ * then the transform method will make the attributes that have been set in the the ExecutionContext available for
+ * other actions in the Mule ESB by setting the attributes map as a property of the message.
+ * The attributes can be accessed by using the key defined under the property "executionContextMessagePropertyKey". Default
+ * "SmooksExecutionContext" is used, which is set under the constant {@link #MESSAGE_PROPERTY_KEY_EXECUTION_CONTEXT}.
+ * An example of accessing the attributes map is:
* <pre>
- * umoEventContext.getMessage().get( SmooksTransformer.EXECUTION_CONTEXT_ATTR_MAP_KEY );
- * </pre>
+ * umoEventContext.getMessage().get( SmooksTransformer.MESSAGE_PROPERTY_KEY_EXECUTION_CONTEXT );
+ * </pre>
+ *
* <h3>Specifying the Source and Result Types</h3>
* From the object payload data type, this Transformer is able to automatically determine the type of
* {@link javax.xml.transform.Source} to use (via the Smooks {@link PayloadProcessor}). The
* {@link javax.xml.transform.Result} type to be used can be specified via the "resultType"
- * property, as outlined above.
+ * property, as outlined above. If the result is required but shouldn't be a String, Bytes or Java then it
+ * is also possible to set the "resultClass" property or the "resultFactoryClass" properties. The resultType
+ * must be set to "RESULT" then.
+ * By defining the resultClass property with a classname the transformer will try to instantiate that class.
+ * The defined class must have a argumentless constructor and must implement the {@link javax.xml.transform.Result} interface.
+ * The resulting Result object will be used by Smooks as result and will be returned as the transformation result.
+ * If you need to use a factory class to instantiate the result class then this is also possible. By
+ * setting the "resultFactoryClass" with the class name of the factory the transformer will instantiate
+ * that factory an use its createResult() method to instantiate the Result object.
+ * The Factory must implement the {@link org.milyn.smooks.mule.ResultFactory} and have an argumentless constructor.
+ *
* <p/>
- * It is expected that the above mechanism will be satisfactory for most usecase, but not all.
- * For the other usecases, this action supports {@link org.milyn.container.plugin.SourceResult}
+ * It is expected that the above mechanism will be satisfactory for most use cases, but not all.
+ * For the other use cases, this transformer supports {@link org.milyn.container.plugin.SourceResult}
* payloads. This allows you to manually specify other Source and Result
- * types, which is of particular interest with respect to the Result type e.g. for streaming
- * the Result to a file etc.
+ * types.
*
* @author <a href="mailto:maurice@...">Maurice Zeijen</a>
*
Modified: trunk/mule2/core/src/main/java/org/milyn/smooks/mule/NamedOutboundEndpointMuleDispatcher.java (64 => 65)
--- trunk/mule2/core/src/main/java/org/milyn/smooks/mule/NamedOutboundEndpointMuleDispatcher.java 2008-07-24 09:23:13 UTC (rev 64)
+++ trunk/mule2/core/src/main/java/org/milyn/smooks/mule/NamedOutboundEndpointMuleDispatcher.java 2008-07-24 15:00:14 UTC (rev 65)
@@ -29,6 +29,8 @@
import org.mule.routing.outbound.AbstractOutboundRouter;
/**
+ * This is the Mule 2.x implementation of the NamedEndpointMuleDispatcher. It
+ * is used by the Smook {@link MuleDispatcher} to actually dispatch a message.
*
* @author <a href="mailto:maurice@...">Maurice Zeijen</a>
*/
Modified: trunk/mule2/core/src/main/java/org/milyn/smooks/mule/Router.java (64 => 65)
--- trunk/mule2/core/src/main/java/org/milyn/smooks/mule/Router.java 2008-07-24 09:23:13 UTC (rev 64)
+++ trunk/mule2/core/src/main/java/org/milyn/smooks/mule/Router.java 2008-07-24 15:00:14 UTC (rev 65)
@@ -41,7 +41,74 @@
import org.xml.sax.SAXException;
/**
+ * The Router intended to be used with the Mule ESB.
+ * <p/>
+ * <h3>Usage:</h3>
+ * Declare the router in the Mule configuration file:
+ * <pre>
+ * <outbound>
+ * <smooks:router configFile="/smooks-config.xml">
+ * <jms:outbound-endpoint name="order" queue="order.queue"/>
+ * <jms:outbound-endpoint name="order-important" queue="order.important.queue"/>
+ * </smooks:router>
+ * </outbound>
*
+ * <b>Required attributes/properties:</b>
+ * <property name="configFile" value="smooks-config.xml" />
+ *
+ * <b>Optional attributes/properties:</b>
+ * <property name="resultType" value="STRING" />
+ * <property name="reportPath" value="/tmp/smooks-report.html" />
+ * <property name="executionContextAsMessageProperty" value="false" />
+ * <property name="executionContextMessagePropertyKey" value="SmooksExecutionContext" />
+ * <property name="excludeNonSerializables" value="false" />
+ * </pre>
+ *
+ * <h3>Description of configuration attributes/properties</h3>
+ * <ul>
+ * <li><i>configFile</i> - the Smooks configuration file. Can be a path on the file system or on the classpath.
+ * <li><i>reportPath</i> - specifies the path and file name for generating a Smooks Execution Report. This is a development tool.
+ * <li><i>executionContextAsMessageProperty</i> - If set to "true" then the attributes map of the Smooks execution context is added to the message
+ * properties of every message that gets created by this router. The property key is defined with
+ * the executionContextMessagePropertyKey property. Default is "false"
+ * <li><i>executionContextMessagePropertyKey</i> - The property key under which the execution context is put. Default is "SmooksExecutionContext"
+ * <li><i>excludeNonSerializables</i> - if true, non serializable attributes from the Smooks ExecutionContext will no be included. Default is true.
+ * </ul>
+ *
+ * <h3>Defining Endpoints</h3>
+ * As normal with Mule router you must at least define one endpoint to route the messages to. For this router it is
+ * also required that you define the name of the router. That name is used as reference within the Smooks configuration
+ * so that it knows which endpoint to use.
+ *
+ * <h3>Using the Smooks MuleDispatcher</h3>
+ * Within the Smooks Router the {@link org.milyn.smooks.mule.MuleDispatcher} resource is used to actually route the message parts
+ * to one of the defined endpoints (using the endpoint name). The following example demonstrates how to configure a MuleDispatcher:
+ *
+ * <pre>
+ * <resource-config selector="order">
+ * <resource>org.milyn.smooks.mule.MuleDispatcher</resource>
+ * <param name="endpointName">orderEndpoint</param>
+ * <param name="beanId">orderBean</param>
+ * </resource-config>
+ * </pre>
+ *
+ * In this example Smooks calls the {@link MuleDispatcher} when it is in the visit after phase of the "order" element. The {@link MuleDispatcher}
+ * creates a new Mule message and it will use the object found under the beanId "orderBean" in the Smooks BeanMap as it's payload. It
+ * then dispatches that message to the endpoint with the name "orderEndpoint".
+ * <p/>
+ * More information on the configuration options of the {@link MuleDispatcher} can be found in the javadoc of the {@link MuleDispatcher} itself.
+ *
+ * <h3>Accessing Smooks ExecutionContext attributes</h3>
+ * When the {@link MuleDispatcher} dispatches a message and if the "executionContextAsMessageProperty" property
+ * is set to <code>true</code> then the MuleDispatcher will make the attributes that have been set in the
+ * ExecutionContext at that moment available for other actions in the Mule ESB by setting the attributes map as a property of the message.
+ * The attributes can be accessed by using the key defined under the property "executionContextMessagePropertyKey". Default
+ * "SmooksExecutionContext" is used, which is set under the constant {@link #MESSAGE_PROPERTY_KEY_EXECUTION_CONTEXT}.
+ * An example of accessing the attributes map is:
+ * <pre>
+ * umoEventContext.getMessage().get( SmooksTransformer.MESSAGE_PROPERTY_KEY_EXECUTION_CONTEXT );
+ * </pre>
+ *
* @author <a href="mailto:maurice@...">Maurice Zeijen</a>
*
*/
Modified: trunk/mule2/core/src/main/java/org/milyn/smooks/mule/Transformer.java (64 => 65)
--- trunk/mule2/core/src/main/java/org/milyn/smooks/mule/Transformer.java 2008-07-24 09:23:13 UTC (rev 64)
+++ trunk/mule2/core/src/main/java/org/milyn/smooks/mule/Transformer.java 2008-07-24 15:00:14 UTC (rev 65)
@@ -25,6 +25,7 @@
import org.apache.commons.lang.StringUtils;
import org.milyn.Smooks;
import org.milyn.container.ExecutionContext;
+import org.milyn.container.plugin.PayloadProcessor;
import org.milyn.event.report.HtmlReportGenerator;
import org.mule.api.MuleMessage;
import org.mule.api.lifecycle.InitialisationException;
@@ -35,11 +36,86 @@
import org.slf4j.LoggerFactory;
import org.xml.sax.SAXException;
-/**
- * SmooksTransformer intended to be used with the Mule ESB.
- *
- *
- * @author <a href="mailto:maurice@...">Maurice Zeijen</a> */
+/**
+ * The Transformer intended to be used with the Mule ESB.
+ * <p/>
+ * <h3>Usage:</h3>
+ * <pre>
+ * Declare the transformer in the Mule configuration file:
+ * <smooks:transformer name="smooksTransformer" configFile="/transformer-smooks-config.xml" />
+ *
+ * Configure the router with a transformer:
+ * <inbound>
+ * <vm:inbound-endpoint path="messageInput" transformer-refs="smooksTransformer"/>
+ * </inbound>
+ *
+ * Required attributes/properties:
+ * <property name="configFile" value="smooks-config.xml" />
+ *
+ * Optional attributes/properties:
+ * <property name="resultType" value="STRING" />
+ * <property name="javaResultBeanId" value="orderBean" />
+ * <property name="resultClass" value="javax.xml.transform.dom.DOMResult" />
+ * <property name="resultFactoryClass" value="your.package.SomeResultFactory" />
+ * <property name="reportPath" value="/tmp/smooks-report.html" />
+ * <property name="executionContextAsMessageProperty" value="false" />
+ * <property name="executionContextMessagePropertyKey" value="SmooksExecutionContext" />
+ * <property name="excludeNonSerializables" value="false" />
+ * </pre>
+ *
+ * <h3>Description of configuration attributes/properties</h3>
+ * <ul>
+ * <li><i>configFile</i> - the Smooks configuration file. Can be a path on the file system or on the classpath.
+ * <li><i>resultType</i> - type of result expected from Smooks ("STRING", "BYTES", "JAVA", "RESULT", "NORESULT"). Default is "STRING".
+ * <li><i>javaResultBeanId</i> - specifies 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 result.
+ * <li><i>resultClass</i> - When the resultType is set to "RESULT" then this attribute defines the Result Class which will be used.
+ * The class must implement the {@link javax.xml.transform.Result} interface and must have an argumentless constructor.
+ * <li><i>resultFactoryClass</i> - When the resultType is set to "RESULT" then this attribute defines the ResultFactory Class which will be used
+ * to create the Result Class. The class must implement the {@link org.milyn.smooks.mule.ResultFactory} interface and
+ * must have an argumentless constructor.
+ * <li><i>reportPath</i> - specifies the path and file name for generating a Smooks Execution Report. This is a development tool.
+ * <li><i>executionContextAsMessageProperty</i> - If set to "true" then the attributes map of the Smooks execution context is added to the message properties.
+ * The property key is defined with the executionContextMessagePropertyKey property. Default is "false"
+ * <li><i>executionContextMessagePropertyKey</i> - The property key under which the execution context is put. Default is "SmooksExecutionContext"
+ * <li><i>excludeNonSerializables</i> - if true, non serializable attributes from the Smooks ExecutionContext will no be included. Default is true.
+ * </ul>
+ *
+ * <h3>Accessing Smooks ExecutionContext attributes</h3>
+ * After Smooks finished filtering they payload and if the "executionContextAsMessageProperty" property is set to <code>true</code>
+ * then the transform method will make the attributes that have been set in the the ExecutionContext available for
+ * other actions in the Mule ESB by setting the attributes map as a property of the message.
+ * The attributes can be accessed by using the key defined under the property "executionContextMessagePropertyKey". Default
+ * "SmooksExecutionContext" is used, which is set under the constant {@link #MESSAGE_PROPERTY_KEY_EXECUTION_CONTEXT}.
+ * An example of accessing the attributes map is:
+ * <pre>
+ * umoEventContext.getMessage().get( SmooksTransformer.MESSAGE_PROPERTY_KEY_EXECUTION_CONTEXT );
+ * </pre>
+ *
+ * <h3>Specifying the Source and Result Types</h3>
+ * From the object payload data type, this Transformer is able to automatically determine the type of
+ * {@link javax.xml.transform.Source} to use (via the Smooks {@link PayloadProcessor}). The
+ * {@link javax.xml.transform.Result} type to be used can be specified via the "resultType"
+ * property, as outlined above. If the result is required but shouldn't be a String, Bytes or Java then it
+ * is also possible to set the "resultClass" property or the "resultFactoryClass" properties. The resultType
+ * must be set to "RESULT" then.
+ * By defining the resultClass property with a classname the transformer will try to instantiate that class.
+ * The defined class must have a argumentless constructor and must implement the {@link javax.xml.transform.Result} interface.
+ * The resulting Result object will be used by Smooks as result and will be returned as the transformation result.
+ * If you need to use a factory class to instantiate the result class then this is also possible. By
+ * setting the "resultFactoryClass" with the class name of the factory the transformer will instantiate
+ * that factory an use its createResult() method to instantiate the Result object.
+ * The Factory must implement the {@link org.milyn.smooks.mule.ResultFactory} and have an argumentless constructor.
+ *
+ * <p/>
+ * It is expected that the above mechanism will be satisfactory for most use cases, but not all.
+ * For the other use cases, this transformer supports {@link org.milyn.container.plugin.SourceResult}
+ * payloads. This allows you to manually specify other Source and Result
+ * types.
+ *
+ * @author <a href="mailto:maurice@...">Maurice Zeijen</a>
+ *
+ */
public class Transformer extends AbstractMessageAwareTransformer {
private static final Logger log = LoggerFactory.getLogger(Transformer.class);
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "MuleForge Dev" group. To post to this group, send email to muleforgedev@... To unsubscribe from this group, send email to muleforgedev-unsubscribe@... For more options, visit this group at http://groups.google.com/group/muleforgedev?hl=en -~----------~----~----~----~------~----~------~--~---
---------------------------------------------------------------------
To unsubscribe from this list, please visit:
http://admin.muleforge.org/manage_email
|
