org.rhq.enterprise.server.bundle
Interface BundleManagerRemote

All Known Subinterfaces:

WebservicesRemote

public interface BundleManagerRemote

Remote interface to the manager responsible for creating and managing bundles.

Method Summary

BundleFile	addBundleFile(Subject subject, int bundleVersionId, String name, String version, Architecture architecture, InputStream fileStream) Adds a BundleFile to the BundleVersion and implicitly creates the backing PackageVersion.
BundleFile	addBundleFileViaByteArray(Subject subject, int bundleVersionId, String name, String version, Architecture architecture, byte[] fileBytes) A convenience method taking a byte array as opposed to a stream for the file bits.
BundleFile	addBundleFileViaPackageVersion(Subject subject, int bundleVersionId, String name, int packageVersionId) A convenience method taking an existing PackageVersion as opposed to a stream for the file bits.
BundleFile	addBundleFileViaURL(Subject subject, int bundleVersionId, String name, String version, Architecture architecture, String bundleFileUrl) A convenience method taking a URL String whose content will be streamed to the server and used for the file bits.
BundleDeployment	createBundleDeployment(Subject subject, int bundleVersionId, int bundleDestinationId, String description, Configuration configuration) Create a new bundle deployment.
BundleDestination	createBundleDestination(Subject subject, int bundleId, String name, String description, String destBaseDirName, String deployDir, Integer groupId) Creates a bundle destination that describes a target for the bundle deployments.
BundleVersion	createBundleVersionViaByteArray(Subject subject, byte[] fileBytes) Creates a bundle version based on the actual bytes of a Bundle Distribution file.
BundleVersion	createBundleVersionViaFile(Subject subject, File distributionFile) Creates a bundle version based on a Bundle Distribution file.
BundleVersion	createBundleVersionViaRecipe(Subject subject, String recipe) Creates a bundle version based on single recipe string.
BundleVersion	createBundleVersionViaURL(Subject subject, String distributionFileUrl) Creates a bundle version based on a Bundle Distribution file.
void	deleteBundle(Subject subject, int bundleId) Remove everything associated with the Bundle with the exception of files laid down by related deployments.
void	deleteBundles(Subject subject, int[] bundleIds) Remove everything associated with the Bundles with the exception of files laid down by related deployments.
void	deleteBundleVersion(Subject subject, int bundleVersionId, boolean deleteBundleIfEmpty) Remove everything associated with the BundleVersion with the exception of files laid down by related deployments.
PageList<BundleDeployment>	findBundleDeploymentsByCriteria(Subject subject, BundleDeploymentCriteria criteria)
PageList<BundleDestination>	findBundleDestinationsByCriteria(Subject subject, BundleDestinationCriteria criteria)
PageList<BundleFile>	findBundleFilesByCriteria(Subject subject, BundleFileCriteria criteria)
PageList<BundleResourceDeployment>	findBundleResourceDeploymentsByCriteria(Subject subject, BundleResourceDeploymentCriteria criteria)
PageList<Bundle>	findBundlesByCriteria(Subject subject, BundleCriteria criteria)
PageList<BundleWithLatestVersionComposite>	findBundlesWithLatestVersionCompositesByCriteria(Subject subject, BundleCriteria criteria)
PageList<BundleVersion>	findBundleVersionsByCriteria(Subject subject, BundleVersionCriteria criteria)
List<BundleType>	getAllBundleTypes(Subject subject)
BundleType	getBundleType(Subject subject, String bundleTypeName)
Set<String>	getBundleVersionFilenames(Subject subject, int bundleVersionId, boolean withoutBundleFileOnly) Determine the files required for a BundleVersion and return all of the filenames or optionally, just those that lack BundleFiles for the BundleVersion.
ResourceTypeBundleConfiguration	getResourceTypeBundleConfiguration(Subject subject, int compatGroupId) Given the ID for a compatible group, this will return the bundle configuration metadata for that group's resource type.
void	purgeBundleDestination(Subject subject, int bundleDestinationId) Purges the destination's live deployment content from the remote platforms.
BundleDeployment	scheduleBundleDeployment(Subject subject, int bundleDeploymentId, boolean isCleanDeployment) Deploy the bundle to the destination, as described in the provided deployment.
BundleDeployment	scheduleRevertBundleDeployment(Subject subject, int bundleDestinationId, String deploymentDescription, boolean isCleanDeployment) For the specified destination, revert from the current live deployment to the deployment it had replaced.

