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

public interface IShellDefinitionManager

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

"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 effecting a single desktop then use the `PortalCustomizationManager` and make changes to the "Instances".

All Known Subinterfaces
  `ShellDefinitionManager`

## Method Summary

`public `ShellDefinition`` | `createShellDefinition`(`CustomizationContext` customizationContext, `ShellDefinition` shellDefinition) Creates a new ShellView Definition with its placeholders.
`public void` | `deleteShellDefinition`(`CustomizationContext` customizationContext, `ShellDefinitionId` shellDefinitionId) Delete a shell definition.
`public void` | `deleteShellDefinitionWithReplacement`(`CustomizationContext` customizationContext, `ShellDefinitionId` deleteShellDefinitionId, `ShellDefinitionId` replacementShellDefinitionId) Delete a shell definition and replace any uses of that shell with a replacement shell.
`public `ShellDefinition`` | `getShellDefinition`(`CustomizationContext` customizationContext, `ShellDefinitionId` shellDefinitionId) Getter for returning a single `ShellDefinition` object given a supplied shell definition identifier.
`public `ShellDefinition`` | `getShellDefinitionFromFile`(`CustomizationContext` customizationContext, `String` shellFile, `String` webAppName) Return a shel definition with the shellFile equal to the supplied filePath.
`public `ShellDefinitionId`` | `getShellDefinitionId`(`CustomizationContext` customizationContext, `String` markupName, `String` webAppName) Getter for returning a single `ShellDefinitionId` object given a supplied shell markup name.
`public `ShellDefinition`[]` | `getShellDefinitions`(`CustomizationContext` customizationContext, `String` webapp) Getter for returning a list of all `ShellDefinitions` scoped to the supplied webapp.
`public `ShellDefinition`[]` | `getShellDefinitions`(`CustomizationContext` customizationContext, `String` webapp, `ShellDefinitionId` firstShellDefinitionId, int limit) Returns `ShellDefinition`s in `definitionId` order (create order).
`public `ShellView`` | `getShellView`(`CustomizationContext` customizationContext, `ShellDefinitionId` shellDefinitionId) Getter for returning an immutable deep copy of a `ShellView`.
`public void` | `updateShellDefinition`(`CustomizationContext` customizationContext, `ShellDefinition` shellDefinition) Update the shell definition with the new data.

## Method Detail

### createShellDefinition(CustomizationContext, ShellDefinition) Method

    public ShellDefinition createShellDefinition(CustomizationContext customizationContext,
                                                 ShellDefinition shellDefinition)
         throws MissingDataException, NotEntitledException, RemoteException

Creates a new ShellView Definition with its placeholders.

#### Parameters

customizationContext
  customization information such as prefered locales and desktopInstanceId returned.

shellDefinition
  the shell data and associated placeholders

#### Returns

a fully populated ShellDefinition

#### Exceptions

``MissingDataException``
  the shellDefiniiton supplied as an argument is missing some vital data.
``NotEntitledException``
``RemoteException``

### deleteShellDefinition(CustomizationContext, ShellDefinitionId) Method

    public void deleteShellDefinition(CustomizationContext customizationContext,
                                      ShellDefinitionId shellDefinitionId)
         throws ObjectNotFoundException, ObjectInUseException, NotEntitledException, RemoteException

Delete a shell definition.

#### Parameters

customizationContext
  customization information such as prefered locales and desktopInstanceId returned.

shellDefinitionId
  the id of the shell definition to delete.

#### Exceptions

``ObjectNotFoundException``
  if the shellDefinitionId is bogus
``ObjectInUseException``
  if page instances are currently using this shell
``NotEntitledException``
  the caller is not entitled to perform this operation.
``RemoteException``

Related Topics

``IShellDefinitionManager.deleteShellDefinitionWithReplacement(CustomizationContext, ShellDefinitionId, ShellDefinitionId)``

### deleteShellDefinitionWithReplacement(CustomizationContext, ShellDefinitionId, ShellDefinitionId) Method

    public void deleteShellDefinitionWithReplacement(CustomizationContext customizationContext,
                                                     ShellDefinitionId deleteShellDefinitionId,
                                                     ShellDefinitionId replacementShellDefinitionId)
         throws ObjectNotFoundException, NotEntitledException, RemoteException

Delete a shell definition and replace any uses of that shell with a replacement shell. This method is useful for deleting a shell that is in use by book instances and not having to delete those book instances.

#### Parameters

customizationContext
  customization information such as prefered locales and desktopInstanceId returned.

deleteShellDefinitionId
  the id of the shell definition to delete.

replacementShellDefinitionId
  the id of the replacement shell

#### Exceptions

``ObjectNotFoundException``
  if either of the shellDefinitionIds are bogus
