org.osid.installation

Interface PackageAdminSession

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable, OsidSession

All Known Subinterfaces:

PackageBatchAdminSession

public interface PackageAdminSession
extends OsidSession

This session creates, updates, and deletes Packages. The data for create and update is provided by the consumer via the form object. OsidForms are requested for each create or update and may not be reused.

Create and update operations differ in their usage. To create a Package, a PackagetForm is requested using getPackageFormForCreate() specifying the desired record Types or none if no record Types are needed. The returned PackageForm will indicate that it is to be used with a create operation and can be used to examine metdata or validate data prior to creation. Once the PackageForm is submiited to a create operation, it cannot be reused with another create operation unless the first operation was unsuccessful. Each PackageForm corresponds to an attempted transaction.

For updates, PackageForms are requested to the Package Id that is to be updated using getPackageFormForUpdate(). Similarly, the PackageForm has metadata about the data that can be updated and it can perform validation before submitting the update. The PackageForm can only be used once for a successful update and cannot be reused.

The delete operations delete Packages. To unmap a Package from the current Depot, the PackageDepotAssignmentSession should be used. These delete operations attempt to remove the Package itself thus removing it from all known Depot catalogs.

This session includes an Id aliasing mechanism to assign an external Id to an internally assigned Id.

Method Summary

Methods

Modifier and Type	Method and Description
void	addPackageVersion(Id packageId, Id nextPackageId) Sets the given package to be the next version of another package.
void	aliasPackage(Id packageId, Id aliasId) Adds an Id to a Package for the purpose of creating compatibility.
boolean	canCreateInstallationContent() Tests if this user can create content for Packages.
boolean	canCreateInstallationContentWithRecordTypes(Type[] installationContentRecordTypes) Tests if this user can create an InstallationContent using the desired record types.
boolean	canCreatePackages() Tests if this user can create Packages.
boolean	canCreatePackageWithRecordTypes(Type[] packageRecordTypes) Tests if this user can create a single Package using the desired record types.
boolean	canDeleteInstallationContents() Tests if this user can delete InstallationContents.
boolean	canDeletePackage(Id packageId) Tests if this user can delete a specified Package.
boolean	canDeletePackages() Tests if this user can delete Packages.
boolean	canManagePackageAliases() Tests if this user can manage Id aliases for Packages.
boolean	canManagePackageVersions() Tests if this user can manage package versions.
boolean	canUpdateInstallationContents() Tests if this user can update InstallationContent.
boolean	canUpdatePackage(Id packageId) Tests if this user can update a specified package.
boolean	canUpdatePackages() Tests if this user can update Packages.
InstallationContent	createInstallationContent(InstallationContentForm installationContentForm) Creates new InstallationContent for a given package.
Package	createPackage(PackageForm packageForm) Creates a new Package.
void	deleteInstallationContent(Id installationContentId) Deletes content from a package.
void	deletePackage(Id packageId) Deletes the Package identified by the given Id.
Depot	getDepot() Gets the Depot associated with this session.
Id	getDepotId() Gets the Depot Id associated with this session.
InstallationContentForm	getInstallationContentFormForCreate(Id packageId, Type[] installationContentRecordTypes) Gets an installation content form for creating new installation contents.
InstallationContentForm	getInstallationContentFormForUpdate(Id installationContentId) Gets the installation content form for updating an existing installation content.
PackageForm	getPackageFormForCreate(Type[] packageRecordTypes) Gets the package form for creating new packages.
PackageForm	getPackageFormForUpdate(Id packageId) Gets the package form for updating an existing package.
void	removePackageVersion(Id packageId, Id nextPackageId) Removes a package from being the next version of another package.
void	updateInstallationContent(InstallationContentForm installationContentForm) Updates an existing installation content.
void	updatePackage(PackageForm packageForm) Updates an existing package.

Methods inherited from interface org.osid.OsidSession

getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions

Methods inherited from interface org.osid.binding.java.OsidSession

close

Methods inherited from interface java.io.Closeable

close

Method Detail

getDepotId

Id getDepotId()

Gets the Depot Id associated with this session.

Returns:

the Depot Id associated with this session

Compliance:

mandatory - This method must be implemented.

getDepot

Depot getDepot()
               throws OperationFailedException,
                      PermissionDeniedException

Gets the Depot associated with this session.

Returns:

the Depot associated with this session

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canCreatePackages

boolean canCreatePackages()

Tests if this user can create Packages. A return of true does not guarantee successful authorization. A return of false indicates that it is known creating a Package will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer create operations to an unauthorized user.

Returns:

false if Package creation is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreatePackageWithRecordTypes

