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

public interface IBookDefinitionManager

This is the primary interface for performing persistent store operations on `BookDefinitions`. 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 preferred 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.

"Definitions" can be thought of as objects in the Library. Objects in the library are not associated to any one Desktop. In other words definitions can be placed on zero or more desktops and changes made in the Library (to the definitions) are cascaded down to object on the desktops. If you are only interested in affecting a single desktop then use the `PortalCustomizationManager` and make changes to the "Instances".

All Known Subinterfaces
  `BookDefinitionManager`

## Method Summary

`public `NavigableInstance`` | `addNavigable`(`CustomizationContext` customizationContext, `BookDefinitionId` bookDefinitionId, `NavigableDefinitionId` navigableDefinitionId, int position, int alignment, boolean isDefault) Add a Navigable definition (child BookDefinition or PageDefinition) to an existing parent BookDefinition.
`public `BookDefinition`` | `createBookDefinition`(`CustomizationContext` customizationContext, `BookDefinition` bookDefinition) Create a new book definition.
`public void` | `deleteBookDefinition`(`CustomizationContext` customizationContext, `BookDefinitionId` bookDefinitionId) Method for deleting a `BookDefinition` object given a supplied book definition identifier.
`public void` | `deleteBookDefinitionWithCascade`(`CustomizationContext` customizationContext, `BookDefinitionId` bookDefinitionId) Delete the `BookDefinition` of the supplied book definition identifier and all `BookInstance` objects associated with this book definition.
`public void` | `deleteBookDefinitionWithReplacement`(`CustomizationContext` customizationContext, `BookDefinitionId` deleteBookDefinitionId, `BookDefinitionId` replacementBookDefinitionId) Delete an existing book definition and if it is in use, replace it's use with the supplied book definition.
`public `BookDefinition`` | `getBookDefinition`(`CustomizationContext` customizationContext, `BookDefinitionId` bookDefinitionId) Getter for returning a single `BookDefinition` object given a supplied book definition identifier.
`public `BookDefinition`` | `getBookDefinition`(`CustomizationContext` customizationContext, `String` definitionLabel, `String` webAppName) Getter for returning a single `BookDefinition` object given a supplied book definition label.
`public `BookDefinition`[]` | `getBookDefinitions`(`CustomizationContext` customizationContext, `String` webapp) Getter for returning a list of all `BookDefinitions` scoped to the supplied webapp.
`public `BookDefinition`[]` | `getBookDefinitions`(`CustomizationContext` customizationContext, `String` webapp, `BookDefinitionId` firstBookDefinitionId, int limit) Returns `BookDefinition`s in `definitionId` order (create order).
`public `BookView`` | `getBookView`(`CustomizationContext` customizationContext, `BookDefinitionId` bookDefinitionId) Getter for returning an immutable deep copy of a `BookView`.
`public `BookDefinition`[]` | `getPublicBookDefinitions`(`CustomizationContext` customizationContext, `String` webapp, `BookDefinitionId` firstBookDefinitionId, int limit) Returns `BookDefinition`s in `definitionId` order (create order) scoped to the supplied webapp and marked as public.
`public `BookDefinition`[]` | `getPublicBookDefinitions`(`CustomizationContext` customizationContext, `String` webapp) Getter for returning a list of all `BookDefinitions` scoped to the supplied webapp and marked as public.
`public `BookDefinition`[]` | `getPublicBookDefinitions`(`CustomizationContext` customizationContext, `DesktopDefinitionId` desktopDefinitionId, `BookDefinitionId` firstBookDefinitionId, int limit) Returns `BookDefinition`s in `definitionId` order (create order) scoped to the supplied webapp and marked as public and not currently on the users desktop.
`public `BookDefinition`[]` | `getPublicBookDefinitions`(`CustomizationContext` customizationContext, `DesktopDefinitionId` desktopDefinitionId) Getter for returning a list of all `BookDefinitions` scoped to the supplied webapp and marked as public and not currently on the users desktop.
`public `BookDefinition`[]` | `getPublicBookDefinitions`(`CustomizationContext` customizationContext, `String` webapp, `BookDefinitionId` bookDefinitionId) Getter for returning a list of all `BookDefinitions` scoped to the supplied webapp and marked as public and not currently in the supplied book (bookDefinitionId).
`public `BookDefinition`[]` | `getPublicBookDefinitions`(`CustomizationContext` customizationContext, `String` webapp, `PageDefinitionId` pageDefinitionId) Getter for returning a list of all `BookDefinitions` scoped to the supplied webapp and marked as public and not currently in the supplied page (pageDefinitionId).
`public `NavigableDefinition`` | `moveNavigable`(`CustomizationContext` customizationContext, `DesktopDefinitionId` desktopDefinitionId, `BookDefinitionId` fromParentBookDefinitionId, `BookDefinitionId` toParentBookDefinitionId, `NavigableDefinitionId` navigableDefinitionId, int position, int alignment) Relocate the navigable definition to a new location.
`public void` | `removeNavigable`(`CustomizationContext` customizationContext, `BookGroupId` bookGroupId) Remove a NavigableDefinition (BookDefinition or PageDefinition) from the specified book.
`public `BookDefinition`[]` | `searchPublicBookDefinitions`(`CustomizationContext` customizationContext, `String` webapp, `String` partialBookTitle, int limit) Search for public books given the supplied search string.
`public void` | `setDefaultNavigable`(`CustomizationContext` customizationContext, `BookDefinitionId` parentBookDefinitionId, `NavigableDefinitionId` navigableDefinitionId) Set a navigable (book or page) on a parent page as the default page.
`public void` | `updateBookDefinition`(`CustomizationContext` customizationContext, `BookDefinition` bookDefintion) Update the persistent store for the supplied `BookDefinition`.

