Commenting Open Service Interface Definitions commenting version 3.0.0

The Commenting OSID provides a means of relating user comments and ratings to OSID Objects.

The Commenting OSID may be used as an auxiliary service orchestrated with other OSIDs to either provide administrative comments as well as create a social network-esque comment and rating service to various OsidObjects.

Comments

Comments contain text entries logged by date and Agent. A Comment may also include a rating represented by a Grade defined in a GradeSystem. The RatingLookupSession may be used to query cumulative scores across an object reference or the entire Book.

Comments are OsidRelationships between a commentor and a reference Id. The relationship defines dates for which the comment and/or rating is effective.

Commentors

An Agent comments on something. As a person is represented by a Resource in the Resource OSID, the Comments provide access to both the commenting Agent and the related Resource to avoid the need of an additional service orchestration for resolving the Agent.

Cataloging

Comments are cataloged in Books which may also be grouped hierarchically to federate multiple collections of comments.

Sub Packages

The Commenting OSID includes a Commenting Batch OSID for managing Comments and Books in bulk.

Service Managers

Commenting Manager

class dlkit.services.commenting.CommentingManager

Bases: dlkit.osid.managers.OsidManager, dlkit.osid.sessions.OsidSession, dlkit.services.commenting.CommentingProfile

commenting_batch_manager

Gets a CommentingBatchManager.

Returns:a CommentingBatchManager Return type:osid.commenting.batch.CommentingBatchManager Raise:OperationFailed – unable to complete request Raise:Unimplemented – supports_commenting_batch() is false

Commenting Profile Methods

CommentingManager.supports_comment_lookup()

Tests for the availability of a comment lookup service.

Returns:true if comment lookup is available, false otherwise Return type:boolean

CommentingManager.supports_comment_query()

Tests if querying comments is available.

Returns:true if comment query is available, false otherwise Return type:boolean

CommentingManager.supports_comment_admin()

Tests if managing comments is available.

Returns:true if comment admin is available, false otherwise Return type:boolean

CommentingManager.supports_book_lookup()

Tests for the availability of an book lookup service.

Returns:true if book lookup is available, false otherwise Return type:boolean

CommentingManager.supports_book_admin()

Tests for the availability of a book administrative service for creating and deleting books.

Returns:true if book administration is available, false otherwise Return type:boolean

CommentingManager.supports_book_hierarchy()

Tests for the availability of a book hierarchy traversal service.

Returns:true if book hierarchy traversal is available, false otherwise Return type:boolean

CommentingManager.supports_book_hierarchy_design()

Tests for the availability of a book hierarchy design service.

Returns:true if book hierarchy design is available, false otherwise Return type:boolean

CommentingManager.comment_record_types

Gets the supported Comment record types.

Returns:a list containing the supported comment record types Return type:osid.type.TypeList

CommentingManager.comment_search_record_types

Gets the supported comment search record types.

Returns:a list containing the supported comment search record types Return type:osid.type.TypeList

CommentingManager.book_record_types

Gets the supported Book record types.

Returns:a list containing the supported book record types Return type:osid.type.TypeList

CommentingManager.book_search_record_types

Gets the supported book search record types.

Returns:a list containing the supported book search record types Return type:osid.type.TypeList

Book Lookup Methods

CommentingManager.can_lookup_books()

Tests if this user can perform Book lookups. 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 offer lookup operations to unauthorized users.

Returns:false if lookup methods are not authorized, true otherwise Return type:boolean

CommentingManager.use_comparative_book_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.

CommentingManager.use_plenary_book_view()

A complete view of the Book 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.

CommentingManager.get_books_by_ids(book_ids)

Gets a BookList corresponding to the given IdList. In plenary mode, the returned list contains all of the books 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 Books may be omitted from the list and may present the elements in any order including returning a unique set.

Parameters:book_ids (osid.id.IdList) – the list of Ids to retrieve Returns:the returned Book list Return type:osid.commenting.BookList Raise:NotFound – an Id was not found Raise:NullArgument – book_ids is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

CommentingManager.get_books_by_genus_type(book_genus_type)

Gets a BookList corresponding to the given book genus Type which does not include books of genus types derived from the specified Type. In plenary mode, the returned list contains all known books or an error results. Otherwise, the returned list may contain only those books that are accessible through this session.

Parameters:book_genus_type (osid.type.Type) – a book genus type Returns:the returned Book list Return type:osid.commenting.BookList Raise:NullArgument – book_genus_type is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