Method Detail

getResourceTypeBundleConfiguration

ResourceTypeBundleConfiguration getResourceTypeBundleConfiguration(Subject subject,
                                                                   int compatGroupId)
                                                                   throws Exception

Given the ID for a compatible group, this will return the bundle configuration metadata for that group's resource type. User interfaces will need to use this method in order to find out if a) the group can be a target for a bundle deployment and/or b) what different destination base locations are supported by the group.

Parameters:

subject - the user making the request

compatGroupId - the ID for a compatible group whose type's bundle config is to be returned

Returns:

the bundle configuration for the group's resource type

Throws:

Exception

addBundleFile

BundleFile addBundleFile(Subject subject,
                         int bundleVersionId,
                         String name,
                         String version,
                         Architecture architecture,
                         InputStream fileStream)
                         throws Exception

Adds a BundleFile to the BundleVersion and implicitly creates the backing PackageVersion. If the PackageVersion already exists use addBundleFile(Subject, int, String, int, boolean)

Parameters:

subject - user that must have proper permissions

bundleVersionId - id of the BundleVersion incorporating this BundleFile

name - name of the BundleFile (and the resulting Package)

version - version of the backing package

architecture - architecture appropriate for the backing package. Defaults to noarch (i.e. any architecture).

fileStream - the file bits

Returns:

the new BundleFile

Throws:

Exception

addBundleFileViaByteArray

BundleFile addBundleFileViaByteArray(Subject subject,
                                     int bundleVersionId,
                                     String name,
                                     String version,
                                     Architecture architecture,
                                     byte[] fileBytes)
                                     throws Exception

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.

Throws:

Exception

See Also:

addBundleFile(Subject, int, String, String, Architecture, InputStream, boolean)}

addBundleFileViaURL

BundleFile addBundleFileViaURL(Subject subject,
                               int bundleVersionId,
                               String name,
                               String version,
                               Architecture architecture,
                               String bundleFileUrl)
                               throws Exception

A convenience method taking a URL String whose content will be streamed to the server and used for the file bits.

Throws:

Exception

See Also:

addBundleFile(Subject, int, String, String, Architecture, InputStream, boolean)}

addBundleFileViaPackageVersion

BundleFile addBundleFileViaPackageVersion(Subject subject,
                                          int bundleVersionId,
                                          String name,
                                          int packageVersionId)
                                          throws Exception

A convenience method taking an existing PackageVersion as opposed to a stream for the file bits.

Throws:

Exception

See Also:

addBundleFile(Subject, int, String, String, Architecture, InputStream, boolean)}

createBundleDeployment

BundleDeployment createBundleDeployment(Subject subject,
                                        int bundleVersionId,
                                        int bundleDestinationId,
                                        String description,
                                        Configuration configuration)
                                        throws Exception

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.

Parameters:

subject - user that must have proper permissions

bundleVersionId - the BundleVersion being deployed by this deployment

bundleDestinationId - the BundleDestination for the deployment

description - an optional longer description describing this deployment

configuration - a Configuration (pojo) to be associated with this deployment. Although it is not enforceable must be that of the associated BundleVersion.

Returns:

the persisted deployment

Throws:

Exception

createBundleDestination

BundleDestination createBundleDestination(Subject subject,
                                          int bundleId,
                                          String name,
                                          String description,
                                          String destBaseDirName,
                                          String deployDir,
                                          Integer groupId)
                                          throws Exception

