OSID - osid.commenting.CommentLookupSession Service Interface Definition

Interface	osid.commenting.CommentLookupSession
Implements	`osid.OsidSession`
Description	This session defines methods for retrieving comments. 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 book view: All comment methods in this session operate, retrieve and pertain to comments defined explicitly in the current book. Using an isolated view is useful for managing comments with the `CommentAdminSession.` federated book view: All comment lookup methods in this session operate, retrieve and pertain to all comments defined in this book and any other books implicitly available in this book through book inheritence. effective comment view: All comment lookup methods return comments where the current dates falls in between the effective dates inclusive. any effective comment view: Comments of any effective date are returned. The methods `useFederatedBookView()` and `useIsolatedBookView()` behave as a radio group and one should be selected before invoking any lookup methods.
Method	getBookId
Description	Gets the `Book` `Id` associated with this session.
Return	`osid.id.Id`		the `Book Id` associated with this session
Compliance	`mandatory`		This method must be implemented.
Method	getBook
Description	Gets the `Book` associated with this session.
Return	`osid.commenting.Book`		the book
Errors	OPERATION_FAILED		unable to complete request
Errors	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	canLookupComments
Description	Tests if this user can examine this book. 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 book reading methods are not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	useComparativeCommentView
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	usePlenaryCommentView
Description	A complete view of the `Comment` 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	useFederatedBookView
Description	Federates the view for methods in this session. A federated view will include comments in books which are children of this book in the book hierarchy.
Compliance	`mandatory`		This method is must be implemented.
Method	useIsolatedBookView
Description	Isolates the view for methods in this session. An isolated view restricts retrievals to this book only.
Compliance	`mandatory`		This method is must be implemented.
Method	useEffectiveCommentView
Description	Only comments whose effective dates are current are returned by methods in this session.
Compliance	`mandatory`		This method is must be implemented.
Method	useAnyEffectiveCommentView
Description	All comments of any effective dates are returned by all methods in this session.
Compliance	`mandatory`		This method is must be implemented.
Method	getComment
Description	Gets the `Comment` specified by its `Id.` In plenary mode, the exact `Id` is found or a `NOT_FOUND` results. Otherwise, the returned `Comment` may have a different `Id` than requested, such as the case where a duplicate `Id` was assigned to a `Comment` and retained for compatibility. In effective mode, comments are returned that are currently effective. In any effective mode, effective comments and those currently expired are returned.
Parameters	`osid.id.Id`	`commentId`	the `Id` of the `Comment` to retrieve
Return	`osid.commenting.Comment`		the returned `Comment`
Errors	NOT_FOUND		no `Comment` found with the given `Id`
	NULL_ARGUMENT		`commentId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getCommentsByIds
Description	Gets a `CommentList` corresponding to the given `IdList.` In plenary mode, the returned list contains all of the comments 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 comments may be omitted from the list and may present the elements in any order including returning a unique set. In effective mode, comments are returned that are currently effective. In any effective mode, effective comments and those currently expired are returned.
Parameters	`osid.id.IdList`	`commentIds`	the list of `Ids` to retrieve
Return	`osid.commenting.CommentList`		the returned `Comment list`
Errors	NOT_FOUND		an `Id was` not found
	NULL_ARGUMENT		`commentIds` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getCommentsByGenusType
Description	Gets a `CommentList` corresponding to the given comment genus `Type` which does not include comments of genus types derived from the specified `Type.` In plenary mode, the returned list contains all known comments or an error results. Otherwise, the returned list may contain only those comments that are accessible through this session. In effective mode, comments are returned that are currently effective. In any effective mode, effective comments and those currently expired are returned.
Parameters	`osid.type.Type`	`commentGenusType`	a comment genus type
Return	`osid.commenting.CommentList`		the returned `Comment` list
Errors	NULL_ARGUMENT		`commentGenusType` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getCommentsByParentGenusType
Description	Gets a `CommentList` corresponding to the given comment genus `Type` and include any additional comments with genus types derived from the specified `Type.` In plenary mode, the returned list contains all known comments or an error results. Otherwise, the returned list may contain only those comments that are accessible through this session. In effective mode, comments are returned that are currently effective. In any effective mode, effective comments and those currently expired are returned.
Parameters	`osid.type.Type`	`commentGenusType`	a comment genus type
Return	`osid.commenting.CommentList`		the returned `Comment` list
Errors	NULL_ARGUMENT		`commentGenusType` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getCommentsByRecordType
Description	Gets a `CommentList` containing the given comment record `Type.` In plenary mode, the returned list contains all known comments or an error results. Otherwise, the returned list may contain only those comments that are accessible through this session. In effective mode, comments are returned that are currently effective. In any effective mode, effective comments and those currently expired are returned.
Parameters	`osid.type.Type`	`commentRecordType`	a comment record type
Return	`osid.commenting.CommentList`		the returned `Comment` list
Errors	NULL_ARGUMENT		`commentRecordType` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getCommentsOnDate
Description	Gets a `CommentList` effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known comments or an error results. Otherwise, the returned list may contain only those comments that are accessible through this session. In effective mode, comments are returned that are currently effective. In any effective mode, effective comments and those currently expired are returned.
Parameters	`osid.calendaring.DateTime`	`from`	starting date
Parameters	`osid.calendaring.DateTime`	`to`	ending date
Return	`osid.commenting.CommentList`		the returned `Comment` list
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	getCommentsByGenusTypeOnDate
Description	Gets a `CommentList` of a given genus type 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 comments or an error results. Otherwise, the returned list may contain only those comments that are accessible through this session. In effective mode, comments are returned that are currently effective. In any effective mode, effective comments and those currently expired are returned.
Parameters	`osid.type.Type`	`commentGenusType`	a comment genus type
	`osid.calendaring.DateTime`	`from`	starting date
	`osid.calendaring.DateTime`	`to`	ending date
Return	`osid.commenting.CommentList`		the returned `Comment` list
Errors	INVALID_ARGUMENT		`from` is greater than `to`
	NULL_ARGUMENT		`commentGenusType, from,` or `to` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getCommentsForCommentor
Description	Gets a list of comments corresponding to a resource `Id.` In plenary mode, the returned list contains all known comments or an error results. Otherwise, the returned list may contain only those comments that are accessible through this session. In effective mode, comments are returned that are currently effective. In any effective mode, effective comments and those currently expired are returned.
Parameters	`osid.id.Id`	`resourceId`	the `Id` of the resource
Return	`osid.commenting.CommentList`		the returned `CommentList`
Errors	NULL_ARGUMENT		`resourceId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getCommentsForCommentorOnDate
Description	Gets a list of all comments corresponding to a resource `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 comments or an error results. Otherwise, the returned list may contain only those comments that are accessible through this session. In effective mode, comments are returned that are currently effective. In any effective mode, effective comments and those currently expired are returned.
Parameters	`osid.id.Id`	`resourceId`	the `Id` of the resource
	`osid.calendaring.DateTime`	`from`	from date
	`osid.calendaring.DateTime`	`to`	to date
Return	`osid.commenting.CommentList`		the returned `CommentList`
Errors	INVALID_ARGUMENT		`to` is less than `from`
	NULL_ARGUMENT		`resourceId, from,` or `to` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getCommentsByGenusTypeForCommentor
Description	Gets a list of comments of the given genus type corresponding to a resource `Id.` In plenary mode, the returned list contains all known comments or an error results. Otherwise, the returned list may contain only those comments that are accessible through this session. In effective mode, comments are returned that are currently effective. In any effective mode, effective comments and those currently expired are returned.
Parameters	`osid.id.Id`	`resourceId`	the `Id` of the resource
Parameters	`osid.type.Type`	`commentGenusType`	the comment genus type
Return	`osid.commenting.CommentList`		the returned `CommentList`
Errors	NULL_ARGUMENT		`resourceId` or `commentGenusType` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getCommentsByGenusTypeForCommentorOnDate
Description	Gets a list of all comments of the given genus type corresponding to a resource `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 comments or an error results. Otherwise, the returned list may contain only those comments that are accessible through this session. In effective mode, comments are returned that are currently effective. In any effective mode, effective comments and those currently expired are returned.
Parameters	`osid.id.Id`	`resourceId`	the `Id` of the resource
	`osid.type.Type`	`commentGenusType`	the comment genus type
	`osid.calendaring.DateTime`	`from`	from date
	`osid.calendaring.DateTime`	`to`	to date