CommentingManager.get_books_by_parent_genus_type(book_genus_type)

Gets a BookList corresponding to the given book genus Type and include any additional books with genus types derived from the specified Type. In plenary mode, the returned list contains all known books or an error results. Otherwise, the returned list may contain only those books that are accessible through this session.

Parameters:book_genus_type (osid.type.Type) – a book genus type Returns:the returned Book list Return type:osid.commenting.BookList Raise:NullArgument – book_genus_type is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

CommentingManager.get_books_by_record_type(book_record_type)

Gets a BookList containing the given book record Type. In plenary mode, the returned list contains all known books or an error results. Otherwise, the returned list may contain only those books that are accessible through this session.

Parameters:book_record_type (osid.type.Type) – a book record type Returns:the returned Book list Return type:osid.commenting.BookList Raise:NullArgument – book_record_type is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

CommentingManager.get_books_by_provider(resource_id)

Gets a BookList from the given provider ````. In plenary mode, the returned list contains all known books or an error results. Otherwise, the returned list may contain only those books that are accessible through this session.

Parameters:resource_id (osid.id.Id) – a resource Id Returns:the returned Book list Return type:osid.commenting.BookList Raise:NullArgument – resource_id is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

CommentingManager.books

Gets all Books. In plenary mode, the returned list contains all known books or an error results. Otherwise, the returned list may contain only those books that are accessible through this session.

Returns:a list of Books Return type:osid.commenting.BookList Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

Book Admin Methods

CommentingManager.can_create_books()

Tests if this user can create Books. A return of true does not guarantee successful authorization. A return of false indicates that it is known creating a Book will result in a PermissionDenied. This is intended as a hint to an application that may not wish to offer create operations to unauthorized users.

Returns:false if Book creation is not authorized, true otherwise Return type:boolean

CommentingManager.can_create_book_with_record_types(book_record_types)

Tests if this user can create a single Book using the desired record types. While CommentingManager.getBookRecordTypes() can be used to examine which records are supported, this method tests which record(s) are required for creating a specific Book. Providing an empty array tests if a Book can be created with no records.

Parameters:book_record_types (osid.type.Type[]) – array of book record types Returns:true if Book creation using the specified record Types is supported, false otherwise Return type:boolean Raise:NullArgument – book_record_types is null

CommentingManager.get_book_form_for_create(book_record_types)

Gets the book form for creating new books. A new form should be requested for each create transaction.

Parameters:book_record_types (osid.type.Type[]) – array of book record types Returns:the book form Return type:osid.commenting.BookForm Raise:NullArgument – book_record_types is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure Raise:Unsupported – unable to get form for requested record types

CommentingManager.create_book(book_form)

Creates a new Book.

Parameters:book_form (osid.commenting.BookForm) – the form for this Book Returns:the new Book Return type:osid.commenting.Book Raise:IllegalState – book_form already used in a create transaction Raise:InvalidArgument – one or more of the form elements is invalid Raise:NullArgument – book_form is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure Raise:Unsupported – book_form did not originte from get_book_form_for_create()

CommentingManager.can_update_books()

Tests if this user can update Books. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating a Book will result in a PermissionDenied. This is intended as a hint to an application that may not wish to offer update operations to unauthorized users.

Returns:false if Book modification is not authorized, true otherwise Return type:boolean

CommentingManager.get_book_form_for_update(book_id)

Gets the book form for updating an existing book. A new book form should be requested for each update transaction.

Parameters:book_id (osid.id.Id) – the Id of the Book Returns:the book form Return type:osid.commenting.BookForm Raise:NotFound – book_id is not found Raise:NullArgument – book_id is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

CommentingManager.update_book(book_form)

Updates an existing book.

Parameters:book_form (osid.commenting.BookForm) – the form containing the elements to be updated Raise:IllegalState – book_form already used in an update transaction Raise:InvalidArgument – the form contains an invalid value Raise:NullArgument – book_form is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure Raise:Unsupported – book_form did not originte from get_book_form_for_update()

CommentingManager.can_delete_books()

Tests if this user can delete Books A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting a Book will result in a PermissionDenied. This is intended as a hint to an application that may not wish to offer delete operations to unauthorized users.

Returns:false if Book deletion is not authorized, true otherwise Return type:boolean

CommentingManager.delete_book(book_id)

Deletes a Book.

