[jboss-svn-commits] JBL Code SVN: r15699 - labs/jbossesb/trunk/product/rosetta/src/org/jboss/soa/esb/message/mapping.

[jboss-svn-commits at lists.jboss.org]

Author: mark.little at jboss.com
Date: 2007-10-09 19:09:57 -0400 (Tue, 09 Oct 2007)
New Revision: 15699

Modified:
   labs/jbossesb/trunk/product/rosetta/src/org/jboss/soa/esb/message/mapping/ObjectMapper.java
Log:
http://jira.jboss.com/jira/browse/JBESB-954

Modified: labs/jbossesb/trunk/product/rosetta/src/org/jboss/soa/esb/message/mapping/ObjectMapper.java
===================================================================
--- labs/jbossesb/trunk/product/rosetta/src/org/jboss/soa/esb/message/mapping/ObjectMapper.java	2007-10-09 22:48:38 UTC (rev 15698)
+++ labs/jbossesb/trunk/product/rosetta/src/org/jboss/soa/esb/message/mapping/ObjectMapper.java	2007-10-09 23:09:57 UTC (rev 15699)
@@ -32,11 +32,35 @@
 import org.mvel.MVEL;
 
 /**
- * Extracts objects from an ESB message and puts them into a Map, which can be used for later processsing.
+ * Extracts objects from an ESB message and puts them into a Map, which can be
+ * used for later processsing, based on expressions. This class is used internally
+ * within the jBPM and Rules integrations. It may be useful elsewhere.
  * 
+ * Likewise, it can be used to take a list of Objects and place them into a Message
+ * based on the same type of expressions.
+ * 
+ * It is based on the notion of an ESB Message Object Path (MOP). The path
+ * should follow the syntax:
+ * 
+ * location.objectname.<bean>...
+ * 
+ * location : one of [body, property, attachment]
+ * objectname: name of the object. Since attachments can be named or numbered, this can be a
+ * number too and will be converted to an integer value. If a stringified number is used elsewhere
+ * to name an object then it will not be interpreted as an integer, i.e., it will remain as a string.
+ * <bean> : optionally you traverse a bean graph by specifying bean names.
+ * 
+ * examples : 
+ * properties.Order, gets the property object named "Order"
+ * attachment.1, gets the first attachment Object 
+ * attachment.FirstAttachment, gets the attachment named 'FirstAttachment'
+ * body.foo, gets the named Object foo
+ * body.1 gets the named Object 1
+ * 
  * @author kurt.stam at jboss.com
- *
+ * 
  */
+
 public class ObjectMapper 
 {
     /** Name to get the byte[] content */
@@ -57,17 +81,22 @@
     private static final char EXPRESSION_SEPARATOR = '.' ;
 
     /**
+     * Given a message and a series of MOPs, traverse the content and create
+     * a list of Objects.
      * 
-     * body.myObject will add 'myObject', while
-     * body.myObject.mySubObject will create an entry of 'mySubObject'. 
+     * For example:
      * 
+     * body.myObject MOP will add 'myObject', while
+     * body.myObject.mySubObject MOP will create an entry of 'mySubObject'. 
+     * 
      * in the returned List.
      * 
      * @param message - the message 
      * @param messageObjectPathList - the key represents the query to get the object from
      *                      from the message.
      *                      
-     * @return List of Objects.
+     * @return List of Objects pulled from the input Message. Will never be null, but could be
+     * of zero length.
      * 
      * @throws ObjectMappingException
      */
@@ -104,6 +133,15 @@
      * Set objects on the message using a OGNL expression syntax to describe the position
      * in the message where the object needs to be attached.
      * 
+     * Each Object within the supplied Map should be associated with an expression that
+     * will be used to determine where in the Message it should be placed.
+     * 
+     * location.objectname...
+     * 
+     * location  : one of [body, property, attachment, header]
+     * objectname: name of the object name, attachments can be named or numbered, so for
+     *             attachments this can be a number too.
+     * 
      * @param message - the message on which the objects will be placed
      * @param expressionAndObject map containing objects with their expression
      * @return the message with the objects attached.
@@ -188,7 +226,7 @@
         return object;
     }
     /**
-     * Sets an object somewhere on the Message, based on the value of the expression.
+     * Sets an object somewhere on the Message, based on the value of the expression (MOP).
      * The expression is OGNL based. MVEL is used to do the actual mapping.
      * 
      * @param message - on which the object will be placed.