QPID-1946: updated management interfaces with API version information for recent additions/changes

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

4 files changed, 48 insertions, 5 deletions

diff --git a/qpid/java/management/common/src/main/java/org/apache/qpid/management/common/mbeans/LoggingManagement.java b/qpid/java/management/common/src/main/java/org/apache/qpid/management/common/mbeans/LoggingManagement.java
index 5d89b0d92d..d9c5f59bd0 100644
--- a/qpid/java/management/common/src/main/java/org/apache/qpid/management/common/mbeans/LoggingManagement.java
+++ b/qpid/java/management/common/src/main/java/org/apache/qpid/management/common/mbeans/LoggingManagement.java
@@ -29,6 +29,10 @@ import org.apache.qpid.management.common.mbeans.annotations.MBeanOperationParame
 import javax.management.MBeanOperationInfo;
 import javax.management.openmbean.TabularData;
 
+/**
+ * Interface for the LoggingManagement MBean
+ * @since Qpid JMX API 1.2
+ */
 public interface LoggingManagement
 {
     String TYPE = "LoggingManagement";
@@ -43,6 +47,7 @@ public interface LoggingManagement
     /**
      * Attribute to represent the log4j xml configuration file's LogWatch interval.
      * @return The logwatch interval in seconds.
+     * @since Qpid JMX API 1.2
      */
     @MBeanAttribute(name="Log4jLogWatchInterval", 
                     description = "The log4j xml configuration file LogWatch interval (in seconds). 0 indicates not being checked.")
@@ -51,6 +56,7 @@ public interface LoggingManagement
     /**
      * Attribute to represent the available log4j logger output levels.
      * @return The logging level names.
+     * @since Qpid JMX API 1.2
      */
     @MBeanAttribute(name="AvailableLoggerLevels", description = "The values to which log output level can be set.")
     String[] getAvailableLoggerLevels();
@@ -63,6 +69,7 @@ public interface LoggingManagement
      * @param logger The name of the logger
      * @param level The level to set the logger to
      * @return True if successful, false if unsuccessful (eg if an invalid level is specified) 
+     * @since Qpid JMX API 1.2
      */
     @MBeanOperation(name = "setRuntimeLoggerLevel", description = "Set the runtime logging level for an active log4j logger.",
                     impact = MBeanOperationInfo.ACTION)
@@ -72,6 +79,7 @@ public interface LoggingManagement
     /**
      * Retrieves a TabularData set of the active log4j loggers and their levels
      * @return TabularData set of CompositeData rows with logger name and level, or null if there is a problem with the TabularData type 
+     * @since Qpid JMX API 1.2
      */
     @MBeanOperation(name = "viewEffectiveRuntimeLoggerLevels", description = "View the effective runtime logging level " +
     		        "for active log4j logger's.", impact = MBeanOperationInfo.INFO)
@@ -81,6 +89,7 @@ public interface LoggingManagement
      * Sets the level of the active Log4J RootLogger
      * @param level The level to set the RootLogger to
      * @return True if successful, false if unsuccessful (eg if an invalid level is specified) 
+     * @since Qpid JMX API 1.2
      */
     @MBeanOperation(name = "setRuntimeRootLoggerLevel", description = "Set the runtime logging level for the active log4j Root Logger.",
                     impact = MBeanOperationInfo.ACTION)
@@ -89,6 +98,7 @@ public interface LoggingManagement
     /**
      * Attribute to represent the level of the active Log4J RootLogger
      * @return The level of the RootLogger.
+     * @since Qpid JMX API 1.2
      */
     @MBeanAttribute(name = "getRuntimeRootLoggerLevel", description = "Get the runtime logging level for the active log4j Root Logger.")
     String getRuntimeRootLoggerLevel();
@@ -102,6 +112,7 @@ public interface LoggingManagement
      * @param level The level to set the logger to
      * @return True if successful, false if unsuccessful (eg if an invalid logger or level is specified) 
      * @throws IOException if there is an error parsing the configuration file.
+     * @since Qpid JMX API 1.2
      */
     @MBeanOperation(name = "setConfigFileLoggerLevel", description = "Set the logging level for an existing logger " +
     		         "in the log4j xml configuration file", impact = MBeanOperationInfo.ACTION)
@@ -112,6 +123,7 @@ public interface LoggingManagement
      * Retrieves a TabularData set of the existing Log4J loggers within the xml configuration file
      * @return TabularData set of CompositeData rows with logger name and level, or null if there is a problem with the TabularData type 
      * @throws IOException if there is an error parsing the configuration file.
+     * @since Qpid JMX API 1.2
      */
     @MBeanOperation(name = "viewConfigFileLoggerLevels", description = "Get the logging level defined for the logger's " +
     		        "in the log4j xml configuration file.", impact = MBeanOperationInfo.INFO)
@@ -122,6 +134,7 @@ public interface LoggingManagement
      * @param level The level to set the logger to
      * @return True if successful, false if not (eg an invalid level is specified, or root logger level isnt already defined) 
      * @throws IOException if there is an error parsing the configuration file.
+     * @since Qpid JMX API 1.2
      */
     @MBeanOperation(name = "setConfigFileRootLoggerLevel", description = "Set the logging level for the Root Logger " +
     		        "in the log4j xml configuration file.", impact = MBeanOperationInfo.ACTION)
@@ -130,6 +143,7 @@ public interface LoggingManagement
     /**
      * Attribute to represent the level of the Log4J RootLogger within the xml configuration file
      * @return The level of the RootLogger, or null if it is not present
+     * @since Qpid JMX API 1.2
      */
     @MBeanAttribute(name = "getConfigFileRootLoggerLevel", description = "Get the logging level for the Root Logger " +
                     "in the log4j xml configuration file.")
diff --git a/qpid/java/management/common/src/main/java/org/apache/qpid/management/common/mbeans/ManagedQueue.java b/qpid/java/management/common/src/main/java/org/apache/qpid/management/common/mbeans/ManagedQueue.java
index f5f1e3e1ea..d0d80fde0f 100644
--- a/qpid/java/management/common/src/main/java/org/apache/qpid/management/common/mbeans/ManagedQueue.java
+++ b/qpid/java/management/common/src/main/java/org/apache/qpid/management/common/mbeans/ManagedQueue.java
@@ -80,6 +80,8 @@ public interface ManagedQueue
 
     /**
      * Size of messages in the queue
+     * 
+     * Since Qpid JMX API 1.2 this operation returns in units of bytes. Prior to this, the result was in units of kilobytes.
      * @return
      * @throws IOException
      */
@@ -181,6 +183,8 @@ public interface ManagedQueue
     /**
      * This is useful for setting notifications or taking required action if the size of messages
      * stored in the queue increases over this limit.
+     * 
+     * Since Qpid JMX API 1.2 this operation returns in units of bytes. Prior to this, the result was in units of kilobytes.
      * @return threshold high value for Queue Depth
      * @throws IOException
      */
@@ -220,9 +224,12 @@ public interface ManagedQueue
 
     /**
      * Deletes the first message from top.
+     * 
+     * Deprecated as of Qpid JMX API 1.3
      * @throws IOException
      * @throws JMException
      */
+    @Deprecated
     @MBeanOperation(name="deleteMessageFromTop", description="Deletes the first message from top",
                     impact= MBeanOperationInfo.ACTION)
     void deleteMessageFromTop() throws IOException, JMException;
diff --git a/qpid/java/management/common/src/main/java/org/apache/qpid/management/common/mbeans/ServerInformation.java b/qpid/java/management/common/src/main/java/org/apache/qpid/management/common/mbeans/ServerInformation.java
index 49549e76fb..c158c26857 100644
--- a/qpid/java/management/common/src/main/java/org/apache/qpid/management/common/mbeans/ServerInformation.java
+++ b/qpid/java/management/common/src/main/java/org/apache/qpid/management/common/mbeans/ServerInformation.java
@@ -24,19 +24,32 @@ import java.io.IOException;
 
 import org.apache.qpid.management.common.mbeans.annotations.MBeanAttribute;
 
-
+/**
+ * Interface for the ServerInformation MBean
+ * @since Qpid JMX API 1.3
+ */
 public interface ServerInformation
 {
     String TYPE = "ServerInformation";
     int VERSION = 1;
     
-    //API version info for the brokers JMX management interface
+    /* API version info for the brokers JMX management interface
+     * 
+     *  As the ServerInformation MBean was only introduced in Qpid JMX API 1.3 it is not possible to use it
+     *  for identifying earlier broker JMX APIs for compatibility purposes. However, this can be accomplished 
+     *  by inspecting the 'version' property key of the UserManagement MBean JMX ObjectName. This was first 
+     *  introduced in Qpid JMX API 1.2 and so if present in the absence of the ServerInformation MBean 
+     *  indicates that version. If it is not present then a null value will be returned upon inspection and 
+     *  Qpid JMX API 1.1 can be assumed.
+     */
     int QPID_JMX_API_MAJOR_VERSION = 1;
     int QPID_JMX_API_MINOR_VERSION = 3;
-
+    
+    
     /**
      * Attribute to represent the major version number for the management API.
      * @return The major management version number.
+     * @since Qpid JMX API 1.3
      */
     @MBeanAttribute(name="ManagementApiMajorVersion", 
                     description = "The major version number for the broker management API")
@@ -45,6 +58,7 @@ public interface ServerInformation
     /**
      * Attribute to represent the minor version number for the management API.
      * @return The minor management version number.
+     * @since Qpid JMX API 1.3
      */
     @MBeanAttribute(name="ManagementApiMinorVersion", 
                     description = "The minor version number for the broker management API")
@@ -53,6 +67,7 @@ public interface ServerInformation
     /**
      * Attribute to represent the build version string.
      * @return The build version string
+     * @since Qpid JMX API 1.3
      */
     @MBeanAttribute(name="BuildVersion", 
                     description = "The repository build version string")
@@ -61,6 +76,7 @@ public interface ServerInformation
     /**
      * Attribute to represent the product version string.
      * @return The product version string
+     * @since Qpid JMX API 1.3
      */
     @MBeanAttribute(name="ProductVersion", 
                     description = "The product version string")
diff --git a/qpid/java/management/common/src/main/java/org/apache/qpid/management/common/mbeans/UserManagement.java b/qpid/java/management/common/src/main/java/org/apache/qpid/management/common/mbeans/UserManagement.java
index 1ef9ef12cd..6c973b438d 100644
--- a/qpid/java/management/common/src/main/java/org/apache/qpid/management/common/mbeans/UserManagement.java
+++ b/qpid/java/management/common/src/main/java/org/apache/qpid/management/common/mbeans/UserManagement.java
@@ -43,7 +43,9 @@ public interface UserManagement
 
     //********** Operations *****************//
     /**
-     * set password for user
+     * set password for user.
+     * 
+     * Since Qpid JMX API 1.2 this operation expects plain text passwords to be provided. Prior to this, MD5 hashed passwords were supplied.
      *
      * @param username The username to create
      * @param password The password for the user
@@ -75,6 +77,8 @@ public interface UserManagement
     /**
      * Create users with given details
      *
+     * Since Qpid JMX API 1.2 this operation expects plain text passwords to be provided. Prior to this, MD5 hashed passwords were supplied.
+     * 
      * @param username The username to create
      * @param password The password for the user
      * @param read     The set of permission to give the new user
@@ -105,10 +109,12 @@ public interface UserManagement
 
     /**
      * Reload the date from disk
+     * 
+     * Since Qpid JMX API 1.2 this operation reloads the password and authorisation files. Prior to this, only the authorisation file was reloaded.
      *
      * @return The result of the operation
      */
-    @MBeanOperation(name = "reloadData", description = "Reload the authentication file from disk.",
+    @MBeanOperation(name = "reloadData", description = "Reload the authentication and authorisation files from disk.",
                     impact = MBeanOperationInfo.ACTION)
     boolean reloadData();