Parameters:book_id (osid.id.Id) – the Id of the Book to remove Raise:NotFound – book_id not found Raise:NullArgument – book_id is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

CommentingManager.can_manage_book_aliases()

Tests if this user can manage Id aliases for Books. A return of true does not guarantee successful authorization. A return of false indicates that it is known changing an alias will result in a PermissionDenied. This is intended as a hint to an application that may opt not to offer alias operations to an unauthorized user.

Returns:false if Book aliasing is not authorized, true otherwise Return type:boolean

CommentingManager.alias_book(book_id, alias_id)

Adds an Id to a Book for the purpose of creating compatibility. The primary Id of the Book is determined by the provider. The new Id performs as an alias to the primary Id. If the alias is a pointer to another book, it is reassigned to the given book Id.

Parameters:

• book_id (osid.id.Id) – the Id of a Book
• alias_id (osid.id.Id) – the alias Id

Raise:

AlreadyExists – alias_id is already assigned

Raise:

NotFound – book_id not found

Raise:

NullArgument – book_id or alias_id is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

Book Hierarchy Methods

CommentingManager.book_hierarchy_id

Gets the hierarchy Id associated with this session.

Returns:the hierarchy Id associated with this session Return type:osid.id.Id

CommentingManager.book_hierarchy

Gets the hierarchy associated with this session.

Returns:the hierarchy associated with this session Return type:osid.hierarchy.Hierarchy Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

CommentingManager.can_access_book_hierarchy()

Tests if this user can perform hierarchy queries. 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 lookup operations.

Returns:false if hierarchy traversal methods are not authorized, true otherwise Return type:boolean

CommentingManager.use_comparative_book_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.

CommentingManager.use_plenary_book_view()

A complete view of the Book 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.

CommentingManager.root_book_ids

Gets the root book Ids in this hierarchy.

Returns:the root book Ids Return type:osid.id.IdList Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

CommentingManager.root_books

Gets the root books in the book hierarchy. A node with no parents is an orphan. While all book Ids are known to the hierarchy, an orphan does not appear in the hierarchy unless explicitly added as a root node or child of another node.

Returns:the root books Return type:osid.commenting.BookList Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

CommentingManager.has_parent_books(book_id)

Tests if the Book has any parents.

Parameters:book_id (osid.id.Id) – a book Id Returns:true if the book has parents, f alse otherwise Return type:boolean Raise:NotFound – book_id is not found Raise:NullArgument – book_id is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

CommentingManager.is_parent_of_book(id_, book_id)

Tests if an Id is a direct parent of book.

Parameters:

• id (osid.id.Id) – an Id
• book_id (osid.id.Id) – the Id of a book

Returns:

true if this id is a parent of book_id, f alse otherwise

Return type:

boolean

Raise:

NotFound – book_id is not found

Raise:

NullArgument – id or book_id is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

CommentingManager.get_parent_book_ids(book_id)

Gets the parent Ids of the given book.

Parameters:book_id (osid.id.Id) – a book Id Returns:the parent Ids of the book Return type:osid.id.IdList Raise:NotFound – book_id is not found Raise:NullArgument – book_id is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

CommentingManager.get_parent_books(book_id)

Gets the parent books of the given id.

Parameters:book_id (osid.id.Id) – the Id of the Book to query Returns:the parent books of the id Return type:osid.commenting.BookList Raise:NotFound – a Book identified by Id is not found Raise:NullArgument – book_id is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

CommentingManager.is_ancestor_of_book(id_, book_id)

Tests if an Id is an ancestor of a book.

Parameters:

• id (osid.id.Id) – an Id
• book_id (osid.id.Id) – the Id of a book

Returns:

tru e if this id is an ancestor of book_id, false otherwise

Return type:

boolean

Raise:

NotFound – book_id is not found

Raise:

NullArgument – id or book_id is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

CommentingManager.has_child_books(book_id)

Tests if a book has any children.

Parameters:book_id (osid.id.Id) – a book Id Returns:true if the book_id has children, false otherwise Return type:boolean Raise:NotFound – book_id is not found Raise:NullArgument – book_id is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

CommentingManager.is_child_of_book(id_, book_id)

Tests if a book is a direct child of another.

Parameters:

• id (osid.id.Id) – an Id
• book_id (osid.id.Id) – the Id of a book

Returns:

true if the id is a child of book_id, false otherwise

Return type:

boolean

Raise:

NotFound – book_id is not found

Raise:

NullArgument – id or book_id is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

