[880359] JavaDoc used for Remote API is inconsistent with API

I made another pass at the remote API jdoc, ensuring that all methods have at
least minimal jdoc with the correct @param, @return, @throws, @deprecated and
@SInCE (starting with RHQ 4.5) annotations.

modules/enterprise/server/jar/src/main/java/org/rhq/enterprise/server/alert/AlertManagerRemote.java

@@ -46,7 +46,6 @@ public interface AlertManagerRemote {
      */
     int deleteAlerts(Subject subject, int[] alertIds);
 
-    // TODO (jshaughn) Should this be deprecated, seems an odd method to expose.
     /**
      * Requires Manage Settings permission.
      *

modules/enterprise/server/jar/src/main/java/org/rhq/enterprise/server/authz/RoleManagerRemote.java

@@ -143,6 +143,8 @@ public interface RoleManagerRemote {
      * @param subject The logged in user's subject.
      * @param roleId
      * @param bundleGroupIds
+     *
+     * @since 4.9
      */
     void addBundleGroupsToRole(Subject subject, int roleId, int[] bundleGroupIds);
 
@@ -159,6 +161,8 @@ public interface RoleManagerRemote {
      * @param subject
      * @param bundleGroupId
      * @param roleIds
+     *
+     * @since 4.9
      */
     void addRolesToBundleGroup(Subject subject, int bundleGroupId, int[] roleIds);
 
@@ -175,6 +179,8 @@ public interface RoleManagerRemote {
      * @param subject
      * @param roleId
      * @param bundleGroupIds
+     *
+     * @since 4.9
      */
     void setAssignedBundleGroups(Subject subject, int roleId, int[] bundleGroupIds);
 
@@ -193,6 +199,8 @@ public interface RoleManagerRemote {
      * @param subject user attempting to remove the groups from the role
      * @param roleId
      * @param bundleGroupIds
+     *
+     * @since 4.9
      */
     void removeBundleGroupsFromRole(Subject subject, int roleId, int[] bundleGroupIds);
 
@@ -211,6 +219,8 @@ public interface RoleManagerRemote {
      * @param subject
      * @param bundleGroupId
      * @param roleIds
+     *
+     * @since 4.9
      */
     void removeRolesFromBundleGroup(Subject subject, int bundleGroupId, int[] roleIds);
 

modules/enterprise/server/jar/src/main/java/org/rhq/enterprise/server/bundle/BundleManagerRemote.java

@@ -130,6 +130,8 @@ BundleFile addBundleFileViaByteArray(Subject subject, int bundleVersionId, Strin
      * @return the new BundleFile
      * @throws Exception
      * @see #addBundleFile(Subject, int, String, String, Architecture, InputStream)
+     *
+     * @since 4.8
      */
     BundleFile addBundleFileViaURL(Subject subject, int bundleVersionId, String name, String version,
         Architecture architecture, String bundleFileUrl) throws Exception;
@@ -190,6 +192,8 @@ BundleFile addBundleFileViaPackageVersion(Subject subject, int bundleVersionId,
      * @param subject
      * @param bundleGroupIds
      * @param bundleIds
+     *
+     * @since 4.9
      */
     void assignBundlesToBundleGroups(Subject subject, int[] bundleGroupIds, int[] bundleIds);
 
@@ -248,6 +252,8 @@ BundleDestination createBundleDestination(Subject subject, int bundleId, String
      * @param bundleGroup the new bundle group name the unique bundle group name
      * @return the persisted BundleGroup
      * @throws Exception
+     *
+     * @since 4.9
      */
     BundleGroup createBundleGroup(Subject subject, BundleGroup bundleGroup) throws Exception;
 
@@ -292,6 +298,8 @@ BundleDestination createBundleDestination(Subject subject, int bundleId, String
      * @return the persisted BundleVersion with alot of the internal relationships filled in to help the caller
      *         understand all that this method did.
      * @throws Exception
+     *
+     * @since 4.9
      */
     BundleVersion createInitialBundleVersionViaRecipe(Subject subject, int[] bundleGroupIds, String recipe)
         throws Exception;
@@ -331,6 +339,8 @@ BundleVersion createInitialBundleVersionViaRecipe(Subject subject, int[] bundleG
      * @see org.rhq.enterprise.server.content.ContentManagerRemote#createTemporaryContentHandle()
      * @see org.rhq.enterprise.server.content.ContentManagerRemote#uploadContentFragment(String, byte[], int, int)
      * @see #createBundleVersionViaFile(org.rhq.core.domain.auth.Subject, java.io.File)
+     *
+     * @since 4.10
      */
     BundleVersion createBundleVersionViaContentHandle(Subject subject, String temporaryContentHandle) throws Exception;
 
@@ -353,6 +363,8 @@ BundleVersion createInitialBundleVersionViaRecipe(Subject subject, int[] bundleG
      * @return the persisted BundleVersion with a lot of the internal relationships filled in to help the caller
      *         understand all that this method did. Bundle files specifically are returned.
      * @throws Exception
+     *
+     * @since 4.9
      */
     BundleVersion createInitialBundleVersionViaFile(Subject subject, int[] bundleGroupIds, File distributionFile)
             throws Exception;
@@ -372,6 +384,8 @@ BundleVersion createInitialBundleVersionViaFile(Subject subject, int[] bundleGro
      * @see org.rhq.enterprise.server.content.ContentManagerRemote#createTemporaryContentHandle()
      * @see org.rhq.enterprise.server.content.ContentManagerRemote#uploadContentFragment(String, byte[], int, int)
      * @see #createInitialBundleVersionViaFile(org.rhq.core.domain.auth.Subject, int[], java.io.File)
+     *
+     * @since 4.10
      */
     BundleVersion createInitialBundleVersionViaContentHandle(Subject subject, int[] bundleGroupIds,
         String temporaryContentHandle) throws Exception;
@@ -418,6 +432,8 @@ BundleVersion createInitialBundleVersionViaContentHandle(Subject subject, int[]
      * @return the persisted BundleVersion with a lot of the internal relationships filled in to help the caller
      *         understand all that this method did. Bundle files specifically are returned.
      * @throws Exception
+     *
+     * @since 4.9
      */
     BundleVersion createInitialBundleVersionViaByteArray(Subject subject, int[] bundleGroupIds, byte[] fileBytes)
         throws Exception;
@@ -469,6 +485,8 @@ BundleVersion createInitialBundleVersionViaByteArray(Subject subject, int[] bund
      * @return the persisted BundleVersion with a lot of the internal relationships filled in to help the caller
      *         understand all that this method did. Bundle files specifically are returned.
      * @throws Exception
+     *
+     * @since 4.9
      */
     BundleVersion createInitialBundleVersionViaURL(Subject subject, int[] bundleGroupIds, String distributionFileUrl)
         throws Exception;
@@ -493,6 +511,8 @@ BundleVersion createInitialBundleVersionViaURL(Subject subject, int[] bundleGrou
      *         understand all that this method did. Bundle files specifically are returned.
      * @throws Exception
      * @see #createBundleVersionViaURL(org.rhq.core.domain.auth.Subject, String)
+     *
+     * @since 4.8
      */
     BundleVersion createBundleVersionViaURL(Subject subject, String distributionFileUrl, String username,
         String password) throws Exception;
@@ -519,6 +539,8 @@ BundleVersion createBundleVersionViaURL(Subject subject, String distributionFile
      *         understand all that this method did. Bundle files specifically are returned.
      * @throws Exception
      * @see #createBundleVersionViaURL(org.rhq.core.domain.auth.Subject, String)
+     *
+     * @since 4.9
      */
     BundleVersion createInitialBundleVersionViaURL(Subject subject, int[] bundleGroupIds, String distributionFileUrl,
         String username, String password) throws Exception;
@@ -566,6 +588,8 @@ BundleVersion createInitialBundleVersionViaURL(Subject subject, int[] bundleGrou
      * @param subject user that must have proper permissions
      * @param ids the bundle group id
      * @throws Exception
+     *
+     * @since 4.9
      */
     void deleteBundleGroups(Subject subject, int[] ids) throws Exception;
 
@@ -603,6 +627,8 @@ BundleVersion createInitialBundleVersionViaURL(Subject subject, int[] bundleGrou
      * @param subject
      * @param criteria
      * @return not null
+     *
+     * @since 4.9
      */
     PageList<BundleGroup> findBundleGroupsByCriteria(Subject subject, BundleGroupCriteria criteria);
 
@@ -765,6 +791,8 @@ BundleDeployment scheduleRevertBundleDeployment(Subject subject, int bundleDesti
      * @param subject
      * @param bundleGroupIds
      * @param bundleIds
+     *
+     * @since 4.9
      */
     void unassignBundlesFromBundleGroups(Subject subject, int[] bundleGroupIds, int[] bundleIds);
 
@@ -778,6 +806,8 @@ BundleDeployment scheduleRevertBundleDeployment(Subject subject, int bundleDesti
      * @param bundleGroup the updated bundle group
      * @return the updated BundleGroup
      * @throws Exception
+     *
+     * @since 4.9
      */
     BundleGroup updateBundleGroup(Subject subject, BundleGroup bundleGroup) throws Exception;
 

modules/enterprise/server/jar/src/main/java/org/rhq/enterprise/server/cloud/StorageNodeManagerRemote.java

@@ -53,21 +53,25 @@ public interface StorageNodeManagerRemote {
      * <p>Returns the current configuration of the storage node.</p>
      * <p>For updating the configuration see {@link #retrieveConfiguration(Subject,StorageNode)}.</p>
      * <p>The subject needs to have <code>MANAGE_SETTINGS</code> permissions.</p>
-     * 
+     *
      * @param subject           user that must have proper permissions
      * @param storageNode       the storage node for which we want to get the configuration
      * @return                  instance of {@link StorageNodeConfigurationComposite} with the configuration properties
+     *
+     * @since 4.9
      */
     StorageNodeConfigurationComposite retrieveConfiguration(Subject subject, StorageNode storageNode);
 
     /**
      * <p>Updates the current configuration of the storage node.</p>
      * <p>For retrieving the configuration see {@link #updateConfiguration(Subject,StorageNodeConfigurationComposite)}.</p>
      * <p>The subject needs to have <code>MANAGE_SETTINGS</code> permissions.</p>
-     * 
+     *
      * @param subject                   user that must have proper permissions
      * @param storageNodeConfiguration  instance of {@link StorageNodeConfigurationComposite} with the configuration properties
      * @return                          true if the update was successful
+     *
+     * @since 4.9
      */
     boolean updateConfiguration(Subject subject, StorageNodeConfigurationComposite storageNodeConfiguration);
 
@@ -84,44 +88,52 @@ public interface StorageNodeManagerRemote {
 
     /**
      * <p>Fetches the list of Storage Node related alerts that have not yet been acknowledged.</p>
-     * 
+     *
      * <p>The subject needs to have <code>MANAGE_SETTINGS</code> permissions.</p>
      *
      * @param subject   user that must have proper permissions
      * @return          storage nodes alerts not acknowledged
+     *
+     * @since 4.9
      */
     PageList<Alert> findNotAcknowledgedStorageNodeAlerts(Subject subject);
 
     /**
      * <p>Fetches the list of Storage Node related alerts that have not yet been acknowledged for the
      * specified storage node.</p>
-     * 
+     *
      * <p>The subject needs to have <code>MANAGE_SETTINGS</code> permissions.</p>
      *
      * @param subject     user that must have proper permissions
      * @param storageNode the storage node
      * @return            storage nodes alerts not acknowledged
+     *
+     * @since 4.9
      */
     PageList<Alert> findNotAcknowledgedStorageNodeAlerts(Subject subject, StorageNode storageNode);
 
     /**
      * <p>Fetches all the Storage Node related alerts.</p>
-     * 
+     *
      * <p>The subject needs to have <code>MANAGE_SETTINGS</code> permissions.</p>
      *
      * @param subject   user that must have proper permissions
      * @return          all storage nodes alerts
+     *
+     * @since 4.9
      */
     PageList<Alert> findAllStorageNodeAlerts(Subject subject);
 
     /**
      * <p>Fetches all the Storage Node related alerts for the specified storage node.</p>
-     * 
+     *
      * <p>The subject needs to have <code>MANAGE_SETTINGS</code> permissions.</p>
      *
      * @param subject     user that must have proper permissions
      * @param storageNode the storage node
      * @return            all storage nodes alerts
+     *
+     * @since 4.9
      */
     PageList<Alert> findAllStorageNodeAlerts(Subject subject, StorageNode storageNode);
 
@@ -134,12 +146,14 @@ public interface StorageNodeManagerRemote {
      *  <li><code>ADD_MAINTENANCE</code></li>
      * </ol>
      * <p>This can be run also on a storage node that is in any intermediate modes mentioned above, because of some failure during the deployment process.</p>
-     * 
+     *
      * <p>The subject needs to have <code>MANAGE_SETTINGS</code> permissions.</p>
-     * 
+     *
      * @see                     <a href="https://docs.jboss.org/author/display/RHQ/Deploying+Storage+Nodes">https://docs.jboss.org/author/display/RHQ/Deploying+Storage+Nodes</a>
      * @param sbubject          user that must have proper permissions
      * @param storageNode       storage node to be deployed to the cluster
+     *
+     * @since 4.9
      */
     void deployStorageNode(Subject sbubject, StorageNode storageNode);
 
@@ -148,12 +162,14 @@ public interface StorageNodeManagerRemote {
      * <p>This will move the storage node from operation mode <code>NORMAL</code> or any other mode to the mode <code>UNINSTALL</code>. At the end of the day,
      *  the node is removed also from the relational database. Currently there is no way to add it back.</p>
      * <p>WARNING: Run this operation only if you know what you are doing.</p>
-     *  
+     *
      * <p>The subject needs to have <code>MANAGE_SETTINGS</code> permissions.</p>
-     * 
+     *
      * @see                     <a href="https://docs.jboss.org/author/display/RHQ/Deploying+Storage+Nodes">https://docs.jboss.org/author/display/RHQ/Deploying+Storage+Nodes</a>
      * @param subject          user that must have proper permissions
      * @param storageNode       storage node to be deployed to the cluster
+     *
+     * @since 4.9
      */
     void undeployStorageNode(Subject subject, StorageNode storageNode);
 
@@ -167,10 +183,12 @@ public interface StorageNodeManagerRemote {
      * <strong>NOTE:</strong> Repair is one of the most resource-intensive operations that a storage node performs. Make
      * sure you know what you are doing if you invoke this method outside of the regularly scheduled maintenance window.
      * </p>
-     * 
+     *
      * <p>the subject needs to have <code>MANAGE_SETTINGS</code> permissions.</p>
      *
      * @param subject   user that must have proper permissions
+     *
+     * @since 4.9
      */
     void runClusterMaintenance(Subject subject);
 }

modules/enterprise/server/jar/src/main/java/org/rhq/enterprise/server/configuration/ConfigurationManagerRemote.java

@@ -52,6 +52,7 @@ public interface ConfigurationManagerRemote {
      * @param subject
      * @param criteria
      * @return not null
+     *
      * @since 4.10
      */
     PageList<GroupPluginConfigurationUpdate> findGroupPluginConfigurationUpdatesByCriteria(Subject subject,
@@ -61,6 +62,7 @@ PageList<GroupPluginConfigurationUpdate> findGroupPluginConfigurationUpdatesByCr
      * @param subject
      * @param criteria
      * @return not null
+     *
      * @since 4.10
      */
     PageList<GroupResourceConfigurationUpdate> findGroupResourceConfigurationUpdatesByCriteria(Subject subject,

modules/enterprise/server/jar/src/main/java/org/rhq/enterprise/server/content/ContentManagerRemote.java

@@ -242,6 +242,8 @@ PackageTypeAndVersionFormatComposite findPackageTypeWithVersionFormat(Subject su
      * Creates a temporary file for fragmented content upload.
      *
      * @return a temporary file handle
+     *
+     * @since 4.10
      */
     String createTemporaryContentHandle();
 
@@ -255,6 +257,8 @@ PackageTypeAndVersionFormatComposite findPackageTypeWithVersionFormat(Subject su
      * @param fragment fragment bytes
      * @param off the offset
      * @param len
+     *
+     * @since 4.10
      */
     void uploadContentFragment(String temporaryContentHandle, byte[] fragment, int off, int len);
 
@@ -282,6 +286,8 @@ PackageTypeAndVersionFormatComposite findPackageTypeWithVersionFormat(Subject su
      * @return the package version
      *
      * @see ContentManagerRemote#createPackageVersionWithDisplayVersion(org.rhq.core.domain.auth.Subject, String, int, String, String, Integer, byte[])
+     *
+     * @since 4.10
      */
     PackageVersion createPackageVersionWithDisplayVersion(Subject subject, String packageName, int packageTypeId,
         String version, String displayVersion, Integer architectureId, String temporaryContentHandle);

modules/enterprise/server/jar/src/main/java/org/rhq/enterprise/server/content/RepoManagerRemote.java

@@ -212,6 +212,7 @@ public interface RepoManagerRemote {
      * @param repoId
      * @param packageVersionId
      * @return the bytes of the package version
+     * @since 4.5
      */
     byte[] getPackageVersionBytes(Subject subject, int repoId, int packageVersionId);
 }