org.osid.commenting

Interface BookAdminSession

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable, OsidSession

All Known Subinterfaces:

BookBatchAdminSession

public interface BookAdminSession
extends OsidSession

This session creates, updates, and deletes Books. The data for create and update is provided by the consumer via the form object. OsidForms are requested for each create or update and may not be reused.

Create and update operations differ in their usage. To create a Book, a BookForm is requested using getBookFormForCreate() specifying the desired record Types or none if no record Types are needed. The returned BookForm will indicate that it is to be used with a create operation and can be used to examine metdata or validate data prior to creation. Once the BookForm is submiited to a create operation, it cannot be reused with another create operation unless the first operation was unsuccessful. Each BookForm corresponds to an attempted transaction.

For updates, BookForms are requested to the Book Id that is to be updated using getBookFormForUpdate(). Similarly, the BookForm has metadata about the data that can be updated and it can perform validation before submitting the update. The BookForm can only be used once for a successful update and cannot be reused.

The delete operations delete Books.

This session includes an Id aliasing mechanism to assign an external Id to an internally assigned Id.

Method Summary

Methods

Modifier and Type	Method and Description
void	aliasBook(Id bookId, Id aliasId) Adds an Id to a Book for the purpose of creating compatibility.
boolean	canCreateBooks() Tests if this user can create Books.
boolean	canCreateBookWithRecordTypes(Type[] bookRecordTypes) Tests if this user can create a single Book using the desired record types.
boolean	canDeleteBooks() Tests if this user can delete Books A return of true does not guarantee successful authorization.
boolean	canManageBookAliases() Tests if this user can manage Id aliases for Books.
boolean	canUpdateBooks() Tests if this user can update Books.
Book	createBook(BookForm bookForm) Creates a new Book.
void	deleteBook(Id bookId) Deletes a Book.
BookForm	getBookFormForCreate(Type[] bookRecordTypes) Gets the book form for creating new books.
BookForm	getBookFormForUpdate(Id bookId) Gets the book form for updating an existing book.
void	updateBook(BookForm bookForm) Updates an existing book.

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

canCreateBooks

boolean canCreateBooks()

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 PERMISSION_DENIED. 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

Compliance:

mandatory - This method must be implemented.

canCreateBookWithRecordTypes

boolean canCreateBookWithRecordTypes(Type[] bookRecordTypes)

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:

bookRecordTypes - array of book record types

Returns:

true if Book creation using the specified record Types is supported, false otherwise

Throws:

NullArgumentException - bookRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getBookFormForCreate

BookForm getBookFormForCreate(Type[] bookRecordTypes)
                              throws OperationFailedException,
                                     PermissionDeniedException

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

Parameters:

bookRecordTypes - array of book record types

Returns:

the book form

Throws:

NullArgumentException - bookRecordTypes is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - unable to get form for requested record types

Compliance:

mandatory - This method must be implemented.

createBook

Book createBook(BookForm bookForm)
                throws OperationFailedException,
                       PermissionDeniedException

Creates a new Book.

Parameters:

bookForm - the form for this Book

Returns:

the new Book

Throws:

IllegalStateException - bookForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - bookForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - bookForm did not originte from getBookFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateBooks

boolean canUpdateBooks()

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 PERMISSION_DENIED. 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

Compliance:

mandatory - This method must be implemented.

getBookFormForUpdate

BookForm getBookFormForUpdate(Id bookId)
                              throws NotFoundException,
                                     OperationFailedException,
                                     PermissionDeniedException

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

Parameters:

bookId - the Id of the Book

Returns:

the book form

Throws:

NotFoundException - bookId is not found

NullArgumentException - bookId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateBook

void updateBook(BookForm bookForm)
                throws OperationFailedException,
                       PermissionDeniedException

Updates an existing book.

Parameters:

bookForm - the form containing the elements to be updated

Throws:

IllegalStateException - bookForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - bookForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - bookForm did not originte from getBookFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteBooks

boolean canDeleteBooks()

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 PERMISSION_DENIED. 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

Compliance:

mandatory - This method must be implemented.

deleteBook

void deleteBook(Id bookId)
                throws NotFoundException,
                       OperationFailedException,
                       PermissionDeniedException

Deletes a Book.

Parameters:

bookId - the Id of the Book to remove

Throws:

NotFoundException - bookId not found

NullArgumentException - bookId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageBookAliases

boolean canManageBookAliases()

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 PERMISSION_DENIED. 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

Compliance:

mandatory - This method must be implemented.

aliasBook

void aliasBook(Id bookId,
             Id aliasId)
               throws AlreadyExistsException,
                      NotFoundException,
                      OperationFailedException,
                      PermissionDeniedException

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:

bookId - the Id of a Book

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is already assigned

NotFoundException - bookId not found

NullArgumentException - bookId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.