oracle.portal.provider.v1
Class DBPersonalizationManager

java.lang.Object
  |
  +--oracle.portal.provider.v1.DBPersonalizationManager

public class DBPersonalizationManager

extends java.lang.Object

implements PortletPersonalizationManager

The DBPersonalizationManager class implements a PortletPersonalizationManager using data objects to persist customized data in a database.

The class of the data objects managed by a DBPersonalizationManager is registered using setDataClass(String). Most commonly this will be the result of a declaration in the provider XML registry (e.g. <dataClass>className</dataClass>). If your data class implements the PersonalizationObject interface (recommended), it will be responsible for reading and writing its own content through its read() and write() methods. Otherwise, it is assumed that the data class implements the Serializable interface, and can therefore be saved and restored through Java serialization. For maximum extensibility, it is recommended that you use NameValuePersonalizationObject as a basis for your data class.

The persisted data is stored in a database table; one row per customization. Connections to the database are retrieved from a 'pool', managed by ConnectionManager; therefore, you must ensure that you have set up a configuration file for ConnectionManager and that your JVM knows its whereabouts. The name of the pooled connection to be used must be registered with a call to setConnection(String), or through a <connection>connectionName</connection> declaration.

The name of the database table to be used to store customizations defaults to JPDK_PREFERENCE_STORE, but can be overriden with a call to setTable(String), or through a <table>TABLE_NAME</table> declaration. A table with this default name can be installed on a database connection using the script in providers/dbPersonalization/jpdk_preference_store.sql. If a table of a different name is to be used, it must conform to the same design.

Constructor Summary

DBPersonalizationManager()
Null Constructor

Method Summary

void	copy(PortletReference from, PortletReference to, ProviderUser user) Copies the instance customizations from one reference to another.
void	create(PortletReference ref, java.lang.Object o, ProviderUser user) Creates the initial personalization reference for this (new) PortletReference.
void	create(PortletReference ref, ProviderUser user) Creates the initial personalization reference for this (new) PortletReference and establishes its (static) defaults.
void	destroy(Portlet p) Called to allow the Portlet Personalization manager to destroy its repository.
void	destroy(PortletReference ref, ProviderUser user) Destroys a given Portlet instance from the repository by reference.
boolean	exists(PortletReference ref, ProviderUser user) Returns true if a customization exists for this given reference.
void	init(Portlet p) Initializes the repository for this DBPersonalizationManager.
void	initInstance(Portlet p) Initializes a new DBPersonalizationManager instance.
java.lang.Object	read(PortletReference ref, ProviderUser user) Returns a data object containing the customizations particular to this reference.
void	setConnection(java.lang.String connection) Sets the name of the connection pool, managed by ConnectionManager from which this DBPersonalizationManager should retrieve its database connections.
void	setDataClass(java.lang.String className) Sets the class name of the data objects this instance manages.
void	setTable(java.lang.String tableName) Sets the name of the database table in which this DBPersonalizationManager should store customization data.
void	write(PortletReference ref, java.lang.Object o, ProviderUser user) Updates this reference's customization using the passed data object.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DBPersonalizationManager

public DBPersonalizationManager()
                         throws ConnectionManagerException

Null Constructor

Method Detail

setDataClass

public void setDataClass(java.lang.String className)
                  throws PersonalizationException

Sets the class name of the data objects this instance manages. This class must implement PersonalizationObject or Serializable. It is recommended that you subclass your data object from NameValuePersonalizationObject.

Parameters:

className - the class name for that class that represents the data to be managed.

setConnection

public void setConnection(java.lang.String connection)
                   throws PersonalizationException

Sets the name of the connection pool, managed by ConnectionManager from which this DBPersonalizationManager should retrieve its database connections.

Parameters:

connection - a connection pool name

Throws:

PersonalizationException - if a connection pool of the given name cannot be initialized by ConnectionManager

setTable

public void setTable(java.lang.String tableName)

Sets the name of the database table in which this DBPersonalizationManager should store customization data. If not set explicitly, the default name is "JPDK_PREFERENCE_STORE".

Parameters:

tableName - name of the database table storing customization data

initInstance

public void initInstance(Portlet p)

Initializes a new DBPersonalizationManager instance. This method should be invoked on each of a Provider's PortletPersonalizationManagers whenever the Provider instance is initialized on startup (by the Provider's init() method).

The DBPersonalizationManager currently does nothing in response to this call.

Specified by:

initInstance in interface PortletPersonalizationManager

Parameters:

p - the portlet this DBPersonalizationManager is controlling.

init

public void init(Portlet p)

Initializes the repository for this DBPersonalizationManager. This method is invoked on each of a Provider's PortletPersonalizationManagers whenever the Provider is registered on a Portal Node (when the Provider's register() method is called). This gives the personalization manager an opportunity to initialize the repository for the corresponding Portlet.