## Method Detail

### addNavigable(CustomizationContext, BookDefinitionId, NavigableDefinitionId, int, int, boolean) Method

    public NavigableInstance addNavigable(CustomizationContext customizationContext,
                                          BookDefinitionId bookDefinitionId,
                                          NavigableDefinitionId navigableDefinitionId,
                                          int position,
                                          int alignment,
                                          boolean isDefault)
         throws RemoteException, ObjectNotFoundException, NotEntitledException, IllegalDependencyException, DuplicateObjectException

Add a Navigable definition (child BookDefinition or PageDefinition) to an existing parent BookDefinition.

#### Parameters

customizationContext
  customization information such as prefered locales and desktopInstanceId

bookDefinitionId
  the book definition to add the navigable to.

navigableDefinitionId
  the definition id of the navigable definition from which to add.

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

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

#### Returns

the Navigable instance which was created.

#### Exceptions

``RemoteException``
``ObjectNotFoundException``
  BookDefinitionId or the NavigableDefinitionId are bogus.
``NotEntitledException``
  if the caller does not have the required permissions to delete this object.
``IllegalDependencyException``
  adding the Navigable to the BookDefinition would cause a recursive dependancy
``DuplicateObjectException``
  if this navigable is already added to this book

Related Topics

``BookView.ALIGNMENT_LEFT``
``BookView.ALIGNMENT_RIGHT``

### createBookDefinition(CustomizationContext, BookDefinition) Method

    public BookDefinition createBookDefinition(CustomizationContext customizationContext,
                                               BookDefinition bookDefinition)
         throws RemoteException, MissingDataException, NotEntitledException

Create a new book definition. Creates a new book definition in the persistent store. This definition may be used to create book instance later on.

#### Parameters

customizationContext
  customization information such as prefered locales and desktopInstanceId

bookDefinition
  the book definition object containing all the required data.

#### Returns

