Interface ConvocationAdminSession

All Superinterfaces:
AutoCloseable, Closeable, OsidSession, OsidSession
All Known Subinterfaces:
ConvocationBatchAdminSession
public interface ConvocationAdminSession extends OsidSession

This session creates, updates, and deletes Convocations . 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 Convocation , a ConvocationForm is requested using getConvocationFormForCreate() specifying the desired record Types or none if no record Types are needed. The returned ConvocationForm 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 ConvocationForm is submiited to a create operation, it cannot be reused with another create operation unless the first operation was unsuccessful. Each ConvocationForm corresponds to an attempted transaction.

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

The delete operations delete Convocations . To unmap a Convocation from the current Academy , the ConvocationAcademyAssignmentSession should be used. These delete operations attempt to remove the Convocation itself thus removing it from all known Academy catalogs.

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

  • Method Details

    • getAcademyId

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

    • getAcademy

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

    • canCreateConvocations

      boolean canCreateConvocations()
      Tests if this user can create convocations. A return of true does not guarantee successful authorization. A return of false indicates that it is known creating a Convocation 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 Convocation creation is not authorized, true otherwise
      Compliance:
      mandatory - This method must be implemented.

    • canCreateConvocationWithRecordTypes

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

    • getConvocationFormForCreate

      ConvocationForm getConvocationFormForCreate(Type[] convocationRecordTypes) throws OperationFailedException, PermissionDeniedException
      Gets the convocation form for creating new convocations. A new form should be requested for each create transaction.
      Parameters:
      convocationRecordTypes - array of convocation record types
      Returns:
      the convocation form
      Throws:
      NullArgumentException - convocationRecordTypes 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.

    • createConvocation

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

    • canUpdateConvocations

      boolean canUpdateConvocations()
      Tests if this user can update convocations. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating a Convocation 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 Convocation modification is not authorized, true otherwise
      Compliance:
      mandatory - This method must be implemented.

    • getConvocationFormForUpdate

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

    • updateConvocation

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

    • canDeleteConvocations

      boolean canDeleteConvocations()
      Tests if this user can delete convocations. A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting an Convocation 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 Convocation deletion is not authorized, true otherwise
      Compliance:
      mandatory - This method must be implemented.

    • deleteConvocation

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

    • canManageConvocationAliases

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

    • aliasConvocation

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