OSID - osid.personnel.AppointmentLookupSession Service Interface Definition

Interface	osid.personnel.AppointmentLookupSession
Implements	`osid.OsidSession`
Used By	`osid.personnel.PersonnelManager`
Used By	`osid.personnel.PersonnelProxyManager`
Description	This session defines methods for retrieving appointments. 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 realm view: All appointment methods in this session operate, retrieve and pertain to appointments defined explicitly in the current realm. Using an isolated view is useful for managing appointments with the `AppointmentAdminSession`. federated realm view: All appointment lookup methods in this session operate, retrieve and pertain to all appointments defined in this realm and any other realms implicitly available in this realm through realm inheritence. effective appointment view: All appointment lookup methods return appointments where the current date falls in between the effective dates inclusive. any effective appointment view: Appointments of any effective date are returned from methods. The methods `useFederatedRealmView()` and `useIsolatedRealmView()` behave as a radio group and one should be selected before invoking any lookup methods.
Method	getRealmId
Description	Gets the `Realm` `Id` associated with this session.
Return	`osid.id.Id`		the `Realm Id` associated with this session
Compliance	`mandatory`		This method must be implemented.
Method	getRealm
Description	Gets the `Realm` associated with this session.
Return	`osid.personnel.Realm`		the realm
Errors	OPERATION_FAILED		unable to complete request
Errors	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	canLookupAppointments
Description	Tests if this user can examine this realm. 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.
Return	`boolean`		`false` if realm reading methods are not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	useComparativeAppointmentView
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.
Compliance	`mandatory`		This method is must be implemented.
Method	usePlenaryAppointmentView
Description	A complete view of the `Appointment` 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.
Method	useFederatedRealmView
Description	Federates the view for methods in this session. A federated view will include appointments in realms which are children of this realm in the realm hierarchy.
Compliance	`mandatory`		This method is must be implemented.
Method	useIsolatedRealmView
Description	Isolates the view for methods in this session. An isolated view restricts retrievals to this realm only.
Compliance	`mandatory`		This method is must be implemented.
Method	useEffectiveAppointmentView
Description	Only appointments whose effective dates are current are returned by methods in this session.
Compliance	`mandatory`		This method is must be implemented.
Method	useAnyEffectiveAppointmentView
Description	All appointments of any effective dates are returned by methods in this session.
Compliance	`mandatory`		This method is must be implemented.
Method	getAppointment
Description	Gets the `Appointment` specified by its `Id`. In plenary mode, the exact `Id` is found or a `NOT_FOUND` results. Otherwise, the returned `Appointment` may have a different `Id` than requested, such as the case where a duplicate `Id` was assigned to an `Appointment` and retained for compatibility. In effective mode, appointments are returned that are currently effective. In any effective mode, effective appointments and those currently expired are returned.
Parameters	`osid.id.Id`	`appointmentId`	the `Id` of the `Appointment` to retrieve
Return	`osid.personnel.Appointment`		the returned `Appointment`
Errors	NOT_FOUND		no `Appointment` found with the given `Id`
	NULL_ARGUMENT		`appointmentId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getAppointmentsByIds
Description	Gets an `AppointmentList` corresponding to the given `IdList`. In plenary mode, the returned list contains all of the appointments 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 appointments may be omitted from the list and may present the elements in any order including returning a unique set. In effective mode, appointments are returned that are currently effective. In any effective mode, effective appointments and those currently expired are returned.
Parameters	`osid.id.IdList`	`appointmentIds`	the list of `Ids` to retrieve
Return	`osid.personnel.AppointmentList`		the returned `Appointment list`
Errors	NOT_FOUND		an `Id was` not found
	NULL_ARGUMENT		`appointmentIds` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getAppointmentsByGenusType
Description	Gets an `AppointmentList` corresponding to the given appointment genus `Type` which does not include appointments of types derived from the specified `Type`. In plenary mode, the returned list contains all known appointments or an error results. Otherwise, the returned list may contain only those appointments that are accessible through this session. In effective mode, appointments are returned that are currently effective. In any effective mode, effective appointments and those currently expired are returned.
Parameters	`osid.type.Type`	`appointmentGenusType`	an appointments genus type
Return	`osid.personnel.AppointmentList`		the returned `Appointment list`
Errors	NULL_ARGUMENT		`appointmentGenusType` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getAppointmentsByParentGenusType
Description	Gets an `AppointmentList` corresponding to the given appointment genus `Type` and include any additional appointments with genus types derived from the specified `Type`. In plenary mode, the returned list contains all known appointments or an error results. Otherwise, the returned list may contain only those appointments that are accessible through this session. In effective mode, appointments are returned that are currently effective. In any effective mode, effective appointments and those currently expired are returned.
Parameters	`osid.type.Type`	`appointmentGenusType`	an appointment genus type
Return	`osid.personnel.AppointmentList`		the returned `Appointment list`
Errors	NULL_ARGUMENT		`appointmentGenusType` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getAppointmentsByRecordType
Description	Gets an `AppointmentList` containing the given appointment record `Type`. In plenary mode, the returned list contains all known appointments or an error results. Otherwise, the returned list may contain only those appointments that are accessible through this session. In effective mode, appointments are returned that are currently effective. In any effective mode, effective appointments and those currently expired are returned.
Parameters	`osid.type.Type`	`appointmentRecordType`	an appointment record type
Return	`osid.personnel.AppointmentList`		the returned `AppointmentList`
Errors	NULL_ARGUMENT		`appointmentRecordType` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getAppointmentsOnDate
Description	Gets an `AppointmentList` effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known appointments or an error results. Otherwise, the returned list may contain only those appointments that are accessible through this session. In effective mode, appointments are returned that are currently effective. In any effective mode, effective appointments and those currently expired are returned.
Parameters	`osid.calendaring.DateTime`	`from`	start of date range
Parameters	`osid.calendaring.DateTime`	`to`	end of date range
Return	`osid.personnel.AppointmentList`		the returned `AppointmentList`
Errors	INVALID_ARGUMENT		`from` is greater than `to`
	NULL_ARGUMENT		`from or to` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getAppointmentsForPerson
Description	Gets an `AppointmentList` for the given person `Id`. In plenary mode, the returned list contains all of the appointments corresponding to the given person, including duplicates, or an error results if an appointment is inaccessible. Otherwise, inaccessible `Appointments` may be omitted from the list. In effective mode, appointments are returned that are currently effective. In any effective mode, effective appointments and those currently expired are returned.
Parameters	`osid.id.Id`	`personId`	the `Id` of the person
Return	`osid.personnel.AppointmentList`		the returned `AppointmentList`
Errors	NULL_ARGUMENT		`personId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getAppointmentsForPersonOnDate
Description	Gets a list of appointments for a resource 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 appointments or an error results. Otherwise, the returned list may contain only those appointments that are accessible through this session. In effective mode, appointments are returned that are currently effective. In any effective mode, effective appointments and those currently expired are returned.
Parameters	`osid.id.Id`	`personId`	a person `Id`
	`osid.calendaring.DateTime`	`from`	start of date range
	`osid.calendaring.DateTime`	`to`	end of date range