Return	`osid.commenting.CommentList`		the returned `CommentList`
Errors	INVALID_ARGUMENT		`to` is less than `from`
	NULL_ARGUMENT		`resourceId, commentGenusType, from,` or `to` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getCommentsForReference
Description	Gets a list of comments corresponding to a reference `Id.` In plenary mode, the returned list contains all known comments or an error results. Otherwise, the returned list may contain only those comments that are accessible through this session. In effective mode, comments are returned that are currently effective. In any effective mode, effective comments and those currently expired are returned.
Parameters	`osid.id.Id`	`referenceId`	the `Id` of the reference
Return	`osid.commenting.CommentList`		the returned `CommentList`
Errors	NULL_ARGUMENT		`referenceId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getCommentsForReferenceOnDate
Description	Gets a list of all comments corresponding to a reference `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 comments or an error results. Otherwise, the returned list may contain only those comments that are accessible through this session. In effective mode, comments are returned that are currently effective. In any effective mode, effective comments and those currently expired are returned.
Parameters	`osid.id.Id`	`referenceId`	a reference `Id`
	`osid.calendaring.DateTime`	`from`	from date
	`osid.calendaring.DateTime`	`to`	to date
Return	`osid.commenting.CommentList`		the returned `CommentList`
Errors	INVALID_ARGUMENT		`to` is less than `from`
	NULL_ARGUMENT		`referenceId, from,` or `to` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getCommentsByGenusTypeForReference
