# com.bea.netuix.application.manager
IBookInstanceManager Interface

public interface IBookInstanceManager

This is the primary interface for performing persistent store operations on `BookInstance` objects. In general this interface provides coarse grain getters and fine grain setters.

It is important to note that all methods on this interface are fully internationalized and entitled. All `titles` and `descriptions` on the objects returned by these methods are internationalized to the prefered locale. Also, all methods are entitled, meaning if the caller does not have the required credentials the method may return a subset of the actual list or be unable to perform the specified function.

Most "Instances" can be thought of as objects tied to a desktop, An Admin has instances derived from the Library Definition, and the "end user" has instances derived from the admin instance. Changes made via these APIs require a DesktopDefinitionId and the changes are scoped to that desktop. In other words changes made here do not affect the Library or other Desktops. If the "visitorMode" on the customization Context is set the false (default) and the user executing the call is in the "Admin" or "PortalSystemAdministrator" role then these changes take affect at the admin level, and affect ALL users. If the visitorMode is false then the changes only affect the calling user.

Related Topics

``CustomizationContext.setVisitorMode(boolean)``

All Known Subinterfaces
  `PortalCustomizationManager`

## Method Summary

`public `NavigableInstance`` | `addNavigable`(`CustomizationContext` customizationContext, `DesktopDefinitionId` desktopDefinitionId, `BookInstanceId` bookInstanceId, `NavigableDefinitionId` navigableDefinitionId, int position, int align) Add a `NavigableDefinition` (BookDefinition or PageDefinition) to the supplied Book Instance.
`public `BookInstance`` | `getBookInstance`(`CustomizationContext` customizationContext, `BookInstanceId` bookInstanceId) Getter for returning a `BookInstance` identified by the supplieed instance id.
`public `BookView`` | `getBookView`(`CustomizationContext` customizationContext, `DesktopDefinitionId` desktopDefinitionId, `BookInstanceId` bookInstanceId) Getter for returning an immutable deep copy of a `BookView`.
`public `NavigableInstance`` | `moveNavigable`(`CustomizationContext` customizationContext, `DesktopDefinitionId` desktopDefinitionId, `BookInstanceId` fromParentBookInstanceId, `BookInstanceId` toParentBookInstanceId, `NavigableInstanceId` navigableInstanceId, int position, int alignment) Relocate the navigable (child book or page) instance to a new location on the parent book.
`public void` | `removeNavigable`(`CustomizationContext` customizationContext, `DesktopDefinitionId` desktopDefinitionId, `NavigableInstance` navigableInstance) Remove a navigable (child book or page) from the specified parent book.
`public void` | `setDefaultNavigable`(`CustomizationContext` customizationContext, `DesktopDefinitionId` desktopDefinitionId, `BookInstanceId` bookInstanceId, `NavigableInstanceId` navigableInstanceId) Set the default navigable (child book or book) on a the parent book.
`public `BookInstance`` | `updateBookInstance`(`CustomizationContext` customizationContext, `DesktopDefinitionId` desktopDefinitionId, `BookInstance` bookInstance) Update the persistent store for the supplied `BookInstance`.

## Method Detail

### addNavigable(CustomizationContext, DesktopDefinitionId, BookInstanceId, NavigableDefinitionId, int, int) Method

    public NavigableInstance addNavigable(CustomizationContext customizationContext,
                                          DesktopDefinitionId desktopDefinitionId,
                                          BookInstanceId bookInstanceId,
                                          NavigableDefinitionId navigableDefinitionId,
                                          int position,
                                          int align)
         throws RemoteException, ObjectNotFoundException, MissingDataException, NotEntitledException, IllegalDependencyException

Add a `NavigableDefinition` (BookDefinition or PageDefinition) to the supplied Book Instance. This is the method you want to call if you want to add a page to a book for a particular user or if you are an admin effect all user.

#### Parameters

customizationContext
  the desktop context to which this update applies.

desktopDefinitionId
  the book instance to add the navigable to.

bookInstanceId
  the navigable defintion id from which to create the instance.

navigableDefinitionId
  the position in the book (or menu) to insert this navigable (starts with 0)

position
  position the page from the left (top) or right (bottom)

#### Returns

the new Navigable (Page or Book) instance which was just created.

#### Exceptions

``RemoteException``
``ObjectNotFoundException``
  BookDefinitionId or the NavigableDefinition are bogus.
``MissingDataException``
  missing vital data in the NavigableDefinition.
``NotEntitledException``
  if the caller does not have the required permissions to delete this object.
``IllegalDependencyException``
  adding the Navigable to the BookInstance would cause a recursive dependancy

Related Topics

``CustomizationContext.setVisitorMode(boolean)``

### getBookInstance(CustomizationContext, BookInstanceId) Method

    public BookInstance getBookInstance(CustomizationContext customizationContext,
                                        BookInstanceId bookInstanceId)
         throws RemoteException

Getter for returning a `BookInstance` identified by the supplieed instance id.

#### Parameters

customizationContext
  customization information such as preferred locales and desktopInstanceId