Return	`osid.personnel.AppointmentList`		the returned `AppointmentList`
Errors	INVALID_ARGUMENT		`from` is greater than `to`
	NULL_ARGUMENT		`personId, from`, or `to` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getAppointmentsForPosition
Description	Gets an `AppointmentList` for the given position. `Id`. In plenary mode, the returned list contains all of the appointments corresponding to the given position, including duplicates, or an error results if an appointment is inaccessible. Otherwise, inaccessible `Appointments` may be omitted from the list. In effective mode, appointments are returned that are currently effective. In any effective mode, effective appointments and those currently expired are returned.
Parameters	`osid.id.Id`	`positionId`	a position `Id`
Return	`osid.personnel.AppointmentList`		the returned `AppointmentList`
Errors	NULL_ARGUMENT		`positionId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getAppointmentsForPositionOnDate
Description	Gets a list of appointments for a position 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 appointments or an error results. Otherwise, the returned list may contain only those appointments that are accessible through this session. In effective mode, appointments are returned that are currently effective. In any effective mode, effective appointments and those currently expired are returned.
Parameters	`osid.id.Id`	`positionId`	a position `Id`
	`osid.calendaring.DateTime`	`from`	start of date range
	`osid.calendaring.DateTime`	`to`	end of date range
Return	`osid.personnel.AppointmentList`		the returned `AppointmentList`
Errors	INVALID_ARGUMENT		`from` is greater than `to`
	NULL_ARGUMENT		`positionId, from`, or `to` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getAppointmentsForPersonAndPosition
Description	Gets an `AppointmentList` for the given person and position. In plenary mode, the returned list contains all of the appointments corresponding to the given resource and reference, including duplicates, or an error results if an appointment is inaccessible. Otherwise, inaccessible `Appointments` may be omitted from the list. In effective mode, appointments are returned that are currently effective. In any effective mode, effective appointments and those currently expired are returned.
Parameters	`osid.id.Id`	`personId`	a person `Id`
Parameters	`osid.id.Id`	`positionId`	a position `Id`
Return	`osid.personnel.AppointmentList`		the returned `AppointmentList`
Errors	NULL_ARGUMENT		`personId` or `positionId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getAppointmentsForPersonAndPositionOnDate
Description	Gets an `AppointmentList` corresponding to the given person and position and effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all of the appointments corresponding to the given peer, including duplicates, or an error results if an appointment is inaccessible. Otherwise, inaccessible `Appointments` may be omitted from the list. In effective mode, appointments are returned that are currently effective. In any effective mode, effective appointments and those currently expired are returned.
Parameters	`osid.id.Id`	`personId`	a person `Id`
	`osid.id.Id`	`positionId`	a position `Id`
	`osid.calendaring.DateTime`	`from`	start of date range
	`osid.calendaring.DateTime`	`to`	end of date range
Return	`osid.personnel.AppointmentList`		the returned `AppointmentList`
Errors	INVALID_ARGUMENT		`from` is greater than `to`
	NULL_ARGUMENT		`referenceId, resourceId, from`, or `to` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getAppointments
Description	Gets all appointments. In plenary mode, the returned list contains all known appointments or an error results. Otherwise, the returned list may contain only those appointments that are accessible through this session. In effective mode, appointments are returned that are currently effective. In any effective mode, effective appointments and those currently expired are returned.
Return	`osid.personnel.AppointmentList`		a list of appointments
Errors	OPERATION_FAILED		unable to complete request
Errors	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.