``NotEntitledException``
  the caller is not entitled to perform this operation.
``RemoteException``

Related Topics

``IShellDefinitionManager.deleteShellDefinition(CustomizationContext, ShellDefinitionId)``

### getShellDefinition(CustomizationContext, ShellDefinitionId) Method

    public ShellDefinition getShellDefinition(CustomizationContext customizationContext,
                                              ShellDefinitionId shellDefinitionId)
         throws RemoteException

Getter for returning a single `ShellDefinition` object given a supplied shell definition identifier.

#### Parameters

customizationContext
  customization information such as prefered locales and desktopInstanceId returned.

shellDefinitionId
  the unique shell definition identifier.

#### Returns

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

#### Exceptions

``RemoteException``

Related Topics

``ShellDefinition``

### getShellDefinitionFromFile(CustomizationContext, String, String) Method

    public ShellDefinition getShellDefinitionFromFile(CustomizationContext customizationContext,
                                                      String shellFile,
                                                      String webAppName)
         throws RemoteException

Return a shel definition with the shellFile equal to the supplied filePath. The `webAppName` name is the deployed name of the module, and is often the name of the WAR file or directory, although this is not always the case. This name is that name given in config.xml as the Name of the WebAppComponent element (and thus WebAppComponentMBean's Name attribute). Note that this name is not the name of the URL context root.

#### Exceptions

``RemoteException``

### getShellDefinitionId(CustomizationContext, String, String) Method

    public ShellDefinitionId getShellDefinitionId(CustomizationContext customizationContext,
                                                  String markupName,
                                                  String webAppName)
         throws RemoteException

Getter for returning a single `ShellDefinitionId` object given a supplied shell markup name.

#### Parameters

customizationContext
  customization information such as prefered locales and desktopInstanceId.

markupName
  the markup name attribute supplied on the tag,

webAppName
  as defined in the config.xml

#### Returns

shellDefinitionId the unique shell definition identifier or null if none exist.

#### Exceptions

``RemoteException``

### getShellDefinitions(CustomizationContext, String) Method

    public ShellDefinition[] getShellDefinitions(CustomizationContext customizationContext,
                                               String webapp)
         throws RemoteException

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

#### Parameters

customizationContext
  customization information such as prefered locales and desktopInstanceId returned.

webapp
  the web application these shell definitions are scoped to.

#### Returns

an array of ShellDinfition objects if they exist, otherwise, an empty array.

#### Exceptions

``RemoteException``

Related Topics

``ShellDefinition``

### getShellDefinitions(CustomizationContext, String, ShellDefinitionId, int) Method

    public ShellDefinition[] getShellDefinitions(CustomizationContext customizationContext,
                                               String webapp,
                                               ShellDefinitionId firstShellDefinitionId,
                                               int limit)
         throws RemoteException

Returns `ShellDefinition`s in `definitionId` order (create order). Starting with the supplied definitionId and limiting the result set to size `limit` If fewer `ShellDefinition`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 `shellDefinitionId`. To retrieve from the end of the list and back specify `null` as the `shellDefinitionId` and a negative `limit`. To retrieve all the shellDefinitions in the database supply a limit of 0. Implementation has to ensure that repeated calls to this method return `ShellDefinition`s in a consistent order.

#### Parameters

customizationContext
  customization information such as preferred locales.

webapp
  the web application these shell definitions are scoped to.

firstShellDefinitionId
  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 `ShellDefinition`s no greater than `limit` in size.

#### Exceptions

``RemoteException``

### getShellView(CustomizationContext, ShellDefinitionId) Method

    public ShellView getShellView(CustomizationContext customizationContext,
                                  ShellDefinitionId shellDefinitionId)
         throws RemoteException

Getter for returning an immutable deep copy of a `ShellView`. The `ShellView` object, unlike the `ShellDefinition` or the `ShellInstance` objects contains a full set of references to all child pages, shells and so on. The `ShellView` object however is immutable.

#### Parameters

customizationContext
  customization information such as prefered locales and desktopInstanceId returned.

shellDefinitionId
  the unique shellDefinitionId.

#### Returns

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

#### Exceptions

``RemoteException``

### updateShellDefinition(CustomizationContext, ShellDefinition) Method

    public void updateShellDefinition(CustomizationContext customizationContext,
                                      ShellDefinition shellDefinition)
         throws ObjectNotFoundException, NotEntitledException, RemoteException

Update the shell definition with the new data.

#### Parameters

customizationContext
  customization information such as prefered locales and desktopInstanceId returned.

shellDefinition
  the shell definition containing the new data

#### Exceptions

``ObjectNotFoundException``
  if the LocalizationIntersectionId in the LocalizationResource is bogus.
``NotEntitledException``
``RemoteException``