All Superinterfaces:: AutoCloseable, Closeable, OsidSession, OsidSession

public interface RoomLookupSession extends OsidSession

This session defines methods for retrieving rooms.

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 campus view: All room methods in this session operate, retrieve and pertain to rooms defined explicitly in the current campus. Using an isolated view is useful for managing rooms with the RoomAdminSession .
federated campus view: All room lookup methods in this session operate, retrieve and pertain to all rooms defined in this campus and any other campuses implicitly available in this campus through campus inheritence.
effective room view: All room lookup methods return effective rooms.
any effective room view: Rooms of any effective date are returned.

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

Method Summary

Modifier and Type

Method

Description

boolean

canLookupRooms()

Tests if this user can lookup rooms.

Campus

getCampus()

Gets the Campus associated with this session.

Id

getCampusId()

Gets the Campus Id associated with this session.

Room

getRoom(Id roomId)

Gets the Room specified by its Id .

RoomList

getRooms()

Gets all rooms.

RoomList

getRoomsByGenusType(Type roomGenusType)

Gets a RoomList corresponding to the given room genus Type which does not include rooms of genus types derived from the specified Type .

RoomList

getRoomsByGenusTypeForBuilding(Id buildingId, Type roomGenusType)

Gets a list of all rooms of the given genus type corresponding to a building Id .

RoomList

getRoomsByGenusTypeForBuildingOnDate(Id buildingId, Type roomGenusType, DateTime from, DateTime to)

Gets a list of all rooms of the given genus type corresponding to a building Id and effective during the entire given date range inclusive but not confined to the date range.

RoomList

getRoomsByGenusTypeForFloor(Id floorId, Type roomGenusType)

Gets a list of all rooms of the given genus type corresponding to a floor Id .

RoomList

getRoomsByGenusTypeForFloorOnDate(Id floorId, Type roomGenusType, DateTime from, DateTime to)

Gets a list of all rooms of the given genus type corresponding to a floor Id and effective during the entire given date range inclusive but not confined to the date range.

RoomList

getRoomsByGenusTypeOnDate(Type roomGenusType, DateTime from, DateTime to)

Gets a list of all rooms of a genus type effective during the entire given date range inclusive but not confined to the date range.

RoomList

getRoomsByIds(IdList roomIds)

Gets a RoomList corresponding to the given IdList .

RoomList

getRoomsByParentGenusType(Type roomGenusType)

Gets a RoomList corresponding to the given room genus Type and include any additional rooms with genus types derived from the specified Type .

RoomList

getRoomsByRecordType(Type roomRecordType)

Gets a RoomList containing the given room record Type .

RoomList

getRoomsByRoomNumber(String number)

Gets a list of all rooms of the given room number.

RoomList

getRoomsForBuilding(Id buildingId)

Gets a list of all rooms corresponding to a building Id .

RoomList

getRoomsForBuildingOnDate(Id buildingId, DateTime from, DateTime to)

Gets a list of all rooms corresponding to a building Id and effective during the entire given date range inclusive but not confined to the date range.

RoomList

getRoomsForFloor(Id floorId)

Gets a list of all rooms corresponding to a floor Id .

RoomList

getRoomsForFloorOnDate(Id floorId, DateTime from, DateTime to)

Gets a list of all rooms corresponding to a floor Id and effective during the entire given date range inclusive but not confined to the date range.

RoomList

getRoomsOnDate(DateTime from, DateTime to)

Gets a list of all rooms effective during the entire given date range inclusive but not confined to the date range.

void

useAnyEffectiveRoomView()

Rooms of any effective dates are returned by all methods in this session.

void

useComparativeRoomView()

The returns from the lookup methods may omit or translate elements based on this session, such as authorization, and not result in an error.

void

useEffectiveRoomView()

Only rooms whose effective dates are current are returned by methods in this session

void

useFederatedCampusView()

Federates the view for methods in this session.

void

useIsolatedCampusView()

Isolates the view for methods in this session.

void

usePlenaryRoomView()

A complete view of the Room returns is desired.

Methods inherited from interface Closeable
close

Methods inherited from interface OsidSession
close

Modifier and Type

Method

Description

void

close()

Close this session.

Methods inherited from interface OsidSession
getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions

Modifier and Type

Method

Description

Agent

getAuthenticatedAgent()

Gets the agent authenticated to this session.