the fully populated BookDefinition object (with id's).

#### Exceptions

``RemoteException``
``MissingDataException``
  if some vital information is missing from the BookDefinition.
``NotEntitledException``
  if the caller does not have the required permissions to delete this object.

### deleteBookDefinition(CustomizationContext, BookDefinitionId) Method

    public void deleteBookDefinition(CustomizationContext customizationContext,
                                     BookDefinitionId bookDefinitionId)
         throws RemoteException, ObjectNotFoundException, ObjectInUseException, NotEntitledException

Method for deleting a `BookDefinition` object given a supplied book definition identifier. If the BookDefinition is in use by clients then a `ObjectInUseFound` exception is thrown.

#### Parameters

customizationContext
  customization information such as prefered locales and desktopInstanceId

bookDefinitionId
  the unique book definition identifier.

#### Exceptions

``RemoteException``
``ObjectNotFoundException``
  if the bookDefinitionId is bogus.
``ObjectInUseException``
  if the book definition is in use by end users.
``NotEntitledException``
  no entitlements for this operation.

Related Topics

``BookDefinition``

### deleteBookDefinitionWithCascade(CustomizationContext, BookDefinitionId) Method

    public void deleteBookDefinitionWithCascade(CustomizationContext customizationContext,
                                                BookDefinitionId bookDefinitionId)
         throws RemoteException, ObjectNotFoundException, NotEntitledException, ObjectInUseException

Delete the `BookDefinition` of the supplied book definition identifier and all `BookInstance` objects associated with this book definition. While this method will cascade delete all the user's and admin's customizations it will complain (`ObjectInUseException`) if the definition is the primary book of a desktop. In that case you may want to try deleteBookDefinitionWithReplacement().

#### Parameters

customizationContext
  customization information such as prefered locales and desktopInstanceId

bookDefinitionId
  the unique book definition identifier of the book to delete.

#### Exceptions

``RemoteException``
``ObjectNotFoundException``
  if there is no BookDefinition associated with bookDefinitionId.
``NotEntitledException``
  if the caller does not have the required permissions to delete this object.
``ObjectInUseException``
  if the book definition is the main book on a desktop.

### deleteBookDefinitionWithReplacement(CustomizationContext, BookDefinitionId, BookDefinitionId) Method

    public void deleteBookDefinitionWithReplacement(CustomizationContext customizationContext,
                                                    BookDefinitionId deleteBookDefinitionId,
                                                    BookDefinitionId replacementBookDefinitionId)
         throws RemoteException, ObjectNotFoundException, NotEntitledException

Delete an existing book definition and if it is in use, replace it's use with the supplied book definition.

Note all customization of the deleted book will be lost.

#### Parameters

customizationContext
  customization information such as prefered locales and desktopInstanceId

deleteBookDefinitionId
  the definition id of the book to delete

replacementBookDefinitionId
  the definition id of the book to replace the deleted book.

#### Exceptions

``RemoteException``
``ObjectNotFoundException``
  if the bookDefinitionId is bogus.
``NotEntitledException``
  no entitlements for this operation.

Related Topics

``BookDefinition``

### getBookDefinition(CustomizationContext, BookDefinitionId) Method

    public BookDefinition getBookDefinition(CustomizationContext customizationContext,
                                            BookDefinitionId bookDefinitionId)
         throws RemoteException

Getter for returning a single `BookDefinition` object given a supplied book definition identifier.

#### Parameters

customizationContext
  customization information such as prefered locales and desktopInstanceId

bookDefinitionId
  the unique book definition identifier.

#### Returns

a `BookDefinition` object fully populated and internationalized, otherwise, `null>/code> if the object does not exist.`

#### Exceptions

``RemoteException``

Related Topics

``BookDefinition``

### getBookDefinition(CustomizationContext, String, String) Method

    public BookDefinition getBookDefinition(CustomizationContext customizationContext,
                                            String definitionLabel,
                                            String webAppName)
         throws RemoteException

Getter for returning a single `BookDefinition` object given a supplied book definition label.

#### Parameters

customizationContext
  customization information such as prefered locales and desktopInstanceId

definitionLabel
  the unique book definition identifier.

webAppName
  the webapp this book is scoped to.

#### Returns

a `BookDefinition` object fully populated and internationalized, otherwise, `null>/code> if the object does not exist.`

#### Exceptions

``RemoteException``

Related Topics

``BookDefinition``

### getBookDefinitions(CustomizationContext, String) Method

    public BookDefinition[] getBookDefinitions(CustomizationContext customizationContext,
                                             String webapp)
         throws RemoteException

Getter for returning a list of all `BookDefinitions` scoped to the supplied webapp.

#### Parameters

customizationContext
  customization information such as prefered locales and desktopInstanceId

webapp
  the web application these book definitions are scoped to.

#### Returns

an array of `BookDefinition` objects if they exist, otherwise, an empty array.

#### Exceptions

``RemoteException``

Related Topics

``BookDefinition``

### getBookDefinitions(CustomizationContext, String, BookDefinitionId, int) Method

    public BookDefinition[] getBookDefinitions(CustomizationContext customizationContext,
                                             String webapp,
                                             BookDefinitionId firstBookDefinitionId,
                                             int limit)
         throws RemoteException

Returns `BookDefinition`s in `definitionId` order (create order). Starting with the supplied definitionId and limiting the result set to size `limit`. If fewer `BookDefinition`s exist than `limit`, then a smaller result set will be returned. If no definitions are found an empty array is returned. To start at the beginning of the list specify `null` as the `bookDefinitionId`. To retrieve from the end of the list and back specify `null` as the `bookDefinitionId` and a negative `limit`. To retrieve all the bookDefinitions in the database supply a limit of 0.
Implementation has to ensure that repeated calls to this method return `BookDefinition`s in a consistent order.

#### Parameters

customizationContext
  customization information such as preferred locales.

webapp
  the web application these book definitions are scoped to.

firstBookDefinitionId
  optional parameter to indicate where the list should start.

limit
  the maximum result set size. Note the limit may be negative indicating a reverse sort order. For all the records specify a limit of zero. Note: some elements may be pruned because of entitlements.

#### Returns

array of `BookDefinition`s no greater than `limit` in size.

#### Exceptions

``RemoteException``

### getBookView(CustomizationContext, BookDefinitionId) Method

    public BookView getBookView(CustomizationContext customizationContext,
                                BookDefinitionId bookDefinitionId)
         throws RemoteException

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

#### Parameters

customizationContext
  customization information such as prefered locales and http request.

bookDefinitionId
  the unique bookDefinitionId.

#### Returns

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

#### Exceptions

``RemoteException``

Related Topics

``IBookInstanceManager.getBookView(CustomizationContext, DesktopDefinitionId, BookInstanceId)``

### getPublicBookDefinitions(CustomizationContext, String, BookDefinitionId, int) Method

    public BookDefinition[] getPublicBookDefinitions(CustomizationContext customizationContext,
                                                   String webapp,
                                                   BookDefinitionId firstBookDefinitionId,
                                                   int limit)
         throws RemoteException

Returns `BookDefinition`s in `definitionId` order (create order) scoped to the supplied webapp and marked as public. Starting with the supplied definitionId and limiting the result set to size `limit`. If fewer `BookDefinition`s exist than `limit`, then a smaller result set will be returned. If no definitions are found an empty array is returned. To start at the beginning of the list specify `null` as the `bookDefinitionId`. To retrieve from the end of the list and back specify `null` as the `bookDefinitionId` and a negative `limit`. To retrieve all the bookDefinitions in the database supply a limit of 0.
Implementation has to ensure that repeated calls to this method return `BookDefinition`s in a consistent order.

#### Parameters

customizationContext
  customization information such as preferred locales.

webapp
  the web application these book definitions are scoped to.

firstBookDefinitionId
  optional parameter to indicate where the list should start.

limit
  the maximum result set size. Note the limit may be negative indicating a reverse sort order. For all the records specify a limit of zero. Note: some elements may be pruned because of entitlements.

#### Returns

array of `BookDefinition`s no greater than `limit` in size.

#### Exceptions

``RemoteException``

### getPublicBookDefinitions(CustomizationContext, String) Method

    public BookDefinition[] getPublicBookDefinitions(CustomizationContext customizationContext,
                                                   String webapp)
         throws RemoteException

Getter for returning a list of all `BookDefinitions` scoped to the supplied webapp and marked as public.

#### Parameters

customizationContext
  customization information such as prefered locales and desktopInstanceId

webapp
  the web application these book definitions are scoped to.

#### Returns

an array of fully populated and internationalized `BookDefinition` objects if they exist, otherwise, an empty array.

#### Exceptions

``RemoteException``

Related Topics

``BookDefinition``

### getPublicBookDefinitions(CustomizationContext, DesktopDefinitionId, BookDefinitionId, int) Method

    public BookDefinition[] getPublicBookDefinitions(CustomizationContext customizationContext,
                                                   DesktopDefinitionId desktopDefinitionId,
                                                   BookDefinitionId firstBookDefinitionId,
                                                   int limit)
         throws RemoteException

Returns `BookDefinition`s in `definitionId` order (create order) scoped to the supplied webapp and marked as public and not currently on the users desktop. Starting with the supplied definitionId and limiting the result set to size `limit`. If fewer `BookDefinition`s exist than `limit`, then a smaller result set will be returned. If no definitions are found an empty array is returned. To start at the beginning of the list specify `null` as the `bookDefinitionId`. To retrieve from the end of the list and back specify `null` as the `bookDefinitionId` and a negative `limit`. To retrieve all the bookDefinitions in the database supply a limit of 0.
Implementation has to ensure that repeated calls to this method return `BookDefinition`s in a consistent order.

#### Parameters

customizationContext
  customization information such as prefered locales

desktopDefinitionId
  you wish to add any of these book definitions to.

firstBookDefinitionId
  optional parameter to indicate where the list should start.

limit
  the maximum result set size. Note the limit may be negative indicating a reverse sort order. For all the records specify a limit of zero.

#### Returns

an array of fully populated and internationalized `BookDefinition` objects if they exist, otherwise, an empty array.

#### Exceptions

``RemoteException``

Related Topics

``BookDefinition``

### getPublicBookDefinitions(CustomizationContext, DesktopDefinitionId) Method

    public BookDefinition[] getPublicBookDefinitions(CustomizationContext customizationContext,
                                                   DesktopDefinitionId desktopDefinitionId)
         throws RemoteException

Getter for returning a list of all `BookDefinitions` scoped to the supplied webapp and marked as public and not currently on the users desktop.

#### Parameters

customizationContext
  customization information such as prefered locales and desktopInstanceId

desktopDefinitionId
  you wish to add any of these book definitions to.

#### Returns

an array of fully populated and internationalized `BookDefinition` objects if they exist, otherwise, an empty array.

#### Exceptions

``RemoteException``

Related Topics

``BookDefinition``

### getPublicBookDefinitions(CustomizationContext, String, BookDefinitionId) Method

    public BookDefinition[] getPublicBookDefinitions(CustomizationContext customizationContext,
                                                   String webapp,
                                                   BookDefinitionId bookDefinitionId)
         throws RemoteException

Getter for returning a list of all `BookDefinitions` scoped to the supplied webapp and marked as public and not currently in the supplied book (bookDefinitionId).

#### Parameters

customizationContext
  customization information such as prefered locales and desktopInstanceId

webapp
  the web application these book definitions are scoped to.

bookDefinitionId
  you wish to add any of these book definitions to.

#### Returns

an array of fully populated and internationalized `BookDefinition` objects if they exist, otherwise, an empty array.

#### Exceptions

``RemoteException``

Related Topics

``BookDefinition``

### getPublicBookDefinitions(CustomizationContext, String, PageDefinitionId) Method

    public BookDefinition[] getPublicBookDefinitions(CustomizationContext customizationContext,
                                                   String webapp,
                                                   PageDefinitionId pageDefinitionId)
         throws RemoteException

Getter for returning a list of all `BookDefinitions` scoped to the supplied webapp and marked as public and not currently in the supplied page (pageDefinitionId).

#### Parameters

customizationContext
  customization information such as prefered locales and desktopInstanceId

webapp
  the web application these book definitions are scoped to.

pageDefinitionId
  you wish to add any of these book definitions to.

#### Returns

an array of fully populated and internationalized `BookDefinition` objects if they exist, otherwise, an empty array.

#### Exceptions

``RemoteException``

Related Topics

``BookDefinition``

### moveNavigable(CustomizationContext, DesktopDefinitionId, BookDefinitionId, BookDefinitionId, NavigableDefinitionId, int, int) Method

    public NavigableDefinition moveNavigable(CustomizationContext customizationContext,
                                             DesktopDefinitionId desktopDefinitionId,
                                             BookDefinitionId fromParentBookDefinitionId,
                                             BookDefinitionId toParentBookDefinitionId,
                                             NavigableDefinitionId navigableDefinitionId,
                                             int position,
                                             int alignment)
         throws RemoteException, ObjectNotFoundException, NotEntitledException

Relocate the navigable definition to a new location.

#### Parameters

customizationContext
  the desktop context to which this update applies.

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

fromParentBookDefinitionId
  the parent book definition to move the navigable definition to.

toParentBookDefinitionId
  the identifier identifying the definition to move.

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) reference the same book defnition.