boolean canCreatePackageWithRecordTypes(Type[] packageRecordTypes)

Tests if this user can create a single Package using the desired record types. While InstallationManager.getPackageRecordTypes() can be used to examine which records are supported, this method tests which record(s) are required for creating a specific Package. Providing an empty array tests if a Package can be created with no records.

Parameters:

packageRecordTypes - array of package record types

Returns:

true if Package creation using the specified record Types is supported, false otherwise

Throws:

NullArgumentException - packageRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getPackageFormForCreate

PackageForm getPackageFormForCreate(Type[] packageRecordTypes)
                                    throws OperationFailedException,
                                           PermissionDeniedException

Gets the package form for creating new packages. A new form should be requested for each create transaction.

Parameters:

packageRecordTypes - array of package record types

Returns:

the package form

Throws:

NullArgumentException - packageRecordTypes is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - unable to get form for requested record types

Compliance:

mandatory - This method must be implemented.

createPackage

Package createPackage(PackageForm packageForm)
                      throws OperationFailedException,
                             PermissionDeniedException

Creates a new Package.

Parameters:

packageForm - the form for this Package

Returns:

the new Package

Throws:

IllegalStateException - packageForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - packageForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - packageForm did not originate from getPackageFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdatePackages

boolean canUpdatePackages()

Tests if this user can update Packages. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating a Package will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer update operations to an unauthorized user.

Returns:

false if package modification is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canUpdatePackage

boolean canUpdatePackage(Id packageId)

Tests if this user can update a specified package. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating the package will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer an update operation to an unauthorized user for this function.

Parameters:

packageId - the Id of the Package

Returns:

false if package modification is not authorized, true otherwise

Throws:

NullArgumentException - packageId is null

Compliance:

mandatory - This method must be implemented.

Notes:

If - the packageId is not found, then it is acceptable to return false to indicate the lack of an update available.

getPackageFormForUpdate

PackageForm getPackageFormForUpdate(Id packageId)
                                    throws NotFoundException,
                                           OperationFailedException,
                                           PermissionDeniedException

Gets the package form for updating an existing package. A new package form should be requested for each update transaction.

Parameters:

packageId - the Id of the Package

Returns:

the package form

Throws:

NotFoundException - packageId is not found

NullArgumentException - packageId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updatePackage

void updatePackage(PackageForm packageForm)
                   throws OperationFailedException,
                          PermissionDeniedException

Updates an existing package.

Parameters:

packageForm - the form containing the elements to be updated

Throws:

InvalidArgumentException - the form contains an invalid value

NullArgumentException - packageForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - packageForm did not originate from getPackageFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeletePackages

boolean canDeletePackages()

Tests if this user can delete Packages. A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting a Package will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer delete operations to an unauthorized user.

Returns:

false if Package deletion is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canDeletePackage

boolean canDeletePackage(Id packageId)

Tests if this user can delete a specified Package. A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting the Package will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer a delete operation to an unauthorized user for this function.

Parameters:

packageId - the Id of the Package

Returns:

false if Package deletion is not authorized, true otherwise

Throws:

NullArgumentException - packageId is null

Compliance:

mandatory - This method must be implemented.

Notes:

If - the packageId is not found, then it is acceptable to return false to indicate the lack of a delete available.

deletePackage

void deletePackage(Id packageId)
                   throws NotFoundException,
                          OperationFailedException,
                          PermissionDeniedException

Deletes the Package identified by the given Id.

Parameters:

packageId - the Id of the Package to delete

Throws:

NotFoundException - a Package was not found identified by the given Id

NullArgumentException - packageId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManagePackageAliases

boolean canManagePackageAliases()

Tests if this user can manage Id aliases for Packages. A return of true does not guarantee successful authorization. A return of false indicates that it is known changing an alias will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer alias operations to an unauthorized user.

Returns:

false if Package aliasing is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

aliasPackage

void aliasPackage(Id packageId,
                Id aliasId)
                  throws AlreadyExistsException,
                         NotFoundException,
                         OperationFailedException,
                         PermissionDeniedException

Adds an Id to a Package for the purpose of creating compatibility. The primary Id of the Package is determined by the provider. The new Id performs as an alias to the primary Id. If the alias is a pointer to another package it is reassigned to the given package Id.

Parameters:

packageId - the Id of a Package

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is already assigned

NotFoundException - packageId not found

NullArgumentException - packageId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canCreateInstallationContent

boolean canCreateInstallationContent()

Tests if this user can create content for Packages. A return of true does not guarantee successful authorization. A return of false indicates that it is known creating an InstallationContent will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer create operations to an unauthorized user.