Id

getAuthenticatedAgentId()

Gets the Id of the agent authenticated to this session.

BigDecimal

getClockRate()

Gets the rate of the service clock.

Date

getDate()

Gets the service date which may be the current date or the effective date in which this session exists.

Agent

getEffectiveAgent()

Gets the effective agent in use by this session.

Id

getEffectiveAgentId()

Gets the Id of the effective agent in use by this session.

Type

getFormatType()

Gets the DisplayText format Type preference in effect for this session.

Locale

getLocale()

Gets the locale indicating the localization preferences in effect for this session.

boolean

isAuthenticated()

Tests if an agent is authenticated to this session.

Transaction

startTransaction()

Starts a new transaction for this sesson.

boolean

supportsTransactions()

Tests for the availability of transactions.

Method Details
- getCampusId
  
  Id getCampusId()
  
  Gets the Campus Id associated with this session.
  
  Returns:
  
  the Campus Id associated with this session
  
  Compliance:
  mandatory - This method must be implemented.
- getCampus
  
  Campus getCampus() throws OperationFailedException, PermissionDeniedException
  
  Gets the Campus associated with this session.
  
  Returns:
  
  the campus
  
  Throws:
  
  OperationFailedException - unable to complete request
  
  PermissionDeniedException - authorization failure
  
  Compliance:
  mandatory - This method must be implemented.
- canLookupRooms
  
  boolean canLookupRooms()
  
  Tests if this user can lookup rooms. 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 room lookup methods are not authorized, true otherwise
  
  Compliance:
  mandatory - This method must be implemented.
- useComparativeRoomView
  
  void useComparativeRoomView()
  
  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.
- usePlenaryRoomView
  
  void usePlenaryRoomView()
  
  A complete view of the Room 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.
- useFederatedCampusView
  
  void useFederatedCampusView()
  
  Federates the view for methods in this session. A federated view will include rooms in campuses which are children of this campus in the campus hierarchy.
  
  Compliance:
  mandatory - This method is must be implemented.
- useIsolatedCampusView
  
  void useIsolatedCampusView()
  
  Isolates the view for methods in this session. An isolated view restricts retrievals to this campus only.
  
  Compliance:
  mandatory - This method is must be implemented.
- useEffectiveRoomView
  
  void useEffectiveRoomView()
  
  Only rooms whose effective dates are current are returned by methods in this session
  
  Compliance:
  mandatory - This method is must be implemented.
- useAnyEffectiveRoomView
  
  void useAnyEffectiveRoomView()
  
  Rooms of any effective dates are returned by all methods in this session.
  
  Compliance:
  mandatory - This method is must be implemented.
- getRoom
  
  Room getRoom(Id roomId) throws NotFoundException, OperationFailedException, PermissionDeniedException
  
  Gets the Room specified by its Id . In plenary mode, the exact Id is found or a NOT_FOUND results. Otherwise, the returned Room may have a different Id than requested, such as the case where a duplicate Id was assigned to a Room and retained for compatibility. In effective mode, rooms are returned that are currently effective. In any effective mode, effective rooms and those currently expired are returned.
  
  Parameters:
  
  roomId - the Id of the Room to retrieve
  
  Returns:
  
  the returned Room
  
  Throws:
  
  NotFoundException - no Room found with the given Id
  
  NullArgumentException - roomId is null
  
  OperationFailedException - unable to complete request
  
  PermissionDeniedException - authorization failure
  
  Compliance:
  mandatory - This method must be implemented.
- getRoomsByIds
  
  RoomList getRoomsByIds(IdList roomIds) throws NotFoundException, OperationFailedException, PermissionDeniedException
  
  Gets a RoomList corresponding to the given IdList . In plenary mode, the returned list contains all of the rooms 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 rooms may be omitted from the list and may present the elements in any order including returning a unique set. In effective mode, rooms are returned that are currently effective. In any effective mode, effective rooms and those currently expired are returned.
  
  Parameters:
  
  roomIds - the list of Ids to retrieve
  
  Returns:
  
  the returned Room list
  
  Throws:
  
  NotFoundException - an Id was not found
  
  NullArgumentException - roomIds is null
  
  OperationFailedException - unable to complete request
  
  PermissionDeniedException - authorization failure
  
  Compliance:
  mandatory - This method must be implemented.
