Interface InstallationLookupSession

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

The session defines methods for retrieving Installations from installation Sites . An Installation represents a Package installed on a Site .

Two views are defined in this session:

  • comparative view: elements may be silently omitted or re-ordered
  • plenary view: provides a complete set or is an error condition
  • normalized version view: multiple versions of the same package are suppressed
  • denormalized version vew: all versions of an installation are returned

Installations may have an additional records indicated by their respective record types. The record may not be accessed through a cast of the Installation .

  • Method Details

    • getSiteId

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

    • getSite

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

    • canLookupInstallations

      boolean canLookupInstallations()
      Tests if this user can perform Installation lookups. 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 lookup operations to unauthorized users.
      Returns:
      false if lookup methods are not authorized, true otherwise
      Compliance:
      mandatory - This method must be implemented.

    • useComparativeInstallationView

      void useComparativeInstallationView()
      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.

    • usePlenaryInstallationView

      void usePlenaryInstallationView()
      A complete view of the Installation 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.

    • useNormalizedVersionView

      void useNormalizedVersionView()
      The returns from the lookup methods may omit multiple versions of the same installation.
      Compliance:
      mandatory - This method is must be implemented.

    • useDenormalizedVersionView

      void useDenormalizedVersionView()
      All versions of the same installation are returned.
      Compliance:
      mandatory - This method is must be implemented.

    • getInstallation

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

    • getInstallationsByIds

      InstallationList getInstallationsByIds(IdList installationIds) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Gets an InstallationList corresponding to the given IdList . In plenary mode, the returned list contains all of the installations 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 Installations may be omitted from the list and may present the elements in any order including returning a unique set.
      Parameters:
      installationIds - the list of Ids to retrieve
      Returns:
      the returned Installation list
      Throws:
      NotFoundException - an Id was not found
      NullArgumentException - installationIds is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getInstallationsByGenusType

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

    • getInstallationsByParentGenusType

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

    • getInstallationsByRecordType

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

    • getInstallationsByPackage

      InstallationList getInstallationsByPackage(Id packageId) throws OperationFailedException, PermissionDeniedException
      Gets an InstallationList corresponding to the given Package . In plenary mode, the returned list contains all of the installations for the specified package, 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 Installations may be omitted from the list and may present the elements in any order including returning a unique set.
      Parameters:
      packageId - Id of a Package
      Returns:
      the returned Installation list
      Throws:
      NullArgumentException - packageId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getInstallations

      InstallationList getInstallations() throws OperationFailedException, PermissionDeniedException
      Gets all Installations . In plenary mode, the returned list contains all known installations or an error results. Otherwise, the returned list may contain only those installations that are accessible through this session. In both cases, the order of the set is not specified.
      Returns:
      an InstallationList
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.