Index: oak-core/src/main/java/org/apache/jackrabbit/oak/api/jmx/RepositoryManagementMBean.java
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
--- oak-core/src/main/java/org/apache/jackrabbit/oak/api/jmx/RepositoryManagementMBean.java	(date 1395747665000)
+++ oak-core/src/main/java/org/apache/jackrabbit/oak/api/jmx/RepositoryManagementMBean.java	(revision )
@@ -20,32 +20,63 @@
 package org.apache.jackrabbit.oak.api.jmx;
 
 import javax.annotation.Nonnull;
+import javax.management.openmbean.CompositeData;
 
 /**
- * This interface exposes repository management operations
- * and the status of such operations. This interface only
- * provides high level functionality for starting certain
- * management operations and monitoring their outcomes.
- * Parametrisation and configuration of the operations is
- * beyond the scope of this interface and must be achieved
- * by other means. For example through a dedicated MBean of
- * the specific service providing the respective functionality.
- * Furthermore not all operations might be available in all
- * deployments or at all times. However the status should give
- * a clear indication for this case.
+ * This interface exposes repository management operations and the status
+ * of such operations. This interface only provides high level functionality
+ * for starting certain management operations and monitoring their outcomes.
+ * Parametrisation and configuration of the operations is beyond the scope
+ * of this interface and must be achieved by other means. For example
+ * through a dedicated MBean of the specific service providing the
+ * respective functionality. Furthermore not all operations might be
+ * available in all deployments or at all times. However the status should
+ * give a clear indication for this case.
  * <p>
- * The status of an operation is an opaque string describing
- * in a human readable form what the operation currently does,
- * which might depend on the particular implementation performing
- * the operation. However the status status <em>must</em> always
- * indicate whether an operation is ongoing, not started  or
- * terminated. In the latter case it <em>must</em> indicate whether
- * it terminated successfully or whether it failed. Furthermore the
- * status <em>must</em> indicate when an operation is not available.
- * In all cases the status <em>may</em> provide additional
- * information like e.g. how far an ongoing operation progressed,
- * what time it took to complete a terminated operation, or information
- * about what caused a terminated operation to fail.
+ * The status of an operation is represented by a {@code CompositeData}
+ * instance consisting at least of the items {@code code}, {@code id},
+ * and {@code message}. Implementations are free to add further items.
+ * <p>
+ * The {@code code} item is an integer encoding the current status of
+ * the respective operation. Valid values and its semantics are:
+ * <ul>
+ *     <li>{@code 0}: <em>Operation not available</em>. For example
+ *     because the system does not implement the operation or the
+ *     system is in a state where it does not allow the operation to
+ *     be carried out (e.g. the operation is already running). The
+ *     {@code message} should give further indication of the exact
+ *     reason.</li>
+ *     <li>{@code 1}: <em>Status not available</em>. Usually because
+ *     there was no prior attempt to start the operation. The
+ *     {@code message} should give further indication of the exact
+ *     reason.</li>
+ *     <li>{@code 2}: <em>Operation initiated</em>. The {@code message}
+ *     should give further information of when the operation was
+ *     initiated. <em>Note:</em> in contrast to
+ *     <em>operation started</em> the operations reporting this status
+ *     do not report the full lifecycle. Rather does this status mean
+ *     that the operation will be performed some time in the future
+ *     without impacting overall system behaviour.</li>
+ *     <li>{@code 3}: <em>Operation started</em>. The {@code message}
+ *     should give further information of when the operation was started.
+ *     As soon as the operation actually runs the status will change
+ *     to <em>operation running</em> and eventually to
+ *     <em>operation succeeded</em> or <em>operation failed</em>
+ *     depending on its outcome. </li>
+ *     <li>{@code 4}: <em>Operation running</em>.</li>
+ *     <li>{@code 5}: <em>Operation succeeded</em>. The {@code message} should
+ *     give further information on how long the operation took to
+ *     complete.</li>
+ *     <li>{@code 6}: Operation failed. The {@code message} should give
+ *     further information on the reason for the failure.</li>
+ * </ul>
+ * <p>
+ * In all cases the {@code message} may provide additional information
+ * that might be useful in the context of the operation.
+ * <p>
+ * The {@code id} is an identifier for the invocation of an operation.
+ * It is reported as a part of the status for clients to relate the
+ * status to invocation.
  */
 public interface RepositoryManagementMBean {
     String TYPE = "RepositoryManagement";
@@ -56,16 +87,16 @@
      * @return  the status of the operation right after it was initiated
      */
     @Nonnull
-    String startBackup();
+    CompositeData startBackup();
 
     /**
      * Backup status
      *
      * @return  the status of the ongoing operation or if none the terminal
-     * status of the last operation or {@code null} if none.
+     * status of the last operation or <em>Status not available</em> if none.
      */
     @Nonnull
-    String getBackupStatus();
+    CompositeData getBackupStatus();
 
     /**
      * Initiate a restore operation.
@@ -73,16 +104,16 @@
      * @return  the status of the operation right after it was initiated
      */
     @Nonnull
-    String startRestore();
+    CompositeData startRestore();
 
     /**
      * Restore status
      *
      * @return  the status of the ongoing operation or if none the terminal
-     * status of the last operation or {@code null} if none.
+     * status of the last operation or <em>Status not available</em> if none.
      */
     @Nonnull
-    String getRestoreStatus();
+    CompositeData getRestoreStatus();
 
     /**
      * Initiate a data store garbage collection operation
@@ -90,16 +121,16 @@
      * @return  the status of the operation right after it was initiated
      */
     @Nonnull
-    String startDataStoreGC();
+    CompositeData startDataStoreGC();
 
     /**
      * Data store garbage collection status
      *
      * @return  the status of the ongoing operation or if none the terminal
-     * status of the last operation or {@code null} if none.
+     * status of the last operation or <em>Status not available</em> if none.
      */
     @Nonnull
-    String getDataStoreGCStatus();
+    CompositeData getDataStoreGCStatus();
 
     /**
      * Initiate a revision garbage collection operation
@@ -107,16 +138,16 @@
      * @return  the status of the operation right after it was initiated
      */
     @Nonnull
-    String startRevisionGC();
+    CompositeData startRevisionGC();
 
     /**
      * Revision garbage collection status
      *
      * @return  the status of the ongoing operation or if none the terminal
-     * status of the last operation or {@code null} if none.
+     * status of the last operation or <em>Status not available</em> if none.
      */
     @Nonnull
-    String getRevisionGCStatus();
+    CompositeData getRevisionGCStatus();
 
     /**
      * Creates a new checkpoint of the latest root of the tree. The checkpoint