Book¶
Book¶
-
class
dlkit.services.commenting.
Book
¶ Bases:
dlkit.osid.objects.OsidCatalog
,dlkit.osid.sessions.OsidSession
-
get_book_record
(book_record_type)¶ Gets the book record corresponding to the given
Book
recordType
. This method is used to retrieve an object implementing the requested record. Thebook_record_type
may be theType
returned inget_record_types()
or any of its parents in aType
hierarchy wherehas_record_type(book_record_type)
istrue
.Parameters: book_record_type ( osid.type.Type
) – the type of book record to retrieveReturns: the book record Return type: osid.commenting.records.BookRecord
Raise: NullArgument
–book_record_type
isnull
Raise: OperationFailed
– unable to complete requestRaise: Unsupported
–has_record_type(book_record_type)
isfalse
-
Comment Lookup Methods¶
Book.
can_lookup_comments
()¶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
PermissionDenied
. This is intended as a hint to an application that may opt not to offer these operations.
Returns: false
if book reading methods are not authorized,true
otherwiseReturn type: boolean
Book.
use_comparative_comment_view
()¶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.
Book.
use_plenary_comment_view
()¶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.
Book.
use_federated_book_view
()¶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.
Book.
use_isolated_book_view
()¶Isolates the view for methods in this session. An isolated view restricts retrievals to this book only.
Book.
use_effective_comment_view
()¶Only comments whose effective dates are current are returned by methods in this session.
Book.
use_any_effective_comment_view
()¶All comments of any effective dates are returned by all methods in this session.
Book.
get_comment
(comment_id)¶Gets the
Comment
specified by itsId
.
Parameters: comment_id ( osid.id.Id
) – theId
of theComment
to retrieveReturns: the returned Comment
Return type: osid.commenting.Comment
Raise: NotFound
– noComment
found with the givenId
Raise: NullArgument
–comment_id
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failure
Book.
get_comments_by_ids
(comment_ids)¶Gets a
CommentList
corresponding to the givenIdList
.
Parameters: comment_ids ( osid.id.IdList
) – the list ofIds
to retrieveReturns: the returned Comment list
Return type: osid.commenting.CommentList
Raise: NotFound
– anId was
not foundRaise: NullArgument
–comment_ids
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failure
Book.
get_comments_by_genus_type
(comment_genus_type)¶Gets a
CommentList
corresponding to the given comment genusType
which does not include comments of genus types derived from the specifiedType
.
Parameters: comment_genus_type ( osid.type.Type
) – a comment genus typeReturns: the returned Comment
listReturn type: osid.commenting.CommentList
Raise: NullArgument
–comment_genus_type
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failure
Book.
get_comments_by_parent_genus_type
(comment_genus_type)¶Gets a
CommentList
corresponding to the given comment genusType
and include any additional comments with genus types derived from the specifiedType
.
Parameters: comment_genus_type ( osid.type.Type
) – a comment genus typeReturns: the returned Comment
listReturn type: osid.commenting.CommentList
Raise: NullArgument
–comment_genus_type
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failure
Book.
get_comments_by_record_type
(comment_record_type)¶Gets a
CommentList
containing the given comment recordType
.
Parameters: comment_record_type ( osid.type.Type
) – a comment record typeReturns: the returned Comment
listReturn type: osid.commenting.CommentList
Raise: NullArgument
–comment_record_type
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failure
Book.
get_comments_on_date
(from_, to)¶Gets a
CommentList
effective during the entire given date range inclusive but not confined to the date range.
Parameters:
- from (
osid.calendaring.DateTime
) – starting date- to (
osid.calendaring.DateTime
) – ending dateReturns: the returned
Comment
listReturn type:
osid.commenting.CommentList
Raise:
InvalidArgument
–from
is greater thanto
Raise:
NullArgument
–from
orto
isnull
Raise:
OperationFailed
– unable to complete requestRaise:
PermissionDenied
– authorization failure
Book.
get_comments_by_genus_type_on_date
(comment_genus_type, from_, to)¶Gets a
CommentList
of a given genus type and effective during the entire given date range inclusive but not confined to the date range.
Parameters:
- comment_genus_type (
osid.type.Type
) – a comment genus type- from (
osid.calendaring.DateTime
) – starting date- to (
osid.calendaring.DateTime
) – ending dateReturns: the returned
Comment
listReturn type:
osid.commenting.CommentList
Raise:
InvalidArgument
–from
is greater thanto
Raise:
NullArgument
–comment_genus_type, from,
orto
isnull
Raise:
OperationFailed
– unable to complete requestRaise:
PermissionDenied
– authorization failure
Book.
get_comments_for_commentor
(resource_id)¶Gets a list of comments corresponding to a resource
Id
.
Parameters: resource_id ( osid.id.Id
) – theId
of the resourceReturns: the returned CommentList
Return type: osid.commenting.CommentList
Raise: NullArgument
–resource_id
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failure
Book.
get_comments_for_commentor_on_date
(resource_id, from_, to)¶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.
Parameters:
- resource_id (
osid.id.Id
) – theId
of the resource- from (
osid.calendaring.DateTime
) – from date- to (
osid.calendaring.DateTime
) – to dateReturns: the returned
CommentList
Return type:
osid.commenting.CommentList
Raise:
InvalidArgument
–to
is less thanfrom
Raise:
NullArgument
–resource_id, from,
orto
isnull
Raise:
OperationFailed
– unable to complete requestRaise:
PermissionDenied
– authorization failure
Book.
get_comments_by_genus_type_for_commentor
(resource_id, comment_genus_type)¶Gets a list of comments of the given genus type corresponding to a resource
Id
.
Parameters:
- resource_id (
osid.id.Id
) – theId
of the resource- comment_genus_type (
osid.type.Type
) – the comment genus typeReturns: the returned
CommentList
Return type:
osid.commenting.CommentList
Raise:
NullArgument
–resource_id
orcomment_genus_type
isnull
Raise:
OperationFailed
– unable to complete requestRaise:
PermissionDenied
– authorization failure
Book.
get_comments_by_genus_type_for_commentor_on_date
(resource_id, comment_genus_type, from_, to)¶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.
Parameters:
- resource_id (
osid.id.Id
) – theId
of the resource- comment_genus_type (
osid.type.Type
) – the comment genus type- from (
osid.calendaring.DateTime
) – from date- to (
osid.calendaring.DateTime
) – to dateReturns: the returned
CommentList
Return type:
osid.commenting.CommentList
Raise:
InvalidArgument
–to
is less thanfrom
Raise:
NullArgument
–resource_id, comment_genus_type, from,
orto
isnull
Raise:
OperationFailed
– unable to complete requestRaise:
PermissionDenied
– authorization failure
Book.
get_comments_for_reference
(reference_id)¶Gets a list of comments corresponding to a reference
Id
.
Parameters: reference_id ( osid.id.Id
) – theId
of the referenceReturns: the returned CommentList
Return type: osid.commenting.CommentList
Raise: NullArgument
–reference_id
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failure
Book.
get_comments_for_reference_on_date
(reference_id, from_, to)¶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.
Parameters:
- reference_id (
osid.id.Id
) – a referenceId
- from (
osid.calendaring.DateTime
) – from date- to (
osid.calendaring.DateTime
) – to dateReturns: the returned
CommentList
Return type:
osid.commenting.CommentList
Raise:
InvalidArgument
–to
is less thanfrom
Raise:
NullArgument
–reference_id, from,
orto
isnull
Raise:
OperationFailed
– unable to complete requestRaise:
PermissionDenied
– authorization failure
Book.
get_comments_by_genus_type_for_reference
(reference_id, comment_genus_type)¶Gets a list of comments of the given genus type corresponding to a reference
Id
.
Parameters:
- reference_id (
osid.id.Id
) – theId
of the reference- comment_genus_type (
osid.type.Type
) – the comment genus typeReturns: the returned
CommentList
Return type:
osid.commenting.CommentList
Raise:
NullArgument
–reference_id
orcomment_genus_type
isnull
Raise:
OperationFailed
– unable to complete requestRaise:
PermissionDenied
– authorization failure
Book.
get_comments_by_genus_type_for_reference_on_date
(reference_id, comment_genus_type, from_, to)¶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.
Parameters:
- reference_id (
osid.id.Id
) – a referenceId
- comment_genus_type (
osid.type.Type
) – the comment genus type- from (
osid.calendaring.DateTime
) – from date- to (
osid.calendaring.DateTime
) – to dateReturns: the returned
CommentList
Return type:
osid.commenting.CommentList
Raise:
InvalidArgument
–to
is less thanfrom
Raise:
NullArgument
–reference_id, comment_genus_type, from,
orto
isnull
Raise:
OperationFailed
– unable to complete requestRaise:
PermissionDenied
– authorization failure
Book.
get_comments_for_commentor_and_reference
(resource_id, reference_id)¶Gets a list of comments corresponding to a resource and reference
Id
.
Parameters:
- resource_id (
osid.id.Id
) – theId
of the resource- reference_id (
osid.id.Id
) – theId
of the referenceReturns: the returned
CommentList
Return type:
osid.commenting.CommentList
Raise:
NullArgument
–resource_id
orreference_id
isnull
Raise:
OperationFailed
– unable to complete requestRaise:
PermissionDenied
– authorization failure
Book.
get_comments_for_commentor_and_reference_on_date
(resource_id, reference_id, from_, to)¶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.
Parameters:
- resource_id (
osid.id.Id
) – theId
of the resource- reference_id (
osid.id.Id
) – a referenceId
- from (
osid.calendaring.DateTime
) – from date- to (
osid.calendaring.DateTime
) – to dateReturns: the returned
CommentList
Return type:
osid.commenting.CommentList
Raise:
InvalidArgument
–to
is less thanfrom
Raise:
NullArgument
–resource_id, reference_id, from,
orto
isnull
Raise:
OperationFailed
– unable to complete requestRaise:
PermissionDenied
– authorization failure
Book.
get_comments_by_genus_type_for_commentor_and_reference
(resource_id, reference_id, comment_genus_type)¶Gets a list of comments of the given genus type corresponding to a resource and reference
Id
.
Parameters:
- resource_id (
osid.id.Id
) – theId
of the resource- reference_id (
osid.id.Id
) – theId
of the reference- comment_genus_type (
osid.type.Type
) – the comment genus typeReturns: the returned
CommentList
Return type:
osid.commenting.CommentList
Raise:
NullArgument
–resource_id, reference_id
orcomment_genus_type
isnull
Raise:
OperationFailed
– unable to complete requestRaise:
PermissionDenied
– authorization failure
Book.
get_comments_by_genus_type_for_commentor_and_reference_on_date
(resource_id, reference_id, comment_genus_type, from_, to)¶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.
Parameters:
- resource_id (
osid.id.Id
) – theId
of the resource- reference_id (
osid.id.Id
) – a referenceId
- comment_genus_type (
osid.type.Type
) – the comment genus type- from (
osid.calendaring.DateTime
) – from date- to (
osid.calendaring.DateTime
) – to dateReturns: the returned
CommentList
Return type:
osid.commenting.CommentList
Raise:
InvalidArgument
–to
is less thanfrom
Raise:
NullArgument
–resource_id, reference_id, comment_genus_type, from,
orto
isnull
Raise:
OperationFailed
– unable to complete requestRaise:
PermissionDenied
– authorization failure
Book.
comments
¶Gets all comments.
Returns: a list of comments Return type: osid.commenting.CommentList
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failure
Comment Query Methods¶
Book.
can_search_comments
()¶Tests if this user can perform comment searches. 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
PermissionDenied
. This is intended as a hint to an application that may not wish to offer search operations to unauthorized users.
Returns: false
if search methods are not authorized,true
otherwiseReturn type: boolean
Book.
use_federated_book_view
()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.
Book.
use_isolated_book_view
()Isolates the view for methods in this session. An isolated view restricts retrievals to this book only.
Book.
comment_query
¶Gets a comment query.
Returns: the comment query Return type: osid.commenting.CommentQuery
Book.
get_comments_by_query
(comment_query)¶Gets a list of comments matching the given search.
Parameters: comment_query ( osid.commenting.CommentQuery
) – the search query arrayReturns: the returned CommentList
Return type: osid.commenting.CommentList
Raise: NullArgument
–comment_query
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failureRaise: Unsupported
–comment_query
is not of this service
Comment Admin Methods¶
Book.
can_create_comments
()¶Tests if this user can create comments. A return of true does not guarantee successful authorization. A return of false indicates that it is known creating a
Comment
will result in aPermissionDenied
. This is intended as a hint to an application that may not wish to offer create operations to unauthorized users.
Returns: false
ifComment
creation is not authorized,true
otherwiseReturn type: boolean
Book.
can_create_comment_with_record_types
(comment_record_types)¶Tests if this user can create a single
Comment
using the desired record types. WhileCommentingManager.getCommentRecordTypes()
can be used to examine which records are supported, this method tests which record(s) are required for creating a specificComment
. Providing an empty array tests if aComment
can be created with no records.
Parameters: comment_record_types ( osid.type.Type[]
) – array of comment record typesReturns: true
ifComment
creation using the specified recordTypes
is supported,false
otherwiseReturn type: boolean
Raise: NullArgument
–comment_record_types
isnull
Book.
get_comment_form_for_create
(reference_id, comment_record_types)¶Gets the comment form for creating new comments. A new form should be requested for each create transaction.
Parameters:
- reference_id (
osid.id.Id
) – theId
for the reference object- comment_record_types (
osid.type.Type[]
) – array of comment record typesReturns: the comment form
Return type:
osid.commenting.CommentForm
Raise:
NullArgument
–reference_id or comment_record_types
isnull
Raise:
OperationFailed
– unable to complete requestRaise:
PermissionDenied
– authorization failureRaise:
Unsupported
– unable to get form for requested record types
Book.
create_comment
(comment_form)¶Creates a new
Comment
.
Parameters: comment_form ( osid.commenting.CommentForm
) – the form for thisComment
Returns: the new Comment
Return type: osid.commenting.Comment
Raise: IllegalState
–comment_form
already used in a create transactionRaise: InvalidArgument
– one or more of the form elements is invalidRaise: NullArgument
–comment_form
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failureRaise: Unsupported
–comment_form
did not originate fromget_comment_form_for_create()
Book.
can_update_comments
()¶Tests if this user can update comments. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating a
Comment
will result in aPermissionDenied
. This is intended as a hint to an application that may not wish to offer update operations to unauthorized users.
Returns: false
ifComment
modification is not authorized,true
otherwiseReturn type: boolean
Book.
get_comment_form_for_update
(comment_id)¶Gets the comment form for updating an existing comment. A new comment form should be requested for each update transaction.
Parameters: comment_id ( osid.id.Id
) – theId
of theComment
Returns: the comment form Return type: osid.commenting.CommentForm
Raise: NotFound
–comment_id
is not foundRaise: NullArgument
–comment_id
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failure
Book.
update_comment
(comment_form)¶Updates an existing comment.
Parameters: comment_form ( osid.commenting.CommentForm
) – the form containing the elements to be updatedRaise: IllegalState
–comment_form
already used in an update transactionRaise: InvalidArgument
– the form contains an invalid valueRaise: NullArgument
–comment_form
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failureRaise: Unsupported
–comment_form
did not originate fromget_comment_form_for_update()
Book.
can_delete_comments
()¶Tests if this user can delete comments. A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting an
Comment
will result in aPermissionDenied
. This is intended as a hint to an application that may not wish to offer delete operations to unauthorized users.
Returns: false
ifComment
deletion is not authorized,true
otherwiseReturn type: boolean
Book.
delete_comment
(comment_id)¶Deletes a
Comment
.
Parameters: comment_id ( osid.id.Id
) – theId
of theComment
to removeRaise: NotFound
–comment_id
not foundRaise: NullArgument
–comment_id
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failure
Book.
can_manage_comment_aliases
()¶Tests if this user can manage
Id
aliases forComnents
. A return of true does not guarantee successful authorization. A return of false indicates that it is known changing an alias will result in aPermissionDenied
. This is intended as a hint to an application that may opt not to offer alias operations to an unauthorized user.
Returns: false
ifComment
aliasing is not authorized,true
otherwiseReturn type: boolean
Book.
alias_comment
(comment_id, alias_id)¶Adds an
Id
to aComment
for the purpose of creating compatibility. The primaryId
of theComment
is determined by the provider. The newId
performs as an alias to the primaryId
. If the alias is a pointer to another comment, it is reassigned to the given commentId
.
Parameters:
- comment_id (
osid.id.Id
) – theId
of aComment
- alias_id (
osid.id.Id
) – the aliasId
Raise:
AlreadyExists
–alias_id
is already assignedRaise:
NotFound
–comment_id
not foundRaise:
NullArgument
–comment_id
oralias_id
isnull
Raise:
OperationFailed
– unable to complete requestRaise:
PermissionDenied
– authorization failure