The DBPersonalizationManager currently does nothing in response to this call.

Specified by:

init in interface PortletPersonalizationManager

Parameters:

p - the portlet this DBPersonalizationManager is controlling.

destroy

public void destroy(Portlet p)
             throws AccessControlException,
                    java.io.IOException

Called to allow the Portlet Personalization manager to destroy its repository. This method is called each time a Provider that manages this PortletPersonalizationManager's Portlet is deregistered (from a portal).

In response to this call, the DBPersonalizationManager removes all rows from the database table that pertain to this Portlet.

Specified by:

destroy in interface PortletPersonalizationManager

Parameters:

p - the portlet this PortletPersonalizationManager is controlling.

create

public void create(PortletReference ref,
                   ProviderUser user)
            throws java.io.IOException,
                   PortletAlreadyExistsException,
                   AccessControlException

Creates the initial personalization reference for this (new) PortletReference and establishes its (static) defaults.

In response to this call, the DBPersonalizationManager creates a new instance of the data object class that is registered to it, and calls its init() method if the class implements PersonalizationObject or CustomizationObject. Finally, a default row for the instance is created in the database table, ensuring the initial data persists.

Specified by:

create in interface PortletPersonalizationManager

Parameters:

ref - the PortletReference. The details of the PortletReference determine whether this creates the default, system instance or a specific user instance.

user - the user attempting this operation. The manager is expected to authorize the user before completing this operation.

create

public void create(PortletReference ref,
                   java.lang.Object o,
                   ProviderUser user)
            throws PortletAlreadyExistsException,
                   AccessControlException,
                   java.io.IOException

Creates the initial personalization reference for this (new) PortletReference. The initial data object representing this new instance is passed as a parameter.

In response to this call, the DBPersonalizationManager saves the passed object to a row in the database table, ensuring the initial data persists.

Specified by:

create in interface PortletPersonalizationManager

Parameters:

ref - the PortletReference. The details of the PortletReference determine whether this creates the default, system instance or a specific user instance.

o - the Object representing the initial values for this instance (should implement PersonalizationObject or Serializable).

user - the user attempting this operation. The manager is expected to authorize the user before completing this operation.

exists

public boolean exists(PortletReference ref,
                      ProviderUser user)
               throws AccessControlException

Returns true if a customization exists for this given reference. This will be true if a create() has been previously called.

Specified by:

exists in interface PortletPersonalizationManager

Parameters:

ref - the portlet instance to check

user - the user making this request -- passed to give the manager access the the session.

read

public java.lang.Object read(PortletReference ref,
                             ProviderUser user)
                      throws PortletNotFoundException,
                             AccessControlException,
                             java.io.IOException

Returns a data object containing the customizations particular to this reference. If no customizations exist then the PortletNotFoundException is thrown.

Specified by:

read in interface PortletPersonalizationManager

Parameters:

ref - the portlet reference that identifies the instance whose customizations are being requested.

user - the user attempting this operation. The manager is expected to authorize the user before completing this operation.

Returns:

an Object (of the class specified with setDataClass) containing the customizations particular to this reference

Throws:

PortletNotFoundException - if no customizations exist

write

public void write(PortletReference ref,
                  java.lang.Object o,
                  ProviderUser user)
           throws java.io.IOException,
                  PortletNotFoundException,
                  AccessControlException

Updates this reference's customization using the passed data object.

Specified by:

write in interface PortletPersonalizationManager

Parameters:

ref - the portlet reference that identifies the instance whose customizations are being updated.

o - the data object containing the new values (should implement PersonalizationObject or Serializable).

user - the user attempting this operation. The manager is expected to authorize the user before completing this operation.

destroy

public void destroy(PortletReference ref,
                    ProviderUser user)
             throws PortletNotFoundException,
                    AccessControlException,
                    java.io.IOException

Destroys a given Portlet instance from the repository by reference. If the reference refers to the system (default) instance the manager should additionally delete all user customizations that correspond.

Specified by:

destroy in interface PortletPersonalizationManager

Parameters:

ref - the portlet reference that identifies the instance whose customizations are being deleted.

user - the user attempting this operation. The manager is expected to authorize the user before completing this operation.

copy

public void copy(PortletReference from,
                 PortletReference to,
                 ProviderUser user)
          throws PortletNotFoundException,
                 AccessControlException,
                 java.io.IOException

Copies the instance customizations from one reference to another. If the reference refers to the system (default) instance the manager should additionally copy any other corresponding default customizations for different locales. If the customization for the to reference doesn't exist it is created else the current values are overwritten.

Specified by:

copy in interface PortletPersonalizationManager

Parameters:

from - reference for the portlet instance we are copying from.

to - reference for the portlet instance we are copying to.

user - the user attempting this operation. The manager is expected to authorize the user before completing this operation.