OSID - osid.installation.InstallationPackageAdminSession Service Interface Definition

Interface	osid.installation.InstallationPackageAdminSession
Implements	`osid.OsidSession`
Implemented By	`osid.installation.batch.InstallationPackageBatchAdminSession`
Used By	`osid.installation.InstallationManager`
Used By	`osid.installation.InstallationProxyManager`
Description	This session creates, updates, and deletes `InstallationPackages`. 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 `InstallationPackage`, a `InstallationPackagetForm` is requested using `getInstallationPackageFormForCreate()` specifying the desired record `Types` or none if no record `Types` are needed. The returned `InstallationPackageForm` 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 `InstallationPackageForm` is submiited to a create operation, it cannot be reused with another create operation unless the first operation was unsuccessful. Each `InstallationPackageForm` corresponds to an attempted transaction. For updates, `InstallationPackageForms` are requested to the `InstallationPackage` `Id` that is to be updated using `getInstallationPackageFormForUpdate()`. Similarly, the `InstallationPackageForm` has metadata about the data that can be updated and it can perform validation before submitting the update. The `InstallationPackageForm` can only be used once for a successful update and cannot be reused. The delete operations delete `InstallationPackages`. To unmap a `InstallationPackage` from the current `Depot`, the `InstallationPackageDepotAssignmentSession` should be used. These delete operations attempt to remove the `InstallationPackage` 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	getDepotId
Description	Gets the `Depot` `Id` associated with this session.
Return	`osid.id.Id`		the `Depot Id` associated with this session
Compliance	`mandatory`		This method must be implemented.
Method	getDepot
Description	Gets the `Depot` associated with this session.
Return	`osid.installation.Depot`		the `Depot` associated with this session
Errors	OPERATION_FAILED		unable to complete request
Errors	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	canCreateInstallationPackages
Description	Tests if this user can create `InstallationPackages`. A return of true does not guarantee successful authorization. A return of false indicates that it is known creating a `InstallationPackage` 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.
Return	`boolean`		`false` if `InstallationPackage` creation is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	canCreateInstallationPackageWithRecordTypes
Description	Tests if this user can create a single `InstallationPackage` using the desired record types. While `InstallationManager.getInstallationPackageRecordTypes()` can be used to examine which records are supported, this method tests which record(s) are required for creating a specific `InstallationPackage`. Providing an empty array tests if a `InstallationPackage` can be created with no records.
Parameters	`osid.type.Type[]`	`installationPackageRecordTypes`	array of package record types
Return	`boolean`		`true` if `InstallationPackage` creation using the specified record `Types` is supported, `false` otherwise
Errors	NULL_ARGUMENT		`installationPackageRecordTypes` is `null`
Compliance	`mandatory`		This method must be implemented.
Method	getInstallationPackageFormForCreate
Description	Gets the package form for creating new packages. A new form should be requested for each create transaction.
Parameters	`osid.type.Type[]`	`installationPackageRecordTypes`	array of package record types
Return	`osid.installation.InstallationPackageForm`		the package form
Errors	NULL_ARGUMENT		`installationPackageRecordTypes` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		unable to get form for requested record types
Compliance	`mandatory`		This method must be implemented.
Method	createInstallationPackage
Description	Creates a new `InstallationPackage`.
Parameters	`osid.installation.InstallationPackageForm`	`installationPackageForm`	the form for this `InstallationPackage`
Return	`osid.installation.InstallationPackage`		the new `InstallationPackage`
Errors	ILLEGAL_STATE		`installationPackageForm` already used in a create transaction
	INVALID_ARGUMENT		one or more of the form elements is invalid
	NULL_ARGUMENT		`installationPackageForm` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		`installationPackageForm` did not originate from `getInstallationPackageFormForCreate()`
Compliance	`mandatory`		This method must be implemented.
Method	canUpdateInstallationPackages
Description	Tests if this user can update `InstallationPackages`. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating a `InstallationPackage` 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.
Return	`boolean`		`false` if package modification is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	canUpdateInstallationPackage
Description	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	`osid.id.Id`	`installationPackageId`	the `Id` of the `InstallationPackage`
Return	`boolean`		`false` if package modification is not authorized, `true` otherwise
Errors	NULL_ARGUMENT		`installationPackageId` is `null`
Compliance	`mandatory`		This method must be implemented.
Provider Notes	If the `installationPackageId` is not found, then it is acceptable to return false to indicate the lack of an update available.
Method	getInstallationPackageFormForUpdate
Description	Gets the package form for updating an existing package. A new package form should be requested for each update transaction.
Parameters	`osid.id.Id`	`installationPackageId`	the `Id` of the `InstallationPackage`
Return	`osid.installation.InstallationPackageForm`		the package form
Errors	NOT_FOUND		`installationPackageId` is not found
	NULL_ARGUMENT		`installationPackageId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	updateInstallationPackage
Description	Updates an existing package.
Parameters	`osid.installation.InstallationPackageForm`	`installationPackageForm`	the form containing the elements to be updated
Errors	INVALID_ARGUMENT		the form contains an invalid value
	NULL_ARGUMENT		`installationPackageForm` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		`installationPackageForm` did not originate from `getInstallationPackageFormForUpdate()`
Compliance	`mandatory`		This method must be implemented.
Method	canDeleteInstallationPackages
Description	Tests if this user can delete `InstallationPackages`. A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting a `InstallationPackage` 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.
Return	`boolean`		`false` if `InstallationPackage` deletion is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	canDeleteInstallationPackage
Description	Tests if this user can delete a specified `InstallationPackage`. A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting the `InstallationPackage` 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	`osid.id.Id`	`installationPackageId`	the `Id` of the `InstallationPackage`
Return	`boolean`		`false` if `InstallationPackage` deletion is not authorized, `true` otherwise
Errors	NULL_ARGUMENT		`installationPackageId` is `null`
Compliance	`mandatory`		This method must be implemented.
Provider Notes	If the `installationPackageId` is not found, then it is acceptable to return false to indicate the lack of a delete available.
Method	deleteInstallationPackage
Description	Deletes the `InstallationPackage` identified by the given `Id`.
Parameters	`osid.id.Id`	`installationPackageId`	the `Id` of the `InstallationPackage` to delete
Errors	NOT_FOUND		a `InstallationPackage` was not found identified by the given `Id`
	NULL_ARGUMENT		`installationPackageId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	canManageInstallationPackageAliases