#### Returns

a reference to the newly positioned navigableDefinition

#### Exceptions

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

### removeNavigable(CustomizationContext, BookGroupId) Method

    public void removeNavigable(CustomizationContext customizationContext,
                                BookGroupId bookGroupId)
         throws RemoteException, ObjectNotFoundException, NotEntitledException

Remove a NavigableDefinition (BookDefinition or PageDefinition) from the specified book. This method does not delete the NavigableDefintion it just removes it from the book.

#### Parameters

customizationContext
  the book group id of the navigable to be removed.

#### Exceptions

``RemoteException``
``ObjectNotFoundException``
  if the navigable or book definition could not be found in persistent store.
``NotEntitledException``
  if the caller does not have the required permissions to delete this object.

### searchPublicBookDefinitions(CustomizationContext, String, String, int) Method

    public BookDefinition[] searchPublicBookDefinitions(CustomizationContext customizationContext,
                                                      String webapp,
                                                      String partialBookTitle,
                                                      int limit)
         throws RemoteException

Search for public books given the supplied search string. Books with `titles` matching the supplied pattern will be returned. No more than `limit` results will be returned; however a smaller number may be returned. Implementation has to ensure that repeated calls to this method return `BookDefinition`s in a consistent order.

#### Parameters

customizationContext
  customization information such as preferred locales.

