Interface ConvocationLookupSession

All Superinterfaces:
AutoCloseable, Closeable, OsidSession, OsidSession
public interface ConvocationLookupSession extends OsidSession

This session defines methods for retrieving convocations.

This lookup session defines several views:

  • comparative view: elements may be silently omitted or re-ordered
  • plenary view: provides a complete result set or is an error condition
  • isolated academy view: All convocation methods in this session operate, retrieve and pertain to convocations defined explicitly in the current academy. Using an isolated view is useful for managing convocations with the ConvocationAdminSession .
  • federated academy view: All convocation lookup methods in this session operate, retrieve and pertain to all convocations defined in this academy and any other academies implicitly available in this academy through academy inheritence.
  • active convocation view: All convocation lookup methods return convocations where the convocation is active.
  • any status convocation view: Convocations of any status are returned.

The methods useFederatedAcademyView() and useIsolatedAcademyView() behave as a radio group and one should be selected before invoking any lookup methods.

  • 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.

    • canLookupConvocations

      boolean canLookupConvocations()
      Tests if this user can lookup convocations. A return of true does not guarantee successful authorization. A return of false indicates that it is known all methods in this session will result in a PERMISSION_DENIED . This is intended as a hint to an application that may opt not to offer these operations.
      Returns:
      false if convocation lookup methods are not authorized, true otherwise
      Compliance:
      mandatory - This method must be implemented.

    • useComparativeConvocationView

      void useComparativeConvocationView()
      The returns from the lookup methods may omit or translate elements based on this session, such as authorization, and not result in an error. This view is used when greater interoperability is desired at the expense of precision.
      Compliance:
      mandatory - This method is must be implemented.

    • usePlenaryConvocationView

      void usePlenaryConvocationView()
      A complete view of the Convocation returns is desired. Methods will return what is requested or result in an error. This view is used when greater precision is desired at the expense of interoperability.
      Compliance:
      mandatory - This method is must be implemented.

    • useFederatedAcademyView

      void useFederatedAcademyView()
      Federates the view for methods in this session. A federated view will include convocations in academies which are children of this academy in the academy hierarchy.
      Compliance:
      mandatory - This method is must be implemented.

    • useIsolatedAcademyView

      void useIsolatedAcademyView()
      Isolates the view for methods in this session. An isolated view restricts retrievals to this academy only.
      Compliance:
      mandatory - This method is must be implemented.

    • useActiveConvocationView

      void useActiveConvocationView()
      Only active convocations are returned by methods in this session.
      Compliance:
      mandatory - This method is must be implemented.

    • useAnyStatusConvocationView

      void useAnyStatusConvocationView()
      All convocations of any status are returned by all methods in this session.
      Compliance:
      mandatory - This method is must be implemented.

    • getConvocation

      Convocation getConvocation(Id convocationId) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Gets the Convocation specified by its Id . In plenary mode, the exact Id is found or a NOT_FOUND results. Otherwise, the returned Convocation may have a different Id than requested, such as the case where a duplicate Id was assigned to a Convocation and retained for compatibility.
      Parameters:
      convocationId - the Id of the Convocation to retrieve
      Returns:
      the returned Convocation
      Throws:
      NotFoundException - no Convocation found with the given Id
      NullArgumentException - convocationId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getConvocationsByIds

      ConvocationList getConvocationsByIds(IdList convocationIds) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Gets a ConvocationList corresponding to the given IdList .In plenary mode, the returned list contains all of the convocations specified in the Id list, in the order of the list, including duplicates, or an error results if an Id in the supplied list is not found or inaccessible. Otherwise, inaccessible convocations may be omitted from the list and may present the elements in any order including returning a unique set.
      Parameters:
      convocationIds - the list of Ids to retrieve
      Returns:
      the returned Convocation list
      Throws:
      NotFoundException - an Id was not found
      NullArgumentException - convocationIds is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getConvocationsByGenusType

      ConvocationList getConvocationsByGenusType(Type convocationGenusType) throws OperationFailedException, PermissionDeniedException
      Gets a ConvocationList corresponding to the given convocation genus Type which does not include convocations of genus types derived from the specified Type . In plenary mode, the returned list contains all known convocations or an error results. Otherwise, the returned list may contain only those convocations that are accessible through this session.
      Parameters:
      convocationGenusType - a convocation genus type
      Returns:
      the returned Convocation list
      Throws:
      NullArgumentException - convocationGenusType is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getConvocationsByParentGenusType

      ConvocationList getConvocationsByParentGenusType(Type convocationGenusType) throws OperationFailedException, PermissionDeniedException
      Gets a ConvocationList corresponding to the given convocation genus Type and include any additional convocations with genus types derived from the specified Type . In plenary mode, the returned list contains all known convocations or an error results. Otherwise, the returned list may contain only those convocations that are accessible through this session.
      Parameters:
      convocationGenusType - a convocation genus type
      Returns:
      the returned Convocation list
      Throws:
      NullArgumentException - convocationGenusType is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getConvocationsByRecordType

      ConvocationList getConvocationsByRecordType(Type convocationRecordType) throws OperationFailedException, PermissionDeniedException
      Gets a ConvocationList containing the given convocation record Type .In plenary mode, the returned list contains all known convocations or an error results. Otherwise, the returned list may contain only those convocations that are accessible through this session.
      Parameters:
      convocationRecordType - a convocation record type
      Returns:
      the returned Convocation list
      Throws:
      NullArgumentException - convocationRecordType is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getConvocationsByDate

      ConvocationList getConvocationsByDate(DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
      Gets a list of convocations with a date within the given date range inclusive. In plenary mode, the returned list contains all known convocations or an error results. Otherwise, the returned list may contain only those convocations that are accessible through this session.
      Parameters:
      from - the starting date
      to - the ending date
      Returns:
      the returned ConvocationList
      Throws:
      InvalidArgumentException - from is greater than to
      NullArgumentException - from or to is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getConvocationsByAward

      ConvocationList getConvocationsByAward(Id awardId) throws OperationFailedException, PermissionDeniedException
      Gets a list of all convocations corresponding to an award Id . In plenary mode, the returned list contains all known convocations or an error results. Otherwise, the returned list may contain only those convocations that are accessible through this session.
      Parameters:
      awardId - the Id of the award
      Returns:
      the returned ConvocationList
      Throws:
      NullArgumentException - awardId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getConvocationsByTimePeriod

      ConvocationList getConvocationsByTimePeriod(Id timePeriodId) throws OperationFailedException, PermissionDeniedException
      Gets a list of all convocations corresponding to a time period Id . In plenary mode, the returned list contains all known convocations or an error results. Otherwise, the returned list may contain only those convocations that are accessible through this session.
      Parameters:
      timePeriodId - the Id of the time period
      Returns:
      the returned ConvocationList
      Throws:
      NullArgumentException - timePeriod is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getConvocationsBySponsor

      ConvocationList getConvocationsBySponsor(Id resourceId) throws OperationFailedException, PermissionDeniedException
      Gets a list of all convocations for a given sponsor. In plenary mode, the returned list contains all known convocations or an error results. Otherwise, the returned list may contain only those convocations that are accessible through this session.
      Parameters:
      resourceId - the Id of the resource
      Returns:
      the returned ConvocationList
      Throws:
      NullArgumentException - resourceId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getConvocations

      ConvocationList getConvocations() throws OperationFailedException, PermissionDeniedException
      Gets all convocations. In plenary mode, the returned list contains all known convocations or an error results. Otherwise, the returned list may contain only those convocations that are accessible through this session.
      Returns:
      a list of convocations
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.