org.osid.room

Interface RoomLookupSession

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable, 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

Methods

Modifier and Type	Method and 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(java.lang.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 org.osid.OsidSession

getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions

Methods inherited from interface org.osid.binding.java.OsidSession

close

Methods inherited from interface java.io.Closeable

close

Method Detail

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(java.lang.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.