Creates a bundle destination that describes a target for the bundle deployments.

Parameters:

subject - user must have MANAGE_INVENTORY permission

bundleId - the Bundle to be deployed to this Destination

name - a name for this destination. not null or empty

description - an optional longer description describing this destination

destBaseDirName - The name of the base directory location where the bundle will be deployed. deployDir is relative to the directory that this name refers to. This name isn't the directory itself, it refers to the named location as defined in the agent plugin's descriptor for the resource's type

deployDir - the root dir for deployments to this destination

groupId - the target platforms for deployments to this destination

Returns:

the persisted destination

Throws:

Exception

createBundleVersionViaRecipe

BundleVersion createBundleVersionViaRecipe(Subject subject,
                                           String recipe)
                                           throws Exception

Creates a bundle version based on single recipe string. 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 the bundle server plugin that can parse the recipe.

Parameters:

subject -

recipe - the recipe that defines the bundle version to be created

Returns:

the persisted BundleVersion with alot of the internal relationships filled in to help the caller understand all that this method did.

Throws:

Exception

createBundleVersionViaFile

BundleVersion createBundleVersionViaFile(Subject subject,
                                         File distributionFile)
                                         throws Exception

Creates a bundle version based on a Bundle Distribution file. Typically a zip file, the bundle distribution contains the recipe for a supported bundle type, along with 0, 1 or more bundle files that will be associated 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.

Parameters:

subject -

distributionFile - a local Bundle Distribution file. It must be read accessible by the RHQ server process.

Returns:

the persisted BundleVersion with alot of the internal relationships filled in to help the caller understand all that this method did. Bundle files specifically are returned.

Throws:

Exception

createBundleVersionViaByteArray

BundleVersion createBundleVersionViaByteArray(Subject subject,
                                              byte[] fileBytes)
                                              throws Exception

Creates a bundle version based on the actual bytes of a Bundle Distribution file. This is essentially the same as createBundleVersionViaFile(Subject, File) but the caller is providing the actual 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.

Parameters:

subject -

fileBytes - the file bits that make up the entire bundle distribution file

Returns:

the persisted BundleVersion with alot of the internal relationships filled in to help the caller understand all that this method did. Bundle files specifically are returned.

Throws:

Exception

createBundleVersionViaURL

BundleVersion createBundleVersionViaURL(Subject subject,
                                        String distributionFileUrl)
                                        throws Exception

Creates a bundle version based on a Bundle Distribution file. Typically a zip file, the bundle distribution contains the recipe for a supported bundle type, along with 0, 1 or more bundle files that will be associated 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.

Note, if the file is local it is more efficient to use createBundleVersionViaFile(Subject,File).

Parameters:

subject -

distributionFileUrl - a URL String to the Bundle Distribution file. It must be live, resolvable and read accessible by the RHQ server process.

Returns:

the persisted BundleVersion with alot of the internal relationships filled in to help the caller understand all that this method did. Bundle files specifically are returned.

Throws:

Exception

deleteBundles

void deleteBundles(Subject subject,
                   int[] bundleIds)
                   throws Exception

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.

Parameters:

subject -

bundleIds - IDs of all bundles to be deleted

Throws:

Exception - if any part of the removal fails.

deleteBundle

void deleteBundle(Subject subject,
                  int bundleId)
                  throws Exception

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.

Parameters:

subject -

bundleId -

Throws:

Exception - if any part of the removal fails.

deleteBundleVersion

void deleteBundleVersion(Subject subject,
                         int bundleVersionId,
                         boolean deleteBundleIfEmpty)
                         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.

Parameters:

subject -

bundleVersionId -

deleteBundleIfEmpty - if true and if this method deletes the last bundle version for its bundle, then that bundle entity itself will be completely purged

Throws:

Exception - if any part of the removal fails.

findBundlesByCriteria

PageList<Bundle> findBundlesByCriteria(Subject subject,
                                       BundleCriteria criteria)

findBundleDeploymentsByCriteria