Description	Gets a list of comments of the given genus type corresponding to a reference `Id.` In plenary mode, the returned list contains all known comments or an error results. Otherwise, the returned list may contain only those comments that are accessible through this session. In effective mode, comments are returned that are currently effective. In any effective mode, effective comments and those currently expired are returned.
Parameters	`osid.id.Id`	`referenceId`	the `Id` of the reference
Parameters	`osid.type.Type`	`commentGenusType`	the comment genus type
Return	`osid.commenting.CommentList`		the returned `CommentList`
Errors	NULL_ARGUMENT		`referenceId` or `commentGenusType` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getCommentsByGenusTypeForReferenceOnDate
Description	Gets a list of all comments of the given genus type corresponding to a reference `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 comments or an error results. Otherwise, the returned list may contain only those comments that are accessible through this session. In effective mode, comments are returned that are currently effective. In any effective mode, effective comments and those currently expired are returned.
Parameters	`osid.id.Id`	`referenceId`	a reference `Id`
	`osid.type.Type`	`commentGenusType`	the comment genus type
	`osid.calendaring.DateTime`	`from`	from date
	`osid.calendaring.DateTime`	`to`	to date
Return	`osid.commenting.CommentList`		the returned `CommentList`
Errors	INVALID_ARGUMENT		`to` is less than `from`
	NULL_ARGUMENT		`referenceId, commentGenusType, from,` or `to` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getCommentsForCommentorAndReference
Description	Gets a list of comments corresponding to a resource and reference `Id.` In plenary mode, the returned list contains all known comments or an error results. Otherwise, the returned list may contain only those comments that are accessible through this session. In effective mode, comments are returned that are currently effective. In any effective mode, effective comments and those currently expired are returned.
Parameters	`osid.id.Id`	`resourceId`	the `Id` of the resource
Parameters	`osid.id.Id`	`referenceId`	the `Id` of the reference
Return	`osid.commenting.CommentList`		the returned `CommentList`
Errors	NULL_ARGUMENT		`resourceId` or `referenceId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getCommentsForCommentorAndReferenceOnDate
Description	Gets a list of all comments corresponding to a resource and reference `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 comments or an error results. Otherwise, the returned list may contain only those comments that are accessible through this session. In effective mode, comments are returned that are currently effective. In any effective mode, effective comments and those currently expired are returned.
Parameters	`osid.id.Id`	`resourceId`	the `Id` of the resource
	`osid.id.Id`	`referenceId`	a reference `Id`
	`osid.calendaring.DateTime`	`from`	from date
	`osid.calendaring.DateTime`	`to`	to date
Return	`osid.commenting.CommentList`		the returned `CommentList`
Errors	INVALID_ARGUMENT		`to` is less than `from`
	NULL_ARGUMENT		`resourceId, referenceId, from,` or `to` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getCommentsByGenusTypeForCommentorAndReference
Description	Gets a list of comments of the given genus type corresponding to a resource and reference `Id.` In plenary mode, the returned list contains all known comments or an error results. Otherwise, the returned list may contain only those comments that are accessible through this session. In effective mode, comments are returned that are currently effective. In any effective mode, effective comments and those currently expired are returned.
Parameters	`osid.id.Id`	`resourceId`	the `Id` of the resource
	`osid.id.Id`	`referenceId`	the `Id` of the reference
	`osid.type.Type`	`commentGenusType`	the comment genus type
Return	`osid.commenting.CommentList`		the returned `CommentList`
Errors	NULL_ARGUMENT		`resourceId, referenceId` or `commentGenusType` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getCommentsByGenusTypeForCommentorAndReferenceOnDate
Description	Gets a list of all comments corresponding to a resource and reference `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 comments or an error results. Otherwise, the returned list may contain only those comments that are accessible through this session. In effective mode, comments are returned that are currently effective. In any effective mode, effective comments and those currently expired are returned.
Parameters	`osid.id.Id`	`resourceId`	the `Id` of the resource
	`osid.id.Id`	`referenceId`	a reference `Id`
	`osid.type.Type`	`commentGenusType`	the comment genus type
	`osid.calendaring.DateTime`	`from`	from date
	`osid.calendaring.DateTime`	`to`	to date
Return	`osid.commenting.CommentList`		the returned `CommentList`
Errors	INVALID_ARGUMENT		`to` is less than `from`
	NULL_ARGUMENT		`resourceId, referenceId, commentGenusType, from,` or `to` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getComments
Description	Gets all comments. In plenary mode, the returned list contains all known comments or an error results. Otherwise, the returned list may contain only those comments that are accessible through this session. In effective mode, comments are returned that are currently effective. In any effective mode, effective comments and those currently expired are returned.
Return	`osid.commenting.CommentList`		a list of comments
Errors	OPERATION_FAILED		unable to complete request
Errors	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.