CommentingManager.get_child_book_ids(book_id)

Gets the child Ids of the given book.

Parameters:book_id (osid.id.Id) – the Id to query Returns:the children of the book Return type:osid.id.IdList Raise:NotFound – book_id is not found Raise:NullArgument – book_id is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

CommentingManager.get_child_books(book_id)

Gets the child books of the given id.

Parameters:book_id (osid.id.Id) – the Id of the Book to query Returns:the child books of the id Return type:osid.commenting.BookList Raise:NotFound – a Book identified by Id is not found Raise:NullArgument – book_id is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

CommentingManager.is_descendant_of_book(id_, book_id)

Tests if an Id is a descendant of a book.

Parameters:

• id (osid.id.Id) – an Id
• book_id (osid.id.Id) – the Id of a book

Returns:

true if the id is a descendant of the book_id, false otherwise

Return type:

boolean

Raise:

NotFound – book_id is not found

Raise:

NullArgument – id or book_id is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

CommentingManager.get_book_node_ids(book_id, ancestor_levels, descendant_levels, include_siblings)

Gets a portion of the hierarchy for the given book.

Parameters:

• book_id (osid.id.Id) – the Id to query
• ancestor_levels (cardinal) – the maximum number of ancestor levels to include. A value of 0 returns no parents in the node.
• descendant_levels (cardinal) – the maximum number of descendant levels to include. A value of 0 returns no children in the node.
• include_siblings (boolean) – true to include the siblings of the given node, false to omit the siblings

Returns:

a book node

Return type:

osid.hierarchy.Node

Raise:

NotFound – book_id is not found

Raise:

NullArgument – book_id is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

CommentingManager.get_book_nodes(book_id, ancestor_levels, descendant_levels, include_siblings)

Gets a portion of the hierarchy for the given book.

Parameters:

• book_id (osid.id.Id) – the Id to query
• ancestor_levels (cardinal) – the maximum number of ancestor levels to include. A value of 0 returns no parents in the node.
• descendant_levels (cardinal) – the maximum number of descendant levels to include. A value of 0 returns no children in the node.
• include_siblings (boolean) – true to include the siblings of the given node, false to omit the siblings

Returns:

a book node

Return type:

osid.commenting.BookNode

Raise:

NotFound – book_id is not found

Raise:

NullArgument – book_id is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

Book Hierarchy Design Methods

CommentingManager.book_hierarchy_id

Gets the hierarchy Id associated with this session.

Returns:the hierarchy Id associated with this session Return type:osid.id.Id

CommentingManager.book_hierarchy

Gets the hierarchy associated with this session.

Returns:the hierarchy associated with this session Return type:osid.hierarchy.Hierarchy Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

CommentingManager.can_modify_book_hierarchy()

Tests if this user can change the hierarchy. A return of true does not guarantee successful authorization. A return of false indicates that it is known performing any update will result in a PermissionDenied. This is intended as a hint to an application that may opt not to offer these operations to an unauthorized user.

Returns:false if changing this hierarchy is not authorized, true otherwise Return type:boolean

CommentingManager.add_root_book(book_id)

Adds a root book.

Parameters:book_id (osid.id.Id) – the Id of a book Raise:AlreadyExists – book_id is already in hierarchy Raise:NotFound – book_id is not found Raise:NullArgument – book_id is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

CommentingManager.remove_root_book(book_id)

Removes a root book.

Parameters:book_id (osid.id.Id) – the Id of a book Raise:NotFound – book_id is not a root Raise:NullArgument – book_id is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

CommentingManager.add_child_book(book_id, child_id)

Adds a child to a book.

Parameters:

• book_id (osid.id.Id) – the Id of a book
• child_id (osid.id.Id) – the Id of the new child

Raise:

AlreadyExists – book_id is already a parent of child_id

Raise:

NotFound – book_id or child_id not found

Raise:

NullArgument – book_id or child_id is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

CommentingManager.remove_child_book(book_id, child_id)

Removes a child from a book.

Parameters:

• book_id (osid.id.Id) – the Id of a book
• child_id (osid.id.Id) – the Id of the new child

Raise:

NotFound – book_id not a parent of child_id

Raise:

NullArgument – book_id or child_id is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

CommentingManager.remove_child_books(book_id)

Removes all children from a book.

Parameters:book_id (osid.id.Id) – the Id of a book Raise:NotFound – book_id not found Raise:NullArgument – book_id is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure