modules/enterprise/server/jar/src/main/java/org/rhq/enterprise/server/bundle/BundleManagerRemote.java
| 176 +++++++---
1 file changed, 140 insertions(+), 36 deletions(-)
New commits:
commit a9c76478054bb558012e2706a6d64435f9588d7e
Author: John Mazzitelli <mazz(a)redhat.com>
Date: Fri Jul 26 15:45:05 2013 -0400
add some javadoc and new apis for bundle groups
diff --git
a/modules/enterprise/server/jar/src/main/java/org/rhq/enterprise/server/bundle/BundleManagerRemote.java
b/modules/enterprise/server/jar/src/main/java/org/rhq/enterprise/server/bundle/BundleManagerRemote.java
index 0ffdc1a..8b4dae6 100644
---
a/modules/enterprise/server/jar/src/main/java/org/rhq/enterprise/server/bundle/BundleManagerRemote.java
+++
b/modules/enterprise/server/jar/src/main/java/org/rhq/enterprise/server/bundle/BundleManagerRemote.java
@@ -72,7 +72,12 @@ public interface BundleManagerRemote {
/**
* Adds a BundleFile to the BundleVersion and implicitly creates the backing
PackageVersion. If the PackageVersion
* already exists use {@link #addBundleFileViaPackageVersion(Subject, int, String,
int)}
- *
+ * </p>
+ * Required Permissions: Either:
+ * - Global.CREATE_BUNDLES and Global.VIEW_BUNDLES
+ * - Global.CREATE_BUNDLES and BundleGroup.VIEW_BUNDLES_IN_GROUP for bundle group BG
and the relevant bundle is assigned to BG
+ * - BundleGroup.CREATE_BUNDLES_IN_GROUP for bundle group BG and the relevant bundle
is assigned to BG
+ *
* @param subject user that must have proper permissions
* @param bundleVersionId id of the BundleVersion incorporating this BundleFile
* @param name name of the BundleFile (and the resulting Package)
@@ -89,7 +94,12 @@ public interface BundleManagerRemote {
* A convenience method taking a byte array as opposed to a stream for the file
bits.
* WARNING: obviously, this requires the entire bundle file to have been loaded fully
in memory.
* For very large files, this could cause OutOfMemoryErrors.
- *
+ * </p>
+ * Required Permissions: Either:
+ * - Global.CREATE_BUNDLES and Global.VIEW_BUNDLES
+ * - Global.CREATE_BUNDLES and BundleGroup.VIEW_BUNDLES_IN_GROUP for bundle group BG
and the relevant bundle is assigned to BG
+ * - BundleGroup.CREATE_BUNDLES_IN_GROUP for bundle group BG and the relevant bundle
is assigned to BG
+ *
* @see {@link #addBundleFile(Subject, int, String, String, Architecture,
InputStream)}
*/
BundleFile addBundleFileViaByteArray(Subject subject, int bundleVersionId, String
name, String version,
@@ -97,7 +107,12 @@ public interface BundleManagerRemote {
/**
* A convenience method taking a URL String whose content will be streamed to the
server and used for the file bits.
- *
+ * </p>
+ * Required Permissions: Either:
+ * - Global.CREATE_BUNDLES and Global.VIEW_BUNDLES
+ * - Global.CREATE_BUNDLES and BundleGroup.VIEW_BUNDLES_IN_GROUP for bundle group BG
and the relevant bundle is assigned to BG
+ * - BundleGroup.CREATE_BUNDLES_IN_GROUP for bundle group BG and the relevant bundle
is assigned to BG
+ *
* @see #addBundleFile(Subject, int, String, String, Architecture, InputStream)
*/
BundleFile addBundleFileViaURL(Subject subject, int bundleVersionId, String name,
String version,
@@ -106,6 +121,11 @@ public interface BundleManagerRemote {
/**
* A variant of {@link #addBundleFileViaURL(Subject, int, String, String,
Architecture, String)} supporting the
* HTTP basic authentication.
+ * </p>
+ * Required Permissions: Either:
+ * - Global.CREATE_BUNDLES and Global.VIEW_BUNDLES
+ * - Global.CREATE_BUNDLES and BundleGroup.VIEW_BUNDLES_IN_GROUP for bundle group BG
and the relevant bundle is assigned to BG
+ * - BundleGroup.CREATE_BUNDLES_IN_GROUP for bundle group BG and the relevant bundle
is assigned to BG
*
* @see #addBundleFileViaURL(Subject, int, String, String, Architecture, String)
*/
@@ -114,19 +134,40 @@ public interface BundleManagerRemote {
/**
* A convenience method taking an existing PackageVersion as opposed to a stream for
the file bits.
- *
+ * </p>
+ * Required Permissions: Either:
+ * - Global.CREATE_BUNDLES and Global.VIEW_BUNDLES
+ * - Global.CREATE_BUNDLES and BundleGroup.VIEW_BUNDLES_IN_GROUP for bundle group BG
and the relevant bundle is assigned to BG
+ * - BundleGroup.CREATE_BUNDLES_IN_GROUP for bundle group BG and the relevant bundle
is assigned to BG
+ *
* @see {@link #addBundleFile(Subject, int, String, String, Architecture,
InputStream)}
*/
BundleFile addBundleFileViaPackageVersion(Subject subject, int bundleVersionId,
String name, int packageVersionId)
throws Exception;
- //void assignBundlesToBundleGroup
-
+ /**
+ * Assign the specified bundles to the specified bundle group.
+ * </p>
+ * Requires VIEW permission for the relevant bundle and either:
+ * - Global.CREATE_BUNDLE
+ * - BundleGroup.CREATE_BUNDLES_IN_GROUP or BundleGroup.ASSIGN_BUNDLES_TO_GROUP for
the relevant bundle group
+ *
+ * @param subject
+ * @param bundleGroupId
+ * @param bundleIds
+ */
+ void assignBundlesToBundleGroup(Subject subject, int bundleGroupId, int[]
bundleIds);
+
/**
* Create a new bundle deployment. Note that bundle deployment names are generated by
this
* call. This provides useful, uniform naming for display. An optional, custom
description
* can be added. This call defines a deployment. The defined deployment can then
be
* scheduled in a separate call.
+ * </p>
+ * Required Permissions: Either:
+ * - Global.DEPLOY_BUNDLES and a view of the relevant bundle and a view of the
relevant resource group (may involve multiple roles)
+ * - Resource.DEPLOY_BUNDLES_TO_GROUP and a view of the relevant bundle and a view of
the relevant resource group (may involve multiple roles)
+ *
* @param subject user that must have proper permissions
* @param bundleVersionId the BundleVersion being deployed by this deployment
* @param bundleDestinationId the BundleDestination for the deployment
@@ -141,7 +182,11 @@ public interface BundleManagerRemote {
/**
* Creates a bundle destination that describes a target for the bundle deployments.
- *
+ * </p>
+ * Required Permissions: Either:
+ * - Global.DEPLOY_BUNDLES and a view of the relevant bundle and a view of the
relevant resource group (may involve multiple roles)
+ * - Resource.DEPLOY_BUNDLES_TO_GROUP and a view of the relevant bundle and a view of
the relevant resource group (may involve multiple roles)
+ *
* @param subject user must have MANAGE_INVENTORY permission
* @param bundleId the Bundle to be deployed to this Destination
* @param name a name for this destination. not null or empty
@@ -161,7 +206,8 @@ public interface BundleManagerRemote {
/**
* Create a new bundle group.
* <p/>
- * Requires Global.MANAGE_BUNDLE_GROUP permission.
+ * Require Permissions:
+ * - Global.MANAGE_BUNDLE_GROUPS
*
* @param subject user that must have proper permissions
* @param name the unique bundle group name
@@ -176,7 +222,12 @@ public interface BundleManagerRemote {
* version, version name and version description. If this is the initial version for
the named
* bundle the bundle will be implicitly created. The bundle type is discovered by
the bundle server
* plugin that can parse the recipe.
- *
+ * </p>
+ * Required Permissions: Either:
+ * - Global.CREATE_BUNDLES and Global.VIEW_BUNDLES
+ * - Global.CREATE_BUNDLES and BundleGroup.VIEW_BUNDLES_IN_GROUP for bundle group BG
and the relevant bundle is assigned to BG
+ * - BundleGroup.CREATE_BUNDLES_IN_GROUP for bundle group BG and the relevant bundle
is assigned to BG
+ *
* @param subject user that must have proper permissions
* @param recipe the recipe that defines the bundle version to be created
* @return the persisted BundleVersion with alot of the internal relationships filled
in to help the caller
@@ -190,7 +241,12 @@ public interface BundleManagerRemote {
* with the bundle version. The recipe specifies the bundle name, version, version
name and version description.
* If this is the initial version for the named bundle the bundle will be implicitly
created. The bundle type
* is discovered by inspecting the distribution file.
- *
+ * </p>
+ * Required Permissions: Either:
+ * - Global.CREATE_BUNDLES and Global.VIEW_BUNDLES
+ * - Global.CREATE_BUNDLES and BundleGroup.VIEW_BUNDLES_IN_GROUP for bundle group BG
and the relevant bundle is assigned to BG
+ * - BundleGroup.CREATE_BUNDLES_IN_GROUP for bundle group BG and the relevant bundle
is assigned to BG
+ *
* @param subject user that must have proper permissions
* @param distributionFile a local Bundle Distribution file. It must be read
accessible by the RHQ server process.
* @return the persisted BundleVersion with alot of the internal relationships filled
in to help the caller
@@ -204,6 +260,11 @@ public interface BundleManagerRemote {
* bytes of the file as opposed to the file itself.
* WARNING: obviously, this requires the entire distribution file to have been loaded
fully in memory.
* For very large distribution files, this could cause OutOfMemoryErrors.
+ * </p>
+ * Required Permissions: Either:
+ * - Global.CREATE_BUNDLES and Global.VIEW_BUNDLES
+ * - Global.CREATE_BUNDLES and BundleGroup.VIEW_BUNDLES_IN_GROUP for bundle group BG
and the relevant bundle is assigned to BG
+ * - BundleGroup.CREATE_BUNDLES_IN_GROUP for bundle group BG and the relevant bundle
is assigned to BG
*
* @param subject user that must have proper permissions
* @param fileBytes the file bits that make up the entire bundle distribution file
@@ -220,7 +281,12 @@ public interface BundleManagerRemote {
* is discovered by inspecting the distribution file.
* <br/></br>
* Note, if the file is local it is more efficient to use {@link
#createBundleVersionViaFile(Subject,File)}.
- *
+ * </p>
+ * Required Permissions: Either:
+ * - Global.CREATE_BUNDLES and Global.VIEW_BUNDLES
+ * - Global.CREATE_BUNDLES and BundleGroup.VIEW_BUNDLES_IN_GROUP for bundle group BG
and the relevant bundle is assigned to BG
+ * - BundleGroup.CREATE_BUNDLES_IN_GROUP for bundle group BG and the relevant bundle
is assigned to BG
+ *
* @param subject user that must have proper permissions
* @param distributionFileUrl a URL String to the Bundle Distribution file. It must
be live, resolvable and read accessible
* by the RHQ server process.
@@ -233,6 +299,11 @@ public interface BundleManagerRemote {
/**
* A version of the {@link
#createBundleVersionViaURL(org.rhq.core.domain.auth.Subject, String)} that accepts a
* username and password for basic authentication on the HTTP URLs.
+ * </p>
+ * Required Permissions: Either:
+ * - Global.CREATE_BUNDLES and Global.VIEW_BUNDLES
+ * - Global.CREATE_BUNDLES and BundleGroup.VIEW_BUNDLES_IN_GROUP for bundle group BG
and the relevant bundle is assigned to BG
+ * - BundleGroup.CREATE_BUNDLES_IN_GROUP for bundle group BG and the relevant bundle
is assigned to BG
*
* @see #createBundleVersionViaURL(org.rhq.core.domain.auth.Subject, String)
*/
@@ -243,7 +314,13 @@ public interface BundleManagerRemote {
* Remove everything associated with the Bundles with the exception of files laid
down by related deployments.
* Deployed files are left as is on the deployment platforms but the bundle mechanism
will no longer track
* the deployment of all bundles that have been deleted.
- *
+ * The bundles that are deleted will be removed from all bundle groups that it was a
member of.
+ * </p>
+ * Required Permissions: Either:
+ * - Global.DELETE_BUNDLES and Global.VIEW_BUNDLES
+ * - Global.DELETE_BUNDLES and BundleGroup.VIEW_BUNDLES_IN_GROUP for bundle group BG
and the relevant bundle is assigned to BG
+ * - BundleGroup.DELETE_BUNDLES_FROM_GROUP for bundle group BG and the relevant
bundle is assigned to BG
+ *
* @param subject user that must have proper permissions
* @param bundleIds IDs of all bundles to be deleted
* @throws Exception if any part of the removal fails.
@@ -254,7 +331,13 @@ public interface BundleManagerRemote {
* Remove everything associated with the Bundle with the exception of files laid down
by related deployments.
* Deployed files are left as is on the deployment platforms but the bundle mechanism
will no longer track
* the deployment.
- *
+ * The bundles that are deleted will be removed from all bundle groups that it was a
member of.
+ * </p>
+ * Required Permissions: Either:
+ * - Global.DELETE_BUNDLES and Global.VIEW_BUNDLES
+ * - Global.DELETE_BUNDLES and BundleGroup.VIEW_BUNDLES_IN_GROUP for bundle group BG
and the relevant bundle is assigned to BG
+ * - BundleGroup.DELETE_BUNDLES_FROM_GROUP for bundle group BG and the relevant
bundle is assigned to BG
+ *
* @param subject user that must have proper permissions
* @param bundleId the id of the bundle to remove
* @throws Exception if any part of the removal fails.
@@ -264,19 +347,26 @@ public interface BundleManagerRemote {
/**
* Delete a bundle group. Any currently assigned bundles will be removed but are not
deleted.
* <p/>
- * Requires Global.MANAGE_BUNDLE_GROUP permission.
+ * Required Permissions:
+ * - Global.MANAGE_BUNDLE_GROUPS
*
* @param subject user that must have proper permissions
- * @param id the bundle group id
+ * @param ids the bundle group id
* @throws Exception
*/
- void deleteBundleGroups(Subject subject, int... id) throws Exception;
+ void deleteBundleGroups(Subject subject, int[] ids) throws Exception;
/**
* Remove everything associated with the BundleVersion with the exception of files
laid down by related deployments.
* Deployed files are left as is on the deployment platforms but the bundle mechanism
will no longer track
* the deployment.
- *
+ * The deleted bundle version will no longer exist in any bundle group.
+ * </p>
+ * Required Permissions: Either:
+ * - Global.DELETE_BUNDLES and Global.VIEW_BUNDLES
+ * - Global.DELETE_BUNDLES and BundleGroup.VIEW_BUNDLES_IN_GROUP for bundle group BG
and the relevant bundle is assigned to BG
+ * - BundleGroup.DELETE_BUNDLES_FROM_GROUP for bundle group BG and the relevant
bundle is assigned to BG
+ *
* @param subject user that must have proper permissions
* @param bundleVersionId the id of the bundle version to remove
* @param deleteBundleIfEmpty if <code>true</code> and if this method
deletes the last bundle version for its
@@ -310,7 +400,13 @@ public interface BundleManagerRemote {
/**
* Determine the files required for a BundleVersion and return all of the filenames
or optionally, just those
* that lack BundleFiles for the BundleVersion. The recipe may be parsed as part of
this call.
- *
+ * This is needed as part of the bundle creation workflow, hence why creation
permissions are needed.
+ * </p>
+ * Required Permissions: Either:
+ * - Global.CREATE_BUNDLES and Global.VIEW_BUNDLES
+ * - Global.CREATE_BUNDLES and BundleGroup.VIEW_BUNDLES_IN_GROUP for bundle group BG
and the relevant bundle is assigned to BG
+ * - BundleGroup.CREATE_BUNDLES_IN_GROUP for bundle group BG and the relevant bundle
is assigned to BG
+ *
* @param subject user that must have proper permissions
* @param bundleVersionId the BundleVersion being queried
* @param withoutBundleFileOnly if true omit any filenames that already have a
corresponding BundleFile for
@@ -322,23 +418,11 @@ public interface BundleManagerRemote {
throws Exception;
/**
- * Similar to {@link #getBundleVersionFilenames(Subject, int, boolean)}, this will
determine the files required for a BundleVersion and return
- * all of the filenames, with the values of the map being true if they already exist
or false if they lack BundleFile representation
- * in the BundleVersion.
- *
- * @param subject user that must have proper permissions
- * @param bundleVersionId the BundleVersion being queried
- * @return map keyed on filenames whose value indicates if a bundle file exists for
the file or not
- * @throws Exception
- */
- /* comment back in when someone writes an adapter to support Map un/marshalling
- Map<String, Boolean> getAllBundleVersionFilenames(
- Subject subject,
- int bundleVersionId) throws Exception;
- */
-
- /**
* Purges the destination's live deployment content from the remote platforms.
+ * </p>
+ * Required Permissions: Either:
+ * - Global.DEPLOY_BUNDLES and a view of the relevant bundle and a view of the
relevant resource group (may involve multiple roles)
+ * - Resource.DEPLOY_BUNDLES_TO_GROUP and a view of the relevant bundle and a view of
the relevant resource group (may involve multiple roles)
*
* @param subject user that must have proper permissions
* @param bundleDestinationId the ID of the destination that is to be purged of
bundle content
@@ -351,7 +435,11 @@ public interface BundleManagerRemote {
* complete. The returned BundleDeployment can be used to track the history of the
individual deployments.
* <br/><br/>
* TODO: Add the scheduling capability, currently it's Immediate.
- * <br/>
+ * </p>
+ * Required Permissions: Either:
+ * - Global.DEPLOY_BUNDLES and a view of the relevant bundle and a view of the
relevant resource group (may involve multiple roles)
+ * - Resource.DEPLOY_BUNDLES_TO_GROUP and a view of the relevant bundle and a view of
the relevant resource group (may involve multiple roles)
+ *
* @param subject user that must have proper permissions
* @param bundleDeploymentId the BundleDeployment being used to guide the
deployments
* @param isCleanDeployment if true perform a wipe of the deploy directory prior to
the deployment. If false
@@ -371,7 +459,11 @@ public interface BundleManagerRemote {
* call. This provides useful, uniform naming for display. An optional, custom
description can be added.
* <br/><br/>
* TODO: Add the scheduling capability, currently it's Immediate.
- * <br/>
+ * </p>
+ * Required Permissions: Either:
+ * - Global.DEPLOY_BUNDLES and a view of the relevant bundle and a view of the
relevant resource group (may involve multiple roles)
+ * - Resource.DEPLOY_BUNDLES_TO_GROUP and a view of the relevant bundle and a view of
the relevant resource group (may involve multiple roles)
+ *
* @param subject user that must have proper permissions
* @param deploymentDescription an optional longer description describing this
deployment. If null defaults
* to the description of the previous deployment.
@@ -383,4 +475,16 @@ public interface BundleManagerRemote {
BundleDeployment scheduleRevertBundleDeployment(Subject subject, int
bundleDestinationId,
String deploymentDescription, boolean isCleanDeployment) throws Exception;
+ /**
+ * Unassign the specified bundles from the specified bundle group.
+ * </p>
+ * Requires VIEW permission for the relevant bundles and either:
+ * - Global.DELETE_BUNDLE
+ * - BundleGroup.DELETE_BUNDLES_FROM_GROUP or BundleGroup.UNASSIGN_BUNDLES_FROM_GROUP
for the relevant bundle group
+ *
+ * @param subject
+ * @param bundleGroupId
+ * @param bundleIds
+ */
+ void unassignBundlesFromBundleGroup(Subject subject, int bundleGroupId, int[]
bundleIds);
}