PageList<BundleDeployment> findBundleDeploymentsByCriteria(Subject subject,
                                                           BundleDeploymentCriteria criteria)

findBundleDestinationsByCriteria

PageList<BundleDestination> findBundleDestinationsByCriteria(Subject subject,
                                                             BundleDestinationCriteria criteria)

findBundleResourceDeploymentsByCriteria

PageList<BundleResourceDeployment> findBundleResourceDeploymentsByCriteria(Subject subject,
                                                                           BundleResourceDeploymentCriteria criteria)

findBundleFilesByCriteria

PageList<BundleFile> findBundleFilesByCriteria(Subject subject,
                                               BundleFileCriteria criteria)

findBundleVersionsByCriteria

PageList<BundleVersion> findBundleVersionsByCriteria(Subject subject,
                                                     BundleVersionCriteria criteria)

findBundlesWithLatestVersionCompositesByCriteria

PageList<BundleWithLatestVersionComposite> findBundlesWithLatestVersionCompositesByCriteria(Subject subject,
                                                                                            BundleCriteria criteria)

getAllBundleTypes

List<BundleType> getAllBundleTypes(Subject subject)

getBundleType

BundleType getBundleType(Subject subject,
                         String bundleTypeName)

getBundleVersionFilenames

Set<String> getBundleVersionFilenames(Subject subject,
                                      int bundleVersionId,
                                      boolean withoutBundleFileOnly)
                                      throws Exception

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.

Parameters:

subject - user that must have proper permissions

bundleVersionId - the BundleVersion being queried

withoutBundleFileOnly - if true omit any filenames that already have a corresponding BundleFile for the BundleVersion.

Returns:

The List of filenames.

Throws:

Exception

purgeBundleDestination

void purgeBundleDestination(Subject subject,
                            int bundleDestinationId)
                            throws Exception

Purges the destination's live deployment content from the remote platforms.

Parameters:

subject - user that must have proper permissions

bundleDestinationId - the ID of the destination that is to be purged of bundle content

Throws:

Exception

scheduleBundleDeployment

BundleDeployment scheduleBundleDeployment(Subject subject,
                                          int bundleDeploymentId,
                                          boolean isCleanDeployment)
                                          throws Exception

Deploy the bundle to the destination, as described in the provided deployment. Deployment is asynchronous so return of this method does not indicate individual resource deployments are complete. The returned BundleDeployment can be used to track the history of the individual deployments.

TODO: Add the scheduling capability, currently it's Immediate.

Parameters:

subject - user that must have proper permissions

bundleDeploymentId - the BundleDeployment being used to guide the deployments

isCleanDeployment - if true perform a wipe of the deploy directory prior to the deployment. If false perform as an upgrade to the existing deployment, if any.

Returns:

the BundleDeployment record, updated with status and (resource) deployments.

Throws:

Exception

scheduleRevertBundleDeployment

BundleDeployment scheduleRevertBundleDeployment(Subject subject,
                                                int bundleDestinationId,
                                                String deploymentDescription,
                                                boolean isCleanDeployment)
                                                throws Exception

For the specified destination, revert from the current live deployment to the deployment it had replaced. A revert first rolls back to the previous deployment (bundle version and configuration) and then rolls forward by replacing changed files that had been backed up during the most recent (live) deployment. The returned BundleDeployment represents the new live deployment and can be used to track the history of the individual revert deployments. Note that bundle deployment names are generated by this call. This provides useful, uniform naming for display. An optional, custom description can be added.

TODO: Add the scheduling capability, currently it's Immediate.

Parameters:

subject - user that must have proper permissions

deploymentDescription - an optional longer description describing this deployment. If null defaults to the description of the previous deployment.

isCleanDeployment - if true perform a wipe of the deploy directory prior to the revert deployment. Backed up files will still be applied. If false perform as an upgrade to the existing deployment.

Returns:

the BundleDeployment record, updated with status and (resource) deployments.

Throws:

Exception