Description	Tests if this user can manage `Id` aliases for `InstallationPackages`. 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.
Return	`boolean`		`false` if `InstallationPackage` aliasing is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	aliasInstallationPackage
Description	Adds an `Id` to a `InstallationPackage` for the purpose of creating compatibility. The primary `Id` of the `InstallationPackage` 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	`osid.id.Id`	`installationPackageId`	the `Id` of a `InstallationPackage`
Parameters	`osid.id.Id`	`aliasId`	the alias `Id`
Errors	ALREADY_EXISTS		`aliasId` is already assigned
	NOT_FOUND		`installationPackageId` not found
	NULL_ARGUMENT		`installationPackageId` or `aliasId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	canCreateInstallationContent
Description	Tests if this user can create content for `InstallationPackages`. 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.
Return	`boolean`		`false` if `installation` content creation is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	canCreateInstallationContentWithRecordTypes
Description	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	`osid.type.Type[]`	`installationContentRecordTypes`	array of installation content record types
Return	`boolean`		`true` if `InstallationContent` creation using the specified `Types` is supported, `false` otherwise
Errors	NULL_ARGUMENT		`installationContentRecordTypes` is `null`
Compliance	`mandatory`		This method must be implemented.
Method	getInstallationContentFormForCreate
Description	Gets an installation content form for creating new installation contents.
Parameters	`osid.id.Id`	`installationPackageId`	the `Id` of a `InstallationPackage`
Parameters	`osid.type.Type[]`	`installationContentRecordTypes`	array of installation content record types
Return	`osid.installation.InstallationContentForm`		the installation content form
Errors	NOT_FOUND		`installationPackageId` is not found
	NULL_ARGUMENT		`installationPackageId` or `installationContentRecordTypes` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		unable to get form for requested record types
Compliance	`mandatory`		This method must be implemented.
Method	createInstallationContent
Description	Creates new `InstallationContent` for a given package.
Parameters	`osid.installation.InstallationContentForm`	`installationContentForm`	the form for this `InstallationContent`
Return	`osid.installation.InstallationContent`		the new `InstallationContent`
Errors	ILLEGAL_STATE		`installationContentForm` already used in a create transaction
	INVALID_ARGUMENT		one or more of the form elements is invalid
	NULL_ARGUMENT		`installationContentForm` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		`installationContentForm` did not originate from `getInstallationContentFormForCreate()`
Compliance	`mandatory`		This method must be implemented.
Method	canUpdateInstallationContents
Description	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.
Return	`boolean`		`false` if `InstallationContent` modification is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	getInstallationContentFormForUpdate
Description	Gets the installation content form for updating an existing installation content. A new installation content form should be requested for each update transaction.
Parameters	`osid.id.Id`	`installationContentId`	the `Id` of the `InstallationContent`
Return	`osid.installation.InstallationContentForm`		the v content form
Errors	NOT_FOUND		`installationContentId` is not found
	NULL_ARGUMENT		`installationContentId` is `null`
	OPERATION_FAILED		unable to complete request
Compliance	`mandatory`		This method must be implemented.
Method	updateInstallationContent
Description	Updates an existing installation content.
Parameters	`osid.installation.InstallationContentForm`	`installationContentForm`	the form containing the elements to be updated
Errors	ILLEGAL_STATE		`installationContentForm` already used in an update transaction
	INVALID_ARGUMENT		the form contains an invalid value
	NULL_ARGUMENT		`installationForm` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		`installationContentForm` did not originate from `getInstallationContentFormForUpdate()`
Compliance	`mandatory`		This method must be implemented.
Method	canDeleteInstallationContents
Description	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.
Return	`boolean`		`false` if `InstallationContent` deletion is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	deleteInstallationContent
Description	Deletes content from a package.
Parameters	`osid.id.Id`	`installationContentId`	the `Id` of the `InstallationContent`
Errors	NOT_FOUND		`installationContentId` is not found
	NULL_ARGUMENT		`installationContentId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	canManageInstallationPackageVersions
Description	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.
Return	`boolean`		`false` if package versioning is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	addInstallationPackageVersion
Description	Sets the given package to be the next version of another package.
Parameters	`osid.id.Id`	`installationPackageId`	the `Id` of a `InstallationPackage`
Parameters	`osid.id.Id`	`nextInstallationPackageId`	the `Id` of the net package version
Errors	ALREADY_EXISTS		`nextInstallationPackageId` or `installationPackageId` already part of a version chain
	NOT_FOUND		`installationPackageId` or `nextInstallationPackageId` not found
	NULL_ARGUMENT		`installationPackageId` or `nextInstallationPackageId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	removeInstallationPackageVersion
Description	Removes a package from being the next version of another package.
Parameters	`osid.id.Id`	`installationPackageId`	the `Id` of a `InstallationPackage`
Parameters	`osid.id.Id`	`nextInstallationPackageId`	the `Id` of the net package version
Errors	NOT_FOUND		`nextInstallationPackageId` does not follow `installationPackageId`
	NULL_ARGUMENT		`installationPackageId` or `dependencyId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.