webapp
  the web application these book definitions are scoped to.

partialBookTitle
  the search string for book title match. Note: this string may contain special '*' and '?' characters, where '*' matches any characters and '?' matches any single character.

limit
  the maximum result set size. Note the limit may be negative indicating a reverse sort order. For all the records specify a limit of zero. Note: some elements may be pruned because of entitlements.

#### Returns

array of `BookDefinition`s no greater than `limit` in size.

#### Exceptions

``RemoteException``

### setDefaultNavigable(CustomizationContext, BookDefinitionId, NavigableDefinitionId) Method

    public void setDefaultNavigable(CustomizationContext customizationContext,
                                    BookDefinitionId parentBookDefinitionId,
                                    NavigableDefinitionId navigableDefinitionId)
         throws RemoteException, ObjectNotFoundException, NotEntitledException

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

#### Parameters

customizationContext
  the book definition id of the parent book

parentBookDefinitionId
  the child book or page definition id to become the new defualt page

#### Exceptions

``RemoteException``
``ObjectNotFoundException``
  if the navigable or book definition could not be found in persistent store.
``NotEntitledException``
  if the caller does not have the required permissions to delete this object.

### updateBookDefinition(CustomizationContext, BookDefinition) Method

    public void updateBookDefinition(CustomizationContext customizationContext,
                                     BookDefinition bookDefintion)
         throws RemoteException, ObjectNotFoundException, NotEntitledException

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

#### Parameters

customizationContext
  customization information such as prefered locales and desktopInstanceId

bookDefintion
  the object containing the new data for the book definition.

#### Exceptions

``RemoteException``
``ObjectNotFoundException``
  the `BookDefinitionId`
``NotEntitledException``
  if the caller does not have the required permissions to delete this object.