Interface CanonicalUnitAdminSession

All Superinterfaces:
AutoCloseable, Closeable, OsidSession, OsidSession
All Known Subinterfaces:
CanonicalUnitBatchAdminSession
public interface CanonicalUnitAdminSession extends OsidSession

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

Create and update operations differ in their usage. To create a CanonicalUnit , a CanonicalUnitForm is requested using getCanonicalUnitFormForCreate() specifying the desired record Types or none if no record Types are needed. The returned CanonicalUnitForm 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 CanonicalUnitForm is submiited to a create operation, it cannot be reused with another create operation unless the first operation was unsuccessful. Each CanonicalUnitForm corresponds to an attempted transaction.

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

The delete operations delete CanonicalUnits . To unmap a CanonicalUnit from the current Catalogue , the CanonicalUnitCatalogueAssignmentSession should be used. These delete operations attempt to remove the CanonicalUnit itself thus removing it from all known Catalogue catalogs.

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

  • Method Details

    • getCatalogueId

      Id getCatalogueId()
      Gets the Catalogue Id associated with this session.
      Returns:
      the Catalogue Id associated with this session
      Compliance:
      mandatory - This method must be implemented.

    • getCatalogue

      Catalogue getCatalogue() throws OperationFailedException, PermissionDeniedException
      Gets the Catalogue associated with this session.
      Returns:
      the catalogue
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • canCreateCanonicalUnits

      boolean canCreateCanonicalUnits()
      Tests if this user can create canonical units. A return of true does not guarantee successful authorization. A return of false indicates that it is known creating a CanonicalUnit will result in a PERMISSION_DENIED . This is intended as a hint to an application that may not wish to offer create operations to unauthorized users.
      Returns:
      false if CanonicalUnit creation is not authorized, true otherwise
      Compliance:
      mandatory - This method must be implemented.

    • canCreateCanonicalUnitWithRecordTypes

      boolean canCreateCanonicalUnitWithRecordTypes(Type[] canonicalUnitRecordTypes)
      Tests if this user can create a single CanonicalUnit using the desired record types. While OfferingManager.getCanonicalUnitRecordTypes() can be used to examine which records are supported, this method tests which record(s) are required for creating a specific CanonicalUnit . Providing an empty array tests if a CanonicalUnit can be created with no records.
      Parameters:
      canonicalUnitRecordTypes - array of canonical unit record types
      Returns:
      true if CanonicalUnit creation using the specified record Types is supported, false otherwise
      Throws:
      NullArgumentException - canonicalUnitRecordTypes is null
      Compliance:
      mandatory - This method must be implemented.

    • getCanonicalUnitFormForCreate

      CanonicalUnitForm getCanonicalUnitFormForCreate(Type[] canonicalUnitRecordTypes) throws OperationFailedException, PermissionDeniedException
      Gets the canonical unit form for creating new canonical units. A new form should be requested for each create transaction.
      Parameters:
      canonicalUnitRecordTypes - array of canonical unit record types to be included in the create operation or an empty list if none
      Returns:
      the canonical unit form
      Throws:
      NullArgumentException - canonicalUnitRecordTypes is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      UnsupportedException - cannot get form for requested record types
      Compliance:
      mandatory - This method must be implemented.

    • createCanonicalUnit

      CanonicalUnit createCanonicalUnit(CanonicalUnitForm canonicalUnitForm) throws OperationFailedException, PermissionDeniedException
      Creates a new CanonicalUnit .
      Parameters:
      canonicalUnitForm - the form for this CanonicalUnit
      Returns:
      the new CanonicalUnit
      Throws:
      IllegalStateException - canonicalUnitForm already used in a create transaction
      InvalidArgumentException - one or more of the form elements is invalid
      NullArgumentException - canonicalUnitForm is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      UnsupportedException - canonicalUnitForm did not originate from getCanonicalUnitFormForCreate()
      Compliance:
      mandatory - This method must be implemented.

    • canUpdateCanonicalUnits

      boolean canUpdateCanonicalUnits()
      Tests if this user can update canonical units. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating a CanonicalUnit will result in a PERMISSION_DENIED . This is intended as a hint to an application that may not wish to offer update operations to unauthorized users.
      Returns:
      false if CanonicalUnit modification is not authorized, true otherwise
      Compliance:
      mandatory - This method must be implemented.

    • getCanonicalUnitFormForUpdate

      CanonicalUnitForm getCanonicalUnitFormForUpdate(Id canonicalUnitId) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Gets the canonical unit form for updating an existing canonical unit. A new canonical unit form should be requested for each update transaction.
      Parameters:
      canonicalUnitId - the Id of the CanonicalUnit
      Returns:
      the canonical unit form
      Throws:
      NotFoundException - canonicalUnitId is not found
      NullArgumentException - canonicalUnitId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • updateCanonicalUnit

      void updateCanonicalUnit(CanonicalUnitForm canonicalUnitForm) throws OperationFailedException, PermissionDeniedException
      Updates an existing canonical unit.
      Parameters:
      canonicalUnitForm - the form containing the elements to be updated
      Throws:
      IllegalStateException - canonicalUnitForm already used in an update transaction
      InvalidArgumentException - the form contains an invalid value
      NullArgumentException - canonicalUnitForm is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      UnsupportedException - canonicalUnitForm did not originate from getCanonicalUnitFormForUpdate()
      Compliance:
      mandatory - This method must be implemented.

    • canDeleteCanonicalUnits

      boolean canDeleteCanonicalUnits()
      Tests if this user can delete canonical units. A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting an CanonicalUnit will result in a PERMISSION_DENIED . This is intended as a hint to an application that may not wish to offer delete operations to unauthorized users.
      Returns:
      false if CanonicalUnit deletion is not authorized, true otherwise
      Compliance:
      mandatory - This method must be implemented.

    • deleteCanonicalUnit

      void deleteCanonicalUnit(Id canonicalUnitId) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Deletes a CanonicalUnit .
      Parameters:
      canonicalUnitId - the Id of the CanonicalUnit to remove
      Throws:
      NotFoundException - canonicalUnitId not found
      NullArgumentException - canonicalUnitId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • canManageCanonicalUnitAliases

      boolean canManageCanonicalUnitAliases()
      Tests if this user can manage Id aliases for CanonicalUnits . 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 CanonicalUnit aliasing is not authorized, true otherwise
      Compliance:
      mandatory - This method must be implemented.

    • aliasCanonicalUnit

      void aliasCanonicalUnit(Id canonicalUnitId, Id aliasId) throws AlreadyExistsException, NotFoundException, OperationFailedException, PermissionDeniedException
      Adds an Id to a CanonicalUnit for the purpose of creating compatibility. The primary Id of the CanonicalUnit is determined by the provider. The new Id is an alias to the primary Id . If the alias is a pointer to another canonical unit, it is reassigned to the given canonical unit Id .
      Parameters:
      canonicalUnitId - the Id of a CanonicalUnit
      aliasId - the alias Id
      Throws:
      AlreadyExistsException - aliasId is in use as a primary Id
      NotFoundException - canonicalUnitId not found
      NullArgumentException - canonicalUnitId or aliasId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.