/*  Copyright (c) 2000 by Oracle Corporation. All Rights Reserved. */

package oracle.portal.provider.v1;

import java.io.IOException;

/**
 *  The PortletPersonalizationManager manages a portlets customizations.  Each
 *  customization must be created before it can be read/written.  create()
 *  establishes a new entry and fills it with default values. An alternative
 *  create() method is defined to allow clients to create a new instance with
 *  specific values.<p>
 *  Once created, customization attributes are controlled by reading them using
 *  the <code>read()</code> method, updating the attributes on customization object,
 *  and then writing them back using the <code>write()</code> method. <p>
 *  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.  This interface dictates it
 *  throws a PortletNotFoundException in the case where this per user customization
 *  doesn't exist.  Clients must be prepared to check for this situation and implement
 *  their own recovery rules.  This includes retying the operation using a
 *  self-generated PortletReference to the default portlet.
 */
public interface PortletPersonalizationManager {

    /**
     *  Initializes a new PortletPersonalizationManager 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 <code>init()</code> method).
     *
     *  @param p the portlet this PortletPersonalizationManager is controlling.
     *
     */
    public void initInstance(Portlet 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 <code>register()</code> method is
     *  called). This gives the personalization manager an opportunity to
     *  initialize the repository for the corresponding Portlet.<p>
     *
     *  @param  p the portlet this PortletPersonalizationManager is controlling.
     *  From the Portlet you can get the Provider to identify the specific instance
     *  being created.
     */
    public void init(Portlet p);

    /**
     *  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).
     *
     *  @param  p the portlet this PortletPersonalizationManager is controlling.
     *  From the Portlet you can get the Provider to identify the specific instance
     *  going away.
     */
    public void destroy(Portlet p) throws AccessControlException, IOException;

    /**
     * Creates the initial personalization reference for this (new)
     * PortletReference and establishes its (static) defaults.
     *
     * @param ref the PortletReference.  The details of the PortletReference
     * determine whether this creates the default, system instance or a specific
     * user instance.
     * @param user the user attempting this operation.  The manager is expected
     * to authorize the user before completing this operation.
     */
    public void create(PortletReference ref, 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 .
     *
     * @param ref the PortletReference.  The details of the PortletReference
     * determine whether this creates the default, system instance or a specific
     * user instance.
     * @param o object containing the customizations.  It is expected that the
     * manager know how to access/control this object to maintain a persistent
     * store.
     * @param user the user attempting this operation.  The manager is expected
     * to authorize the user before completing this operation.
     */
    public void create(PortletReference ref, Object o, ProviderUser user) throws PortletAlreadyExistsException, 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.
     *  @param ref the portlet instance to check
     *  @user the user making this request -- passed to give the manager access
     *  the the session.
     */
    public boolean exists(PortletReference ref, ProviderUser user) throws AccessControlException;


    /**
     *  Returns an object containing the customizations particular to this reference.
     *  If no customizations exist then the PortletNotFoundException is thrown.
     *  @param ref the portlet referecne that identifies the instance whose
     *  customizations are being requested.
     *  @param user the user attempting this operation.  The manager is expected
     * to authorize the user before completing this operation.
     */
    public Object read(PortletReference ref, ProviderUser user)  throws PortletNotFoundException, AccessControlException, java.io.IOException;


    /**
     *  Updates this references customizations.
     *  @param ref the portlet reference that identifies the instance whose
     *  customizations are being updated.
     *  @param o the object containing the new values.
     *  @param user the user attempting this operation.  The manager is expected
     * to authorize the user before completing this operation.
     */
    public void write(PortletReference ref, Object o, ProviderUser user)  throws java.io.IOException, PortletNotFoundException, AccessControlException;

    /**
     *  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.
     *
     *  @param  ref the portlet reference that identifies the instance whose
     *  customizations are being deleted.
     *  @param user the user attempting this operation.  The manager is expected
     * to authorize the user before completing this operation.
     */
    public void destroy(PortletReference ref, ProviderUser user) throws PortletNotFoundException, AccessControlException, 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.
     *
     *  @param from reference for the portlet isntance we are copying from.
     *  @param to reference for the portlet isntance we are copying to.
     *  @param user the user attempting this operation.  The manager is expected
     * to authorize the user before completing this operation.
     */
    public void copy(PortletReference from, PortletReference to, ProviderUser user) throws PortletNotFoundException, AccessControlException, IOException;


}

 