bookInstanceId
  the unique id of the instace to return

#### Returns

a fully populated internationalized `BookInstance` objects if it exist, otherwisez null.

#### Exceptions

``RemoteException``

### getBookView(CustomizationContext, DesktopDefinitionId, BookInstanceId) Method

    public BookView getBookView(CustomizationContext customizationContext,
                                DesktopDefinitionId desktopDefinitionId,
                                BookInstanceId bookInstanceId)
         throws RemoteException

Getter for returning an immutable deep copy of a `BookView`. The `BookView` object, unlike the `BookDefinition` or the `BookInstance` objects contains a deep copy of all references to all child pages, books and so on. The `BookView` object however is immutable.

#### Parameters

customizationContext
  customization information such as preferred locales and desktopInstanceId returned.

desktopDefinitionId
  the unique instance id of the book.

#### Returns

an immutable deep copy BookView object if one exist, otherwise null.

#### Exceptions

``RemoteException``

Related Topics

``IBookDefinitionManager.getBookView(CustomizationContext, BookDefinitionId)``

### moveNavigable(CustomizationContext, DesktopDefinitionId, BookInstanceId, BookInstanceId, NavigableInstanceId, int, int) Method

    public NavigableInstance moveNavigable(CustomizationContext customizationContext,
                                           DesktopDefinitionId desktopDefinitionId,
                                           BookInstanceId fromParentBookInstanceId,
                                           BookInstanceId toParentBookInstanceId,
                                           NavigableInstanceId navigableInstanceId,
                                           int position,
                                           int alignment)
         throws RemoteException, ObjectNotFoundException, NotEntitledException, IllegalDependencyException

Relocate the navigable (child book or page) instance to a new location on the parent book.

#### Parameters

customizationContext
  the desktop context to which this update applies.

desktopDefinitionId
  the parent book instance id we are moving this navigable from.

fromParentBookInstanceId
  the parent book instance to move the navigable instance to.

toParentBookInstanceId
  the identifier identifying the instance to move.

navigableInstanceId
  the position in the book (or menu) to insert this navigable (starts with 0)

position
  position the page from the left (top) or right (bottom) reference the same book defnition.

#### Returns

a reference to the newly positioned navigableInstance

#### Exceptions

``RemoteException``
``ObjectNotFoundException``
  BookInstanceId or the NavigableInstanceId are bogus.
``NotEntitledException``
  if the caller does not have the required permissions to delete this object.
``IllegalDependencyException``
  if this move would cause an infinite loop condition

Related Topics

``CustomizationContext.setVisitorMode(boolean)``

### removeNavigable(CustomizationContext, DesktopDefinitionId, NavigableInstance) Method

    public void removeNavigable(CustomizationContext customizationContext,
                                DesktopDefinitionId desktopDefinitionId,
                                NavigableInstance navigableInstance)
         throws RemoteException, ObjectNotFoundException, MissingDataException, NotEntitledException

Remove a navigable (child book or page) from the specified parent book. This method does not delete the navigable it just removes it from the parent book.

#### Parameters

customizationContext
  the desktop context to which this update applies.

desktopDefinitionId
  the instance to be removed. reference the same book defnition.

#### Exceptions

``RemoteException``
``ObjectNotFoundException``
  BookInstanceId or the NavigableInstanceId are bogus.
``MissingDataException``
``NotEntitledException``
  if the caller does not have the required permissions to delete this object.

Related Topics

``CustomizationContext.setVisitorMode(boolean)``

### setDefaultNavigable(CustomizationContext, DesktopDefinitionId, BookInstanceId, NavigableInstanceId) Method

    public void setDefaultNavigable(CustomizationContext customizationContext,
                                    DesktopDefinitionId desktopDefinitionId,
                                    BookInstanceId bookInstanceId,
                                    NavigableInstanceId navigableInstanceId)
         throws RemoteException, ObjectNotFoundException, NotEntitledException

Set the default navigable (child book or book) on a the parent book.

#### Parameters

customizationContext
  the desktop context to which this update applies.

desktopDefinitionId
  the parent book instance to set the default on.

bookInstanceId
  the navigable instance id of the child page/book to become the default

#### Exceptions

``RemoteException``
``ObjectNotFoundException``
  BookInstanceId or the NavigableInstanceId are bogus.
``NotEntitledException``
  if the caller does not have the required permissions to delete this object.

### updateBookInstance(CustomizationContext, DesktopDefinitionId, BookInstance) Method

    public BookInstance updateBookInstance(CustomizationContext customizationContext,
                                           DesktopDefinitionId desktopDefinitionId,
                                           BookInstance bookInstance)
         throws RemoteException, ObjectNotFoundException, NotEntitledException

Update the persistent store for the supplied `BookInstance`. All attributes of the BookInstance are updated in persistent store.

#### Parameters

customizationContext
  the desktop context to which this update applies.

desktopDefinitionId
  the book instance containing all the new data. reference the same book defnition.

#### Exceptions

``RemoteException``
``ObjectNotFoundException``
  the BookInstanceId specified in the bookInstance is bogus.
``NotEntitledException``