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

package oracle.portal.provider.v1;

import java.util.Locale;
import java.util.Calendar;

/**
 *  A portlet implements a particular portal service.  It is managed and exposed
 *  to the portal via a <code>Provider</code>. A portlet is implemented as a set of controllers:
 *  a renderer and optionally a personalization manager and a security manager.<p>
 *  The Portlet interface is a container for these controllers as well as portlet meta-data.  The portlet design uses a controller model.
 *  The meta-data specifies the static meta-data of this portlet; e.g. the id, name, etc.
 *  The security manager (controller) is used to authorize a portlet user's actions.
 *  See the <code>PortletSecurityManager</code> interface for further details.<p>
 *  The personalization manager (controller) provides access to and manages a portlet's
 *  user customizations. See the <code>PortletPersonalizatonManager</code> interface for further details.
 *  <p>The renderer is responsible for all renditions(browser output) of the
 *  portlet.  See the <code>PortletRenderer</code> interface. for further details.<p>
 *  Controllers operate on logical portlet instance references.  I.e. the object
 *  that represents a particular instance merely identifies the instance; it
 *  doesn't contain any additional actions.  The controllers use this reference
 *  to map to their data model and perform their actions.  This keeps the number
 *  of objects to a minumum ensuring maximum throughput.<p>
 *  By example, assume a portlet that implements user customizations. When asked
 *  to render, the framework:
 *  <ul>
 *  <li>Uses the <code>Provider</code> to get the <code>Portlet</code> that corresponds to
 *  the request.</li>
 *  <li>Constructs a <code>PortletRenderRequest</code> from the available information.</li>
 *  <li>Gets the <code>PortletRenderer</code> from the <code>Portlet</code> by calling
 *  <code>getPortletRenderer()</code>.</li>
 *  <li>Calls <code>renderer.render()</code>.</li>
 *  </ul>
 *  The renderer in turn:
 *  <ul>
 *  <li>Gets the <code>SecurityManager</code> from the request and checks with it to
 *  see if the current user is authorized to render the corresponding
 *  <code>PortletReference</code> contained in the request.</li>
 *  <li>Gets the <code>PersonalizationManager</code> from the request.</li>
 *  <li>Asks the <code>PersonalizationManager</code> for the personalization information
 *  corresponding to the <code>PortletReference</code> contained in the request.<li>
 *  <li>Renders the response using the information from the
 *  <code>PersonalizationManager</code> as well as information contained in the
 *  request.</li>
 *  </ul>
 */



public interface Portlet {

    /**
     *  Initializes the Portlet.  At its simpliest it registers the
     *  provider this Portlet is managed by.  Needed because framework
     *  uses a null constructor.
     */

    public void init(Provider p);

    /**
     *  Gets the security manager for this portlet.  The security manager is
     *  used to check whether a user is authorized to perform a specific action.
     *  It is valid for a Portlet to not have a security manager.  I.e. this
     *  method can return null.  If there is no security manager it is assumed
     *  that all users have unrestricted access.
     */
    public PortletSecurityManager getSecurityManager();

    /**
     *  Gets the personalization manager for this portlet.  The personalization
     *  manager provides the interface between the renderer and the personalization
     *  store that allows the renderer to get the user customizations for this
     *  rendition.  It is valid for a Portlet to not have a personalization
     *  manager.  I.e. this method can return null.
     */
    public PortletPersonalizationManager getPersonalizationManager();

    /**
     *  Gets the renderer for this portlet.  The renderer is responsible for
     *  emitting the visual aspects of the portlet (as markup).  All portlets
     *  must have a renderer.
     */
    public PortletRenderer getRenderer();



    /**
     *  Gets the Provider of this Portlet.
     *
     *  @return  the Provider that manages this Portlet.
     */
    public Provider getProvider();

    /**
     *  Gets the string resource (bundle) for this Portlet.  This is the resource
     *  bundle that stores the meta-data string values for this portlet.  I.e. if
     *  this portlet has been internationalized different translations are provided
     *  the meta-data values returned by this interface.  This method returns the
     *  resource bundle containing these resources.
     *
     *  @return  the string resource (bundle) for this Portlet.  <b>null</b> if
     *  there isn't one.
     */
    public java.util.ResourceBundle getResourceBundle(Locale l);

