Interface PackageAdminSession

All Superinterfaces:
AutoCloseable, Closeable, OsidSession, 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 Details

    • 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 {@code 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 {@code 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.