OSID Logo
OSID Specifications
control package
Version 3.0.0
Release Candidate Preview
Interfaceosid.control.SystemLookupSession
Implementsosid.OsidSession
Description

This session provides methods for retrieving System objects.

This session defines views that offer differing behaviors when retrieving multiple objects.

  • comparative view: elements may be silently omitted or re-ordered
  • plenary view: provides a complete set or is an error condition

Generally, the comparative view should be used for most applications as it permits operation even if there is data that cannot be accessed. For example, a browsing application may only need to examine the Systems it can access, without breaking execution. However, an assessment may only be useful if all Systems referenced by it are available, and a test-taking application may sacrifice some interoperability for the sake of precision.

MethodcanLookupSystems
Description

Tests if this user can perform System 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.

Returnboolean false if lookup methods are not authorized, true otherwise
CompliancemandatoryThis method must be implemented.
MethoduseComparativeSystemView
Description

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.

CompliancemandatoryThis method is must be implemented.
MethodusePlenarySystemView
Description

A complete view of the System 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.

CompliancemandatoryThis method is must be implemented.
MethodgetSystem
Description

Gets the System specified by its Id. In plenary mode, the exact Id is found or a NOT_FOUND results. Otherwise, the returned System may have a different Id than requested, such as the case where a duplicate Id was assigned to a System and retained for compatibility.

Parametersosid.id.IdsystemId Id of the System
Returnosid.control.Systemthe system
ErrorsNOT_FOUND systemId not found
NULL_ARGUMENT systemId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method is must be implemented.
MethodgetSystemsByIds
Description

Gets a SystemList corresponding to the given IdList. In plenary mode, the returned list contains all of the systems 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 Systems may be omitted from the list and may present the elements in any order including returning a unique set.

Parametersosid.id.IdListsystemIdsthe list of Ids to retrieve
Returnosid.control.SystemListthe returned System list
ErrorsNOT_FOUNDan Id was not found
NULL_ARGUMENT systemIds is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetSystemsByGenusType
Description

Gets a SystemList corresponding to the given system genus Type which does not include systems of types derived from the specified Type. In plenary mode, the returned list contains all known systems or an error results. Otherwise, the returned list may contain only those systems that are accessible through this session.

Parametersosid.type.TypesystemGenusTypea system genus type
Returnosid.control.SystemListthe returned System list
ErrorsNULL_ARGUMENT systemGenusType is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetSystemsByParentGenusType
Description

Gets a SystemList corresponding to the given system genus Type and include any additional systems with genus types derived from the specified Type. In plenary mode, the returned list contains all known systems or an error results. Otherwise, the returned list may contain only those systems that are accessible through this session.

Parametersosid.type.TypesystemGenusTypea system genus type
Returnosid.control.SystemListthe returned System list
ErrorsNULL_ARGUMENT systemGenusType is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetSystemsByRecordType
Description

Gets a SystemList containing the given system record Type. In plenary mode, the returned list contains all known systems or an error results. Otherwise, the returned list may contain only those systems that are accessible through this session.

Parametersosid.type.TypesystemRecordTypea system record type
Returnosid.control.SystemListthe returned System list
ErrorsNULL_ARGUMENT systemRecordType is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetSystemsByProvider
Description

Gets a SystemList for the given provider. In plenary mode, the returned list contains all known systems or an error results. Otherwise, the returned list may contain only those systems that are accessible through this session.

Parametersosid.id.IdresourceIda resource Id
Returnosid.control.SystemListthe returned System list
ErrorsNULL_ARGUMENT resourceId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetSystems
Description

Gets all Systems. In plenary mode, the returned list contains all known systems or an error results. Otherwise, the returned list may contain only those systems that are accessible through this session.

Returnosid.control.SystemLista list of Systems
ErrorsOPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.