oracle.portal.provider.v2.personalize
Class PortletPersonalizationManager

java.lang.Object
  oracle.portal.provider.v2.personalize.PortletPersonalizationManager

All Implemented Interfaces:

Validateable

Direct Known Subclasses:

DBPersonalizationManager, PrefStorePersonalizationManager

public abstract class PortletPersonalizationManager
extends java.lang.Object
implements Validateable

The PortletPersonalizationManager manages customization data for a portlet. Each customization must be created before it can be read/written. The create(PortletReference, ProviderUser) method establishes a new entry and populates it with default values. An alternative create(PortletReference, PersonalizationObject, ProviderUser) method is defined to allow clients to create a new instance with specific values.

Once created, customization attributes can be read from the persistent store using the read(PortletReference, ProviderUser) method, modified by updating the attributes of the PersonalizationObject and saved again using the write(PortletReference, PersonalizationObject, ProviderUser) method.

A customization is identified by its PortletReference. This reference may refer to a specific user instance or the default instance (see PortletReference for details). Unfortunately, the portal doesn't have knowledge of a specific user instance. It merely understands that a (single) portlet instance exists on a given page. The portal therefore leaves this determination up to the provider. Except when the operation is explicitly constrained to the default portlet instance, the JPDK always generates the deepest PortletReference. I.e. a reference to the per user customization. When reading a customization the read() method should start with the most specific reference specified by the PortletReference and work back towards the least specific until it finds a match for the portlet instance. If a match is not found at all, the Personalization Manager can throw a PortletNotFoundException or create a default customization using the default values. Under normal circumstances, a call to read() should always locate at least the default customization. Failure to do so indicates that data has been lost or the portlet instance was not registered correctly when it was added to the page.

Constructor Summary

PortletPersonalizationManager()

Method Summary

abstract void	copy(PortletReference from, PortletReference to, ProviderUser user) Copies the instance customizations from one reference to another.
abstract void	create(PortletReference ref, PersonalizationObject o, ProviderUser user) Creates the initial personalization reference for this (new) PortletReference.
abstract void	create(PortletReference ref, ProviderUser user) Creates the initial personalization reference for this (new) PortletReference and establishes its (static) defaults.
abstract void	destroy(PortletReference ref, ProviderUser user) Destroys a given Portlet instance from the repository by reference.
abstract void	destroy(ProviderInstance provider, PortletDefinition p) Called to allow the Portlet Personalization manager to destroy its repository.
abstract boolean	exists(PortletReference ref, ProviderUser user) Returns true is a customization exists for this given reference.
java.lang.Class	getDataClass() Gets the class name of the data objects this instance manages.
abstract void	init(PortletDefinition p) Called to allow this PortletPersonalizationManager to initialize its repository.
abstract PersonalizationObject	read(PortletReference ref, ProviderUser user) Returns an object containing the customizations particular to this reference.
void	setDataClass(java.lang.String className) Sets the class name of the data objects this instance manages.
void	validate(java.lang.String context, ValidationError errors) Validates the internal state of this PortletPersonalizationManager instance.
abstract void	write(PortletReference ref, PersonalizationObject o, ProviderUser user) Updates this references customizations.

Methods inherited from class java.lang.Object

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

Constructor Detail

PortletPersonalizationManager

public PortletPersonalizationManager()

Method Detail

setDataClass

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

Sets the class name of the data objects this instance manages. This class must implement the PersonalizationObject interface. The framework provides an implementation of this interface calle NameValuePersonalizationObject.

Parameters:

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

Throws:

PersonalizationException

getDataClass

public final java.lang.Class getDataClass()

Gets the class name of the data objects this instance manages.

Returns:

the name of the class

init

public abstract void init(PortletDefinition p)

Called to allow this PortletPersonalizationManager to initialize its repository. 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.

Parameters:

p - the portlet this PortletPersonalizationManager is controlling. From the Portlet you can get the Provider to identify the specific instance being created.

destroy

public abstract void destroy(ProviderInstance provider,
                             PortletDefinition 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).

Parameters:

provider - the provider instance that is being deregistered.

p - the portlet this PortletPersonalizationManager is controlling. From the Portlet you can get the Provider to identify the specific instance going away.

Throws:

AccessControlException

java.io.IOException

create

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

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

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.

Throws:

PortletAlreadyExistsException

AccessControlException

java.io.IOException

create

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

Creates the initial personalization reference for this (new) PortletReference. The initial setting are set from the object passed in .

Parameters:

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

o - object containing the customizations. It is expected that the manager know how to access/control this object to maintain a persistent store.

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

Throws:

PortletAlreadyExistsException

AccessControlException

java.io.IOException

exists

public abstract boolean exists(PortletReference ref,
                               ProviderUser user)
                        throws AccessControlException,
                               java.io.IOException

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

Parameters:

ref - the portlet instance to check

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

Throws:

AccessControlException

java.io.IOException

read

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

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

Parameters:

ref - the portlet referecne 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.

Throws:

PortletNotFoundException

AccessControlException

java.io.IOException

write

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

Updates this references customizations.

Parameters:

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

o - the object containing the new values.

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

Throws:

java.io.IOException

PortletNotFoundException

AccessControlException

destroy

public abstract 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.

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.

Throws:

PortletNotFoundException

AccessControlException

java.io.IOException

copy

public abstract 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 customization for the to reference doesn't exist it is created else the current values are overwritten.

Parameters:

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

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

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

Throws:

PortletNotFoundException

AccessControlException

java.io.IOException

validate

public void validate(java.lang.String context,
                     ValidationError errors)

Validates the internal state of this PortletPersonalizationManager instance. Errors found are reported using the supplied ValidationError instance.

Specified by:

validate in interface Validateable

Parameters:

context - The context of the calling instance.

errors - The current list of errors.