- getRoomsByGenusType
  
  RoomList getRoomsByGenusType(Type roomGenusType) throws OperationFailedException, PermissionDeniedException
  
  Gets a RoomList corresponding to the given room genus Type which does not include rooms of genus types derived from the specified Type . In plenary mode, the returned list contains all known rooms or an error results. Otherwise, the returned list may contain only those rooms that are accessible through this session. In effective mode, rooms are returned that are currently effective. In any effective mode, effective rooms and those currently expired are returned.
  
  Parameters:
  
  roomGenusType - a room genus type
  
  Returns:
  
  the returned Room list
  
  Throws:
  
  NullArgumentException - roomGenusType is null
  
  OperationFailedException - unable to complete request
  
  PermissionDeniedException - authorization failure
  
  Compliance:
  mandatory - This method must be implemented.
- getRoomsByParentGenusType
  
  RoomList getRoomsByParentGenusType(Type roomGenusType) throws OperationFailedException, PermissionDeniedException
  
  Gets a RoomList corresponding to the given room genus Type and include any additional rooms with genus types derived from the specified Type . In plenary mode, the returned list contains all known rooms or an error results. Otherwise, the returned list may contain only those rooms that are accessible through this session. In effective mode, rooms are returned that are currently effective. In any effective mode, effective rooms and those currently expired are returned.
  
  Parameters:
  
  roomGenusType - a room genus type
  
  Returns:
  
  the returned Rooms list
  
  Throws:
  
  NullArgumentException - roomGenusType is null
  
  OperationFailedException - unable to complete request
  
  PermissionDeniedException - authorization failure
  
  Compliance:
  mandatory - This method must be implemented.
- getRoomsByRecordType
  
  RoomList getRoomsByRecordType(Type roomRecordType) throws OperationFailedException, PermissionDeniedException
  
  Gets a RoomList containing the given room record Type . In plenary mode, the returned list contains all known rooms or an error results. Otherwise, the returned list may contain only those rooms that are accessible through this session. In effective mode, rooms are returned that are currently effective. In any effective mode, effective rooms and those currently expired are returned.
  
  Parameters:
  
  roomRecordType - a room record type
  
  Returns:
  
  the returned Rooms list
  
  Throws:
  
  NullArgumentException - roomRecordType is null
  
  OperationFailedException - unable to complete request
  
  PermissionDeniedException - authorization failure
  
  Compliance:
  mandatory - This method must be implemented.