    /**
     *  Returns this Portlet's default locale.
     */
    public java.util.Locale getDefaultLocale();

    /**
     *  Gets the Portlet name.
     *
     *  @param The Locale the name should be represented in.
     *  @return  the Portlet name.  This is the Portlet's non-unique display name.
     */
    public String getName(Locale l);

    /**
     *  Gets the Portlet unique ID.  This ID must be unique within this Portlet's
     *  Provider.  It must also be immutable.  It need not be sequential.
     *
     *  @return  the Portlet (unique ID.  Value should be unique with
     *  respect to the Provider.
     */
    public long getId();

    /**
     *  Gets the Portlet title.
     *
     *  @param The Locale the name should be represented in.
     *  @return  the title of this Portlet.  This is the name that shows up in
     *  a portlet's title bar.
     */
    public String getTitle(Locale l);

    /*
     *  Gets the Portlet description.
     *
     *  @param The Locale the name should be represented in.
     *  @return  a short description of what this portlet is.  Displayed at
     *  design-time along with the name and thumbnail image when a user is choosing
     *  to add a portlet to a page.
     */
    public String getDescription(Locale l);

    /**
     *  Gets an array of (input) parameters that this portlet recognizes when
     *  requested to render to control/affect the rendering.
     *
     *  @return  array of PortletParameters.
     */
    public PortletParameter[] getInputParameters();

    /**
     *  Gets an array of mime-types (represented as Strings) that this Portlet
     *  can render.  For example {"text/html", "text/xml"}.
     *
     *  @return  array containing a list of mime-types.
     */
    public String[] getAcceptContentTypes();

    /**
     *  Gets the number of seconds the portal should wait before timing out a request
     *  to this portlet.
     *
     *  @return  timeout period in seconds.
     */
    public int getTimeout();

    /**
     *  Gets the timeout messsage that the portal should use in its response when
     *  a request to this Portlet times out.
     *
     *  @param The Locale the timeout message should be represented in.
     *  @return  Timeout message.
     */
    public String getTimeoutMessage(Locale l);

    /**
     *  Returns <code>true</code> if this Portlet supports per user personalization,
     *  <code>false</code> otherwise.
     *
     *  @return  returns <code>true</code> if this Portlet supports per user
     *  personalization, <code>false</code> otherwise.
     */
    public boolean hasShowEdit();

    /**
     *  Returns <code>true</code> if this Portlet exposes per user personalization to the
     *  public (non-logged in) user.  The default for portlets is <code>false</code>.  In general
     *  allowing the public user to personalize a portlet is a bad idea as the
     *  personalization is seen by all public users.  Instead it is recommended
     *  that controlled users be allowed to edit the portlet's defaults which
     *  are then exposed through to the public users (and any other user that
     *  doesn't personalize the portlet).
     *
     *  @deprecated use PortletXtra3.getMinEditAuthLevel(),
     *                  MutablePortletXtra3.setMinEditAuthLevel()
     *
     *  @return  returns <code>true</code> if this Portlet exposes per user personalization to the
     *  public (non-logged in) user, <code>false</code> otherwise.
     */
    public boolean getShowEditToPublic();

    /**
     *  Returns <code>true</code> if this Portlet supports per portlet customization,
     *  <code>false</code> otherwise.  Per portlet customizations means that all users of this
     *  instance see a customized version of the portlet vs. the generic version.
     *  Users are then free to further personalize this instance (via showEdit).
     *
     *  @return  returns true if this Portlet supports per portlet customization, false
     *  otherwise.
     */
    public boolean hasShowEditDefault();


    /**
     *  Returns <code>true</code> if this Portlet is capable of displaying a design-time
     *  preview of itself (after customization or personalization). Returns
     *  <code>false</code> otherwise.
     *
     */
    public boolean hasShowPreview();

    /**
     *  @return returns <code>true</code> if this Portlet is capable of displaying a full-screen
     *  (detailed) version of itself.
     *
     */
    public boolean hasShowDetails();

    /**
     *  @return returns <code>true</code> if this Portlet is capable of displaying help
     *  information.
     *
     */
    public boolean hasHelp();

    /**
     *  @return returns <code>true</code> if this Portlet is capable of displaying about
     *  information.
     *
     */
    public boolean hasAbout();

}

