OSID - osid.installation.PackageAdminSession Service Interface Definition

Interface	osid.installation.PackageAdminSession
Implements	`osid.OsidSession`
Description	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	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	canCreatePackages
Description	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.
Return	`boolean`		`false` if `Package` creation is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	canCreatePackageWithRecordTypes
Description	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	`osid.type.Type[]`	`packageRecordTypes`	array of package record types
Return	`boolean`		`true` if `Package` creation using the specified record `Types` is supported, `false` otherwise
Errors	NULL_ARGUMENT		`packageRecordTypes` is `null`
Compliance	`mandatory`		This method must be implemented.
Method	getPackageFormForCreate
Description	Gets the package form for creating new packages. A new form should be requested for each create transaction.
Parameters	`osid.type.Type[]`	`packageRecordTypes`	array of package record types
Return	`osid.installation.PackageForm`		the package form
Errors	NULL_ARGUMENT		`packageRecordTypes` 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	createPackage
Description	Creates a new `Package.`
Parameters	`osid.installation.PackageForm`	`packageForm`	the form for this `Package`
Return	`osid.installation.Package`		the new `Package`
Errors	ILLEGAL_STATE		`packageForm` already used in a create transaction
	INVALID_ARGUMENT		one or more of the form elements is invalid
	NULL_ARGUMENT		`packageForm` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		`packageForm` did not originate from `getPackageFormForCreate()`
Compliance	`mandatory`		This method must be implemented.
Method	canUpdatePackages
Description	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.
Return	`boolean`		`false` if package modification is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	canUpdatePackage
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`	`packageId`	the `Id` of the `Package`
Return	`boolean`		`false` if package modification is not authorized, `true` otherwise
Errors	NULL_ARGUMENT		`packageId` is `null`
Compliance	`mandatory`		This method must be implemented.
Provider Notes	If the `packageId` is not found, then it is acceptable to return false to indicate the lack of an update available.
Method	getPackageFormForUpdate
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`	`packageId`	the `Id` of the `Package`
Return	`osid.installation.PackageForm`		the package form
Errors	NOT_FOUND		`packageId` is not found
	NULL_ARGUMENT		`packageId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	updatePackage
Description	Updates an existing package.
Parameters	`osid.installation.PackageForm`	`packageForm`	the form containing the elements to be updated
Errors	INVALID_ARGUMENT		the form contains an invalid value
	NULL_ARGUMENT		`packageForm` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		`packageForm` did not originate from `getPackageFormForUpdate()`
Compliance	`mandatory`		This method must be implemented.
Method	canDeletePackages
Description	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.
Return	`boolean`		`false` if `Package` deletion is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	canDeletePackage
Description	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	`osid.id.Id`	`packageId`	the `Id` of the `Package`
Return	`boolean`		`false` if `Package` deletion is not authorized, `true` otherwise
Errors	NULL_ARGUMENT		`packageId` is `null`
Compliance	`mandatory`		This method must be implemented.
Provider Notes	If the `packageId` is not found, then it is acceptable to return false to indicate the lack of a delete available.
Method	deletePackage
Description	Deletes the `Package` identified by the given `Id.`
Parameters	`osid.id.Id`	`packageId`	the `Id` of the `Package` to delete
Errors	NOT_FOUND		a `Package` was not found identified by the given `Id`
	NULL_ARGUMENT		`packageId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	canManagePackageAliases
Description	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.
Return	`boolean`		`false` if `Package` aliasing is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	aliasPackage
Description	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	`osid.id.Id`	`packageId`	the `Id` of a `Package`
Parameters	`osid.id.Id`	`aliasId`	the alias `Id`
Errors	ALREADY_EXISTS		`aliasId` is already assigned
	NOT_FOUND		`packageId` not found
	NULL_ARGUMENT		`packageId` 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 `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.
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`	`packageId`	the `Id` of a `Package`
Parameters	`osid.type.Type[]`	`installationContentRecordTypes`	array of installation content record types
Return	`osid.installation.InstallationContentForm`		the installation content form
Errors	NOT_FOUND		`packageId` is not found
	NULL_ARGUMENT		`packageId` 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	canManagePackageVersions
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	addPackageVersion
Description	Sets the given package to be the next version of another package.
Parameters	`osid.id.Id`	`packageId`	the `Id` of a `Package`
Parameters	`osid.id.Id`	`nextPackageId`	the `Id` of the net package version
Errors	ALREADY_EXISTS		`nextPackageId` or `packageId` already part of a version chain
	NOT_FOUND		`packageId` or `nextPackageId` not found
	NULL_ARGUMENT		`packageId` or `nextPackageId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	removePackageVersion
Description	Removes a package from being the next version of another package.
Parameters	`osid.id.Id`	`packageId`	the `Id` of a `Package`
Parameters	`osid.id.Id`	`nextPackageId`	the `Id` of the net package version
Errors	NOT_FOUND		`nextPackageId` does not follow `packageId`
	NULL_ARGUMENT		`packageId` or `dependencyId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.