QPID-1903 - Applied patch from Bryan Kearney

git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk/qpid@784252 13f79535-47bb-0310-9956-ffa450edef68

20 files changed, 95 insertions, 11 deletions

diff --git a/java/agent/src/main/java/org/apache/qpid/agent/Agent.java b/java/agent/src/main/java/org/apache/qpid/agent/Agent.java
index fa80694017..80348c52d9 100644
--- a/java/agent/src/main/java/org/apache/qpid/agent/Agent.java
+++ b/java/agent/src/main/java/org/apache/qpid/agent/Agent.java
@@ -54,8 +54,9 @@ import org.apache.qpid.transport.codec.BBEncoder;
 import org.apache.qpid.transport.codec.Decoder;
 
 /**
- * Agent
- * 
+ * The main class for interacting with the QMF bus. Objects which are
+ * to be managed can be registered with the agent, as can classes
+ * to be exposed via the schema.
  */
 public class Agent implements MessageListener
 {
@@ -96,6 +97,7 @@ public class Agent implements MessageListener
                 systemId.toString()));
     }
 
+
     public void register(ManagedObject managedObject)
     {
         Class managedClass = managedObject.getObjectClass();
@@ -120,6 +122,10 @@ public class Agent implements MessageListener
         }
     }
 
+    /**
+     * Starts up the agent. Many bean containers may call this by
+     * default which aids in deployment
+     */
     public void start()
     {
         log.debug(String.format("Agent with uid %s and name %s starting",
@@ -161,6 +167,9 @@ public class Agent implements MessageListener
         }
     }
 
+    /**
+     * Send an event object to the bus
+     */
     public void raiseEvent(Object value, EventSeverity sev)
     {
         log.debug(String.format("Sending event of class %s with Severity %s",
@@ -201,7 +210,7 @@ public class Agent implements MessageListener
             throw new AgentException(e);
         }
         byte[] magic = dec.readBytes(3);
-        if (magic[0] != 'A' || magic[1] != 'M' || magic[2] != '2')
+        if (magic[0] != 'A' || magic[1] != 'M' || magic[2] != '3')
         {
             throw new AgentException("bad magic: " + new String(magic));
         }
@@ -436,7 +445,7 @@ public class Agent implements MessageListener
         enc.init();
         enc.writeUint8((short) 'A');
         enc.writeUint8((short) 'M');
-        enc.writeUint8((short) '2');
+        enc.writeUint8((short) '3');
         enc.writeUint8((short) opcode);
         enc.writeUint32(sequence);
         return enc;
diff --git a/java/agent/src/main/java/org/apache/qpid/agent/ManagedEJB.java b/java/agent/src/main/java/org/apache/qpid/agent/ManagedEJB.java
index c27ff7acc6..4c5bc594d3 100644
--- a/java/agent/src/main/java/org/apache/qpid/agent/ManagedEJB.java
+++ b/java/agent/src/main/java/org/apache/qpid/agent/ManagedEJB.java
@@ -27,6 +27,11 @@ import org.apache.qpid.agent.binding.BindingUtils;
 import org.apache.qpid.agent.binding.MethodBinding;
 import org.apache.qpid.agent.binding.PropertyBinding;
 
+/**
+ * Wrapper classe for adding EJBS which are to be 
+ * managed by the QMF Agent. The jndi location and the
+ * public interface to exposed are used to generate the schema.
+ */
 public class ManagedEJB extends ManagedObjectBase
 {
     protected String className;
diff --git a/java/agent/src/main/java/org/apache/qpid/agent/ManagedObject.java b/java/agent/src/main/java/org/apache/qpid/agent/ManagedObject.java
index 679ee81d76..aa3bbf3894 100644
--- a/java/agent/src/main/java/org/apache/qpid/agent/ManagedObject.java
+++ b/java/agent/src/main/java/org/apache/qpid/agent/ManagedObject.java
@@ -23,6 +23,9 @@ package org.apache.qpid.agent;
 import org.apache.qpid.agent.binding.MethodBinding;
 import org.apache.qpid.agent.binding.PropertyBinding;
 
+/**
+ * Objects which are to be managed and controlled by the QMF Agent.
+ */
 public interface ManagedObject
 {
     public abstract long getId();
@@ -46,4 +49,4 @@ public interface ManagedObject
     public void setManagedClassName(String aName);
 
     public void setManagedPackageName(String aName);
-}
\ No newline at end of file
+}
diff --git a/java/agent/src/main/java/org/apache/qpid/agent/ManagedPOJO.java b/java/agent/src/main/java/org/apache/qpid/agent/ManagedPOJO.java
index 9a707fe09e..061334b252 100644
--- a/java/agent/src/main/java/org/apache/qpid/agent/ManagedPOJO.java
+++ b/java/agent/src/main/java/org/apache/qpid/agent/ManagedPOJO.java
@@ -26,6 +26,10 @@ import org.apache.qpid.agent.binding.BindingUtils;
 import org.apache.qpid.agent.binding.MethodBinding;
 import org.apache.qpid.agent.binding.PropertyBinding;
 
+/**
+ * Wrapper classe for adding POJOS which are to be 
+ * managed by the QMF Agent. 
+ */
 public class ManagedPOJO extends ManagedObjectBase implements ManagedObject
 {
     private Log log = LogFactory.getLog(ManagedPOJO.class);
diff --git a/java/agent/src/main/java/org/apache/qpid/agent/annotations/QMFEvent.java b/java/agent/src/main/java/org/apache/qpid/agent/annotations/QMFEvent.java
index 06ef46c648..319c471445 100644
--- a/java/agent/src/main/java/org/apache/qpid/agent/annotations/QMFEvent.java
+++ b/java/agent/src/main/java/org/apache/qpid/agent/annotations/QMFEvent.java
@@ -27,6 +27,11 @@ import java.lang.annotation.Documented;
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
+/**
+ * Tells the QMF Agent that this object will be passed as a
+ * QMF event. This will cause only properties to be sent across
+ * the wire.
+ */
 @Target(TYPE)
 @Retention(RUNTIME)
 @Documented
diff --git a/java/agent/src/main/java/org/apache/qpid/agent/annotations/QMFHide.java b/java/agent/src/main/java/org/apache/qpid/agent/annotations/QMFHide.java
index c173e701a5..f3824ff228 100644
--- a/java/agent/src/main/java/org/apache/qpid/agent/annotations/QMFHide.java
+++ b/java/agent/src/main/java/org/apache/qpid/agent/annotations/QMFHide.java
@@ -27,6 +27,10 @@ import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
+/**
+ * Causes the property which is annotated to not be added to the
+ * QMF schema when it is built.
+ */
 @Target(ElementType.METHOD)
 @Retention(RUNTIME)
 @Documented
diff --git a/java/agent/src/main/java/org/apache/qpid/agent/annotations/QMFObject.java b/java/agent/src/main/java/org/apache/qpid/agent/annotations/QMFObject.java
index c883051fda..d737dbb852 100644
--- a/java/agent/src/main/java/org/apache/qpid/agent/annotations/QMFObject.java
+++ b/java/agent/src/main/java/org/apache/qpid/agent/annotations/QMFObject.java
@@ -27,6 +27,11 @@ import java.lang.annotation.Documented;
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
+/**
+ * Tells the QMF Agent that this object will be a managed 
+ * object. This will allow users to query for it, as well as
+ * invoke methods on it.
+ */
 @Target(TYPE)
 @Retention(RUNTIME)
 @Documented
diff --git a/java/agent/src/main/java/org/apache/qpid/agent/annotations/QMFProperty.java b/java/agent/src/main/java/org/apache/qpid/agent/annotations/QMFProperty.java
index 82e1b3a1af..f309fa95b5 100644
--- a/java/agent/src/main/java/org/apache/qpid/agent/annotations/QMFProperty.java
+++ b/java/agent/src/main/java/org/apache/qpid/agent/annotations/QMFProperty.java
@@ -27,6 +27,9 @@ import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
+/**
+ * Controls the QMF schema which is generated for this property.
+ */
 @Target(ElementType.FIELD)
 @Retention(RUNTIME)
 @Documented
diff --git a/java/agent/src/main/java/org/apache/qpid/agent/annotations/QMFSeeAlso.java b/java/agent/src/main/java/org/apache/qpid/agent/annotations/QMFSeeAlso.java
index 924e12a574..c14ea11ca4 100644
--- a/java/agent/src/main/java/org/apache/qpid/agent/annotations/QMFSeeAlso.java
+++ b/java/agent/src/main/java/org/apache/qpid/agent/annotations/QMFSeeAlso.java
@@ -27,6 +27,10 @@ import java.lang.annotation.Documented;
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
+/**
+ * Augements the schema generation process to look for known
+ * subclasses of a type. Modeled after the JAXB @XMLSeeAlso.
+ */
 @Target(TYPE)
 @Retention(RUNTIME)
 @Documented
diff --git a/java/agent/src/main/java/org/apache/qpid/agent/annotations/QMFType.java b/java/agent/src/main/java/org/apache/qpid/agent/annotations/QMFType.java
index 2b5aaa1983..5d43276a55 100644
--- a/java/agent/src/main/java/org/apache/qpid/agent/annotations/QMFType.java
+++ b/java/agent/src/main/java/org/apache/qpid/agent/annotations/QMFType.java
@@ -27,6 +27,11 @@ import java.lang.annotation.Documented;
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
+/**
+ * Tells the QMF Agent that this object will be a type only
+ * This will cause only properties to be sent across
+ * the wire.
+ */
 @Target(TYPE)
 @Retention(RUNTIME)
 @Documented
diff --git a/java/agent/src/main/java/org/apache/qpid/agent/binding/BindingContext.java b/java/agent/src/main/java/org/apache/qpid/agent/binding/BindingContext.java
index 480d8b526c..aa84b9dd54 100644
--- a/java/agent/src/main/java/org/apache/qpid/agent/binding/BindingContext.java
+++ b/java/agent/src/main/java/org/apache/qpid/agent/binding/BindingContext.java
@@ -32,6 +32,10 @@ import org.apache.qpid.agent.annotations.QMFObject;
 import org.apache.qpid.agent.annotations.QMFSeeAlso;
 import org.apache.qpid.agent.annotations.QMFType;
 
+/**
+ * Contains the mappings from java classes to QMF schema and back.
+ * There is one context per agent, and it contains all the metadata.
+ */
 public class BindingContext
 {
     private static Log log = LogFactory.getLog(BindingContext.class);
diff --git a/java/agent/src/main/java/org/apache/qpid/agent/binding/ClassBinding.java b/java/agent/src/main/java/org/apache/qpid/agent/binding/ClassBinding.java
index d1ad04adef..3de978e34b 100644
--- a/java/agent/src/main/java/org/apache/qpid/agent/binding/ClassBinding.java
+++ b/java/agent/src/main/java/org/apache/qpid/agent/binding/ClassBinding.java
@@ -37,6 +37,9 @@ import org.apache.qpid.agent.annotations.QMFHide;
 import org.apache.qpid.transport.codec.Decoder;
 import org.apache.qpid.transport.codec.Encoder;
 
+/**
+ * Binding information from a custom java class to a QMF schema
+ */
 public class ClassBinding implements TypeBinding
 {
     private static Log log = LogFactory.getLog(ClassBinding.class);
diff --git a/java/agent/src/main/java/org/apache/qpid/agent/binding/EnumBinding.java b/java/agent/src/main/java/org/apache/qpid/agent/binding/EnumBinding.java
index 37d20341d9..ef4abc743b 100644
--- a/java/agent/src/main/java/org/apache/qpid/agent/binding/EnumBinding.java
+++ b/java/agent/src/main/java/org/apache/qpid/agent/binding/EnumBinding.java
@@ -25,6 +25,9 @@ import org.apache.commons.logging.LogFactory;
 import org.apache.qpid.transport.codec.Decoder;
 import org.apache.qpid.transport.codec.Encoder;
 
+/**
+ * Binding information from a java enum to a QMF schema
+ */
 public class EnumBinding extends ClassBinding
 {
     private static Log log = LogFactory.getLog(EnumBinding.class);
diff --git a/java/agent/src/main/java/org/apache/qpid/agent/binding/ListBinding.java b/java/agent/src/main/java/org/apache/qpid/agent/binding/ListBinding.java
index fcdd20a0c1..0de8a07107 100644
--- a/java/agent/src/main/java/org/apache/qpid/agent/binding/ListBinding.java
+++ b/java/agent/src/main/java/org/apache/qpid/agent/binding/ListBinding.java
@@ -30,6 +30,9 @@ import org.apache.qpid.transport.codec.BBEncoder;
 import org.apache.qpid.transport.codec.Decoder;
 import org.apache.qpid.transport.codec.Encoder;
 
+/**
+ * Binding information from a java list to a QMF schema.
+ */
 public class ListBinding implements TypeBinding
 {
     private static Log log = LogFactory.getLog(ListBinding.class);
@@ -46,12 +49,17 @@ public class ListBinding implements TypeBinding
     {
         List list = (List) value;
         BBEncoder newEncoder = new BBEncoder(10);
-        newEncoder.writeUint32(list.size());
-        for (Object obj : list)
-        {
-            TypeBinding type = bctx.getTypeBinding(obj.getClass());
-            newEncoder.writeUint8(type.getCode());
-            type.encode(newEncoder, obj);
+        if (list != null) {
+            newEncoder.writeUint32(list.size());
+            for (Object obj : list)
+            {
+                TypeBinding type = bctx.getTypeBinding(obj.getClass());
+                newEncoder.writeUint8(type.getCode());
+                type.encode(newEncoder, obj);
+            }
+        }
+        else {
+            newEncoder.writeUint32(0) ;
         }
         enc.writeVbin32(newEncoder.buffer().array());
     }
diff --git a/java/agent/src/main/java/org/apache/qpid/agent/binding/MapBinding.java b/java/agent/src/main/java/org/apache/qpid/agent/binding/MapBinding.java
index 8b0df57e89..80889f3b4e 100644
--- a/java/agent/src/main/java/org/apache/qpid/agent/binding/MapBinding.java
+++ b/java/agent/src/main/java/org/apache/qpid/agent/binding/MapBinding.java
@@ -30,6 +30,9 @@ import org.apache.qpid.transport.codec.BBEncoder;
 import org.apache.qpid.transport.codec.Decoder;
 import org.apache.qpid.transport.codec.Encoder;
 
+/**
+ * Binding information from a java Map to a QMF schema.
+ */
 public class MapBinding implements TypeBinding
 {
     private static Log log = LogFactory.getLog(MapBinding.class);
diff --git a/java/agent/src/main/java/org/apache/qpid/agent/binding/MethodBinding.java b/java/agent/src/main/java/org/apache/qpid/agent/binding/MethodBinding.java
index d6dec92b13..fc05c7393a 100644
--- a/java/agent/src/main/java/org/apache/qpid/agent/binding/MethodBinding.java
+++ b/java/agent/src/main/java/org/apache/qpid/agent/binding/MethodBinding.java
@@ -29,6 +29,9 @@ import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
 import org.apache.qpid.transport.codec.Encoder;
 
+/**
+ * Metadata for mapping a method to a QMF schema
+ */
 public class MethodBinding
 {
     private final String name;
diff --git a/java/agent/src/main/java/org/apache/qpid/agent/binding/ParameterBinding.java b/java/agent/src/main/java/org/apache/qpid/agent/binding/ParameterBinding.java
index 3c707dc9cb..7362976e0e 100644
--- a/java/agent/src/main/java/org/apache/qpid/agent/binding/ParameterBinding.java
+++ b/java/agent/src/main/java/org/apache/qpid/agent/binding/ParameterBinding.java
@@ -25,6 +25,9 @@ import java.util.Map;
 
 import org.apache.qpid.transport.codec.Encoder;
 
+/**
+ * Metadata for mapping a method argument to a QMF schema
+ */
 public class ParameterBinding
 {
     private final String name;
diff --git a/java/agent/src/main/java/org/apache/qpid/agent/binding/PropertyBinding.java b/java/agent/src/main/java/org/apache/qpid/agent/binding/PropertyBinding.java
index 6c94dc5b17..22ad8cd8e4 100644
--- a/java/agent/src/main/java/org/apache/qpid/agent/binding/PropertyBinding.java
+++ b/java/agent/src/main/java/org/apache/qpid/agent/binding/PropertyBinding.java
@@ -27,6 +27,10 @@ import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
 import org.apache.qpid.transport.codec.Encoder;
 
+
+/**
+ * Metadata for mapping a java property (getter/setter) to a QMF schema
+ */
 public class PropertyBinding
 {
     private static Log log = LogFactory.getLog(PropertyBinding.class);
diff --git a/java/agent/src/main/java/org/apache/qpid/agent/binding/QMFTypeBinding.java b/java/agent/src/main/java/org/apache/qpid/agent/binding/QMFTypeBinding.java
index 9d86f27c1a..11ccf1b1a7 100644
--- a/java/agent/src/main/java/org/apache/qpid/agent/binding/QMFTypeBinding.java
+++ b/java/agent/src/main/java/org/apache/qpid/agent/binding/QMFTypeBinding.java
@@ -28,6 +28,9 @@ import java.util.UUID;
 import org.apache.qpid.transport.codec.Decoder;
 import org.apache.qpid.transport.codec.Encoder;
 
+/**
+ * Basic type mappings for QMF schema
+ */
 public abstract class QMFTypeBinding implements TypeBinding
 {
     private static final Map<Class<?>, QMFTypeBinding> TYPES = new HashMap<Class<?>, QMFTypeBinding>();
diff --git a/java/agent/src/main/java/org/apache/qpid/agent/binding/TypeBinding.java b/java/agent/src/main/java/org/apache/qpid/agent/binding/TypeBinding.java
index 492e533fdc..97ec943bfd 100644
--- a/java/agent/src/main/java/org/apache/qpid/agent/binding/TypeBinding.java
+++ b/java/agent/src/main/java/org/apache/qpid/agent/binding/TypeBinding.java
@@ -23,6 +23,9 @@ package org.apache.qpid.agent.binding;
 import org.apache.qpid.transport.codec.Decoder;
 import org.apache.qpid.transport.codec.Encoder;
 
+/**
+ * Binding between Java Type and QMF type
+ */
 public interface TypeBinding
 {
     public Object decode(Decoder dec);