- getRoomsOnDate
  
  RoomList getRoomsOnDate(DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
  
  Gets a list of all rooms effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known rooms or an error results. Otherwise, the returned list may contain only those rooms that are accessible through this session. In effective mode, rooms are returned that are currently effective. In any effective mode, effective rooms and those currently expired are returned.
  
  Parameters:
  
  from - start of date range
  
  to - end of date range
  
  Returns:
  
  the returned RoomList
  
  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.
- getRoomsByGenusTypeOnDate
  
  RoomList getRoomsByGenusTypeOnDate(Type roomGenusType, DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
  
  Gets a list of all rooms of a genus type effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known rooms or an error results. Otherwise, the returned list may contain only those rooms that are accessible through this session. In effective mode, rooms are returned that are currently effective. In any effective mode, effective rooms and those currently expired are returned.
  
  Parameters:
  
  roomGenusType - a room genus Type
  
  from - start of date range
  
  to - end of date range
  
  Returns:
  
  the returned RoomList
  
  Throws:
  
  InvalidArgumentException - from is greater than to
  
  NullArgumentException - roomGenusType, from , or to is null
  
  OperationFailedException - unable to complete request
  
  PermissionDeniedException - authorization failure
  
  Compliance:
  mandatory - This method must be implemented.
- getRoomsForBuilding
  
  RoomList getRoomsForBuilding(Id buildingId) throws OperationFailedException, PermissionDeniedException
  
  Gets a list of all rooms corresponding to a building Id . In plenary mode, the returned list contains all known rooms or an error results. Otherwise, the returned list may contain only those rooms that are accessible through this session. In effective mode, rooms are returned that are currently effective. In any effective mode, effective rooms and those currently expired are returned.
  
  Parameters:
  
  buildingId - the Id of the building
  
  Returns:
  
  the returned RoomList
  
  Throws:
  
  NullArgumentException - buildingId is null
  
  OperationFailedException - unable to complete request
  
  PermissionDeniedException - authorization failure
  
  Compliance:
  mandatory - This method must be implemented.
- getRoomsForBuildingOnDate
  
  RoomList getRoomsForBuildingOnDate(Id buildingId, DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
  
  Gets a list of all rooms corresponding to a building Id and effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known rooms or an error results. Otherwise, the returned list may contain only those rooms that are accessible through this session. In effective mode, rooms are returned that are currently effective. In any effective mode, effective rooms and those currently expired are returned.
  
  Parameters:
  
  buildingId - a building Id
  
  from - from date
  
  to - to date
  
  Returns:
  
  the returned RoomList
  
  Throws:
  
  InvalidArgumentException - to is less than from
  
  NullArgumentException - buildingId, from , or to is null
  
  OperationFailedException - unable to complete request
  
  PermissionDeniedException - authorization failure
  
  Compliance:
  mandatory - This method must be implemented.
- getRoomsByGenusTypeForBuilding
  
  RoomList getRoomsByGenusTypeForBuilding(Id buildingId, Type roomGenusType) throws OperationFailedException, PermissionDeniedException
  
  Gets a list of all rooms of the given genus type corresponding to a building Id . In plenary mode, the returned list contains all known rooms or an error results. Otherwise, the returned list may contain only those rooms that are accessible through this session. In effective mode, rooms are returned that are currently effective. In any effective mode, effective rooms and those currently expired are returned.
  
  Parameters:
  
  buildingId - the Id of the building
  
  roomGenusType - a room genus type
  
  Returns:
  
  the returned RoomList
  
  Throws:
  
  NullArgumentException - buildingId or roomGenusType is null
  
  OperationFailedException - unable to complete request
  
  PermissionDeniedException - authorization failure
  
  Compliance:
  mandatory - This method must be implemented.
- getRoomsByGenusTypeForBuildingOnDate
  
  RoomList getRoomsByGenusTypeForBuildingOnDate(Id buildingId, Type roomGenusType, DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
  
  Gets a list of all rooms of the given genus type corresponding to a building Id and effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known rooms or an error results. Otherwise, the returned list may contain only those rooms that are accessible through this session. In effective mode, rooms are returned that are currently effective. In any effective mode, effective rooms and those currently expired are returned.
  
  Parameters:
  
  buildingId - a building Id
  
  roomGenusType - a room genus type
  
  from - from date
  
  to - to date
  
  Returns:
  
  the returned RoomList
  
  Throws:
  
  InvalidArgumentException - to is less than from
  
  NullArgumentException - buildingId, roomGenusType, from , or to is null
  
  OperationFailedException - unable to complete request
  
  PermissionDeniedException - authorization failure
  
  Compliance:
  mandatory - This method must be implemented.
- getRoomsForFloor
  
  RoomList getRoomsForFloor(Id floorId) throws OperationFailedException, PermissionDeniedException
  
  Gets a list of all rooms corresponding to a floor Id . In plenary mode, the returned list contains all known rooms or an error results. Otherwise, the returned list may contain only those rooms that are accessible through this session. In effective mode, rooms are returned that are currently effective. In any effective mode, effective rooms and those currently expired are returned.
  
  Parameters:
  
  floorId - the Id of the building
  
  Returns:
  
  the returned RoomList
  
  Throws:
  
  NullArgumentException - floorId is null
  
  OperationFailedException - unable to complete request
  
  PermissionDeniedException - authorization failure
  
  Compliance:
  mandatory - This method must be implemented.
- getRoomsForFloorOnDate
  
  RoomList getRoomsForFloorOnDate(Id floorId, DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
  
  Gets a list of all rooms corresponding to a floor Id and effective during the entire given date range inclusive but not confined to the date range. Rooms are returned with start effective dates that fall between the requested dates inclusive. In plenary mode, the returned list contains all known rooms or an error results. Otherwise, the returned list may contain only those rooms that are accessible through this session. In effective mode, rooms are returned that are currently effective. In any effective mode, effective rooms and those currently expired are returned.
  
  Parameters:
  
  floorId - a building Id
  
  from - from date
  
  to - to date
  
  Returns:
  
  the returned RoomList
  
  Throws:
  
  InvalidArgumentException - to is less than from
  
  NullArgumentException - floorId, from , or to is null
  
  OperationFailedException - unable to complete request
  
  PermissionDeniedException - authorization failure
  
  Compliance:
  mandatory - This method must be implemented.
- getRoomsByGenusTypeForFloor
  
  RoomList getRoomsByGenusTypeForFloor(Id floorId, Type roomGenusType) throws OperationFailedException, PermissionDeniedException
  
  Gets a list of all rooms of the given genus type corresponding to a floor Id . In plenary mode, the returned list contains all known rooms or an error results. Otherwise, the returned list may contain only those rooms that are accessible through this session. In effective mode, rooms are returned that are currently effective. In any effective mode, effective rooms and those currently expired are returned.
  
  Parameters:
  
  floorId - the Id of the floor
  
  roomGenusType - a room genus type
  
  Returns:
  
  the returned RoomList
  
  Throws:
  
  NullArgumentException - floorId or roomGenusType is null
  
  OperationFailedException - unable to complete request
  
  PermissionDeniedException - authorization failure
  
  Compliance:
  mandatory - This method must be implemented.
- getRoomsByGenusTypeForFloorOnDate
  
  RoomList getRoomsByGenusTypeForFloorOnDate(Id floorId, Type roomGenusType, DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
  
  Gets a list of all rooms of the given genus type corresponding to a floor Id and effective during the entire given date range inclusive but not confined to the date range. Rooms are returned with start effective dates that fall between the requested dates inclusive. In plenary mode, the returned list contains all known rooms or an error results. Otherwise, the returned list may contain only those rooms that are accessible through this session. In effective mode, rooms are returned that are currently effective. In any effective mode, effective rooms and those currently expired are returned.
  
  Parameters:
  
  floorId - a floor Id
  
  roomGenusType - a room genus type
  
  from - from date
  
  to - to date
  
  Returns:
  
  the returned RoomList
  
  Throws:
  
  InvalidArgumentException - to is less than from
  
  NullArgumentException - floorId, roomGenusType, from , or to is null
  
  OperationFailedException - unable to complete request
  
  PermissionDeniedException - authorization failure
  
  Compliance:
  mandatory - This method must be implemented.
- getRoomsByRoomNumber
  
  RoomList getRoomsByRoomNumber(String number) throws OperationFailedException, PermissionDeniedException
  
  Gets a list of all rooms of the given room number. In plenary mode, the returned list contains all known rooms or an error results. Otherwise, the returned list may contain only those rooms that are accessible through this session. In effective mode, rooms are returned that are currently effective. In any effective mode, effective rooms and those currently expired are returned.
  
  Parameters:
  
  number - a room number
  
  Returns:
  
  the returned RoomList
  
  Throws:
  
  NullArgumentException - number is null
  
  OperationFailedException - unable to complete request
  
  PermissionDeniedException - authorization failure
  
  Compliance:
  mandatory - This method must be implemented.
- getRooms
  
  RoomList getRooms() throws OperationFailedException, PermissionDeniedException
  
  Gets all rooms. In plenary mode, the returned list contains all known rooms or an error results. Otherwise, the returned list may contain only those rooms that are accessible through this session. In effective mode, rooms are returned that are currently effective. In any effective mode, effective rooms and those currently expired are returned.
  
  Returns:
  
  a list of rooms
  
  Throws:
  
  OperationFailedException - unable to complete request
  
  PermissionDeniedException - authorization failure
  
  Compliance:
  mandatory - This method must be implemented.

Interface RoomLookupSession

Method Summary

Methods inherited from interface Closeable

Methods inherited from interface OsidSession

Methods inherited from interface OsidSession

Method Details

getCampusId

getCampus

canLookupRooms

useComparativeRoomView

usePlenaryRoomView

useFederatedCampusView

useIsolatedCampusView

useEffectiveRoomView

useAnyEffectiveRoomView

getRoom

getRoomsByIds

getRoomsByGenusType

getRoomsByParentGenusType

getRoomsByRecordType

getRoomsOnDate

getRoomsByGenusTypeOnDate

getRoomsForBuilding

getRoomsForBuildingOnDate

getRoomsByGenusTypeForBuilding

getRoomsByGenusTypeForBuildingOnDate

getRoomsForFloor

getRoomsForFloorOnDate

getRoomsByGenusTypeForFloor

getRoomsByGenusTypeForFloorOnDate

getRoomsByRoomNumber

getRooms