Returns:

false if installation content creation is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreateInstallationContentWithRecordTypes

boolean canCreateInstallationContentWithRecordTypes(Type[] installationContentRecordTypes)

Tests if this user can create an InstallationContent using the desired record types. While InstallationManager.getInstallationContentRecordTypes() can be used to test which records are supported, this method tests which records are required for creating a specific InstallationContent. Providing an empty array tests if an InstallationContent can be created with no records.

Parameters:

installationContentRecordTypes - array of installation content record types

Returns:

true if InstallationContent creation using the specified Types is supported, false otherwise

Throws:

NullArgumentException - installationContentRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getInstallationContentFormForCreate

InstallationContentForm getInstallationContentFormForCreate(Id packageId,
                                                          Type[] installationContentRecordTypes)
                                                            throws NotFoundException,
                                                                   OperationFailedException,
                                                                   PermissionDeniedException

Gets an installation content form for creating new installation contents.

Parameters:

packageId - the Id of a Package

installationContentRecordTypes - array of installation content record types

Returns:

the installation content form

Throws:

NotFoundException - packageId is not found

NullArgumentException - packageId or installationContentRecordTypes is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - unable to get form for requested record types

Compliance:

mandatory - This method must be implemented.

createInstallationContent

InstallationContent createInstallationContent(InstallationContentForm installationContentForm)
                                              throws OperationFailedException,
                                                     PermissionDeniedException

Creates new InstallationContent for a given package.

Parameters:

installationContentForm - the form for this InstallationContent

Returns:

the new InstallationContent

Throws:

IllegalStateException - installationContentForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - installationContentForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - installationContentForm did not originate from getInstallationContentFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateInstallationContents

boolean canUpdateInstallationContents()

Tests if this user can update InstallationContent. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating an InstallationContent will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer update operations to an unauthorized user.

Returns:

false if InstallationContent modification is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

getInstallationContentFormForUpdate

InstallationContentForm getInstallationContentFormForUpdate(Id installationContentId)
                                                            throws NotFoundException,
                                                                   OperationFailedException

Gets the installation content form for updating an existing installation content. A new installation content form should be requested for each update transaction.

Parameters:

installationContentId - the Id of the InstallationContent

Returns:

the v content form

Throws:

NotFoundException - installationContentId is not found

NullArgumentException - installationContentId is null

OperationFailedException - unable to complete request

Compliance:

mandatory - This method must be implemented.

updateInstallationContent

void updateInstallationContent(InstallationContentForm installationContentForm)
                               throws OperationFailedException,
                                      PermissionDeniedException

Updates an existing installation content.

Parameters:

installationContentForm - the form containing the elements to be updated

Throws:

IllegalStateException - installationContentForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - installationForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - installationContentForm did not originate from getInstallationContentFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteInstallationContents

boolean canDeleteInstallationContents()

Tests if this user can delete InstallationContents. A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting an InstallationContent will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer delete operations to an unauthorized user.

Returns:

false if InstallationContent deletion is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

deleteInstallationContent

void deleteInstallationContent(Id installationContentId)
                               throws NotFoundException,
                                      OperationFailedException,
                                      PermissionDeniedException

Deletes content from a package.

Parameters:

installationContentId - the Id of the InstallationContent

Throws:

NotFoundException - installationContentId is not found

NullArgumentException - installationContentId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManagePackageVersions

boolean canManagePackageVersions()

Tests if this user can manage package versions. A return of true does not guarantee successful authorization. A return of false indicates that it is known version methods will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer delete operations to an unauthorized user.

Returns:

false if package versioning is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

addPackageVersion

void addPackageVersion(Id packageId,
                     Id nextPackageId)
                       throws AlreadyExistsException,
                              NotFoundException,
                              OperationFailedException,
                              PermissionDeniedException

Sets the given package to be the next version of another package.

Parameters:

packageId - the Id of a Package

nextPackageId - the Id of the net package version

Throws:

AlreadyExistsException - nextPackageId or packageId already part of a version chain

NotFoundException - packageId or nextPackageId not found

NullArgumentException - packageId or nextPackageId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

removePackageVersion

void removePackageVersion(Id packageId,
                        Id nextPackageId)
                          throws NotFoundException,
                                 OperationFailedException,
                                 PermissionDeniedException

Removes a package from being the next version of another package.

Parameters:

packageId - the Id of a Package

nextPackageId - the Id of the net package version

Throws:

NotFoundException - nextPackageId does not follow packageId

NullArgumentException - packageId or dependencyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.