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

package oracle.portal.provider.v2.render;

import oracle.portal.provider.v2.PortletException;
import oracle.portal.provider.v2.PortletNotFoundException;
import oracle.portal.provider.v2.security.AccessControlException;

/**
 *  A PortletRenderer is the portlet controller responsible for generating
 *  the portlet's display (via markup).  The renderer use the information
 *  passed in the request to determine what "instance" its rendering.  If
 *  user customizations are supported, the render accesses the personalization
 *  manager to get the user specific data.<p>
 *  A renderer is designed for concurrent use.  That is a single renderer may
 *  have its <code>render()</code> method called concurrently.<p>
 *
 *  Besides specifying the rendering interface, this interface defines constants
 *  Renderers use to reference the portals CSS tags.  Using these is integral to
 *  having your renderer "adopt" the user page style.<p>
 *
 *  The interface also defines constants to represent the various render modes
 *  your portlet renderer may/must support.
 */

public abstract class PortletRenderer
{
    public static final String PORTLET_HEADING_1 = "PortletHeading1";
    public static final String PORTLET_HEADING_2 = "PortletHeading2";
    public static final String PORTLET_HEADING_3 = "PortletHeading3";
    public static final String PORTLET_HEADING_4 = "PortletHeading4";

    public static final String PORTLET_HEADER_TEXT = "PortletHeaderText";
    public static final String PORTLET_SUBHEADER_TEXT = "PortletSubHeaderText";
    public static final String PORTLET_HEADER_LINK = "PortletHeaderLink";
    public static final String PORTLET_SUBHEADER_LINK = "PortletSubHeaderLink";

    public static final String PORTLET_HEADER_COLOR = "PortletHeaderColor";
    public static final String PORTLET_SUBHEADER_COLOR = "PortletSubHeaderColor";
    public static final String PORTLET_BODY_COLOR = "PortletBodyColor";

    public static final String PORTLET_TEXT_1 = "PortletText1";
    public static final String PORTLET_TEXT_2 = "PortletText2";
    public static final String PORTLET_TEXT_3 = "PortletText3";
    public static final String PORTLET_TEXT_4 = "PortletText4";

    public static final String LEFT_CURVE = "LeftCurve";
    public static final String RIGHT_CURVE = "RightCurve";
    public static final String PAGE_COLOR = "PageColor";

    /**
     * The MIME content type for HTML output (i.e. "text/html")
     */
    public static final String TYPE_HTML = "text/html";

    /**
     * The MIME content type for XML output (i.e. "text/xml")
     */
    public static final String TYPE_XML = "text/xml";

    /**
     * The MIME content type for Mobile XML output
     */
    public static final String TYPE_MOBILE = "text/vnd.oracle.mobilexml";


    /**
     * The default character encoding for renderer output
     */
    public static final String DEFAULT_CHARACTER_ENCODING = "utf-8";


    /**
     *  Signifies this renderer should render its (regular) content.
     */
    public static final int MODE_SHOW = 1;

    /**
     *  Signifies this renderer should render its "about" information.  I.e the
     *  equivalent information that a client program would provide when the
     *  About menu is selected.  Usually contains version and author information.
     */
    public static final int MODE_ABOUT = 2;

    /**
     *  Signifies this renderer should render its user customization screen. I.e.
     *  a form containing the current user personalizations for this portlet.
     */
    public static final int MODE_EDIT = 3;

    /**
     *  Signifies this renderer should render its "help" information.  I.e the
     *  equivalent information that a client program would provide when the
     *  help menu is selected.  Usually, an overview of the portlet and how
     *  it can be used/customized.
     */
    public static final int MODE_HELP = 4;

    /**
     *  Signifies this renderer should render its default or system customization screen.
     *  The portal supports 2 levels of customization: user customization and system
     *  (or default) customization.  The later customizes the default setting of
     *  a portlet (instance) for this portlet.  All users who haven't customized the
     *  portlet are controlled by these settings.
     */
    public static final int MODE_EDIT_DEFAULTS = 5;

    /**
     *  Signifies this renderer should render its "details".
     */
    public static final int MODE_SHOW_DETAILS = 6;

    /**
     *  Signifies this renderer should render a preview of itself. A preview is
     *  a rendition that provides a sample of who this portlet will look at
     *  runtime without necessarily being "live".
     */
    public static final int MODE_PREVIEW = 7;

    /**
     *  Signifies this renderer should render a link reference to itself.
     */
    public static final int MODE_LINK = 8;

    /**
     *  The total number of modes a portlet can implement
     */
    public static final int TOTAL_MODES = 8;


    /**
     *  The String representation of the show mode.  Use PortletRendererUtil methods
     *  to map between the numberic mode value and its name.
     */
    public static final String MODE_NAME_SHOW = "show";

    /**
     *  The String representation of the about mode.  Use PortletRendererUtil methods
     *  to map between the numberic mode value and its name.
     */
    public static final String MODE_NAME_ABOUT = "about";

    /**
     *  The String representation of the edit mode.  Use PortletRendererUtil methods
     *  to map between the numberic mode value and its name.
     */
    public static final String MODE_NAME_EDIT = "edit";

    /**
     *  The String representation of the help mode.  Use PortletRendererUtil methods
     *  to map between the numberic mode value and its name.
     */
    public static final String MODE_NAME_HELP = "help";

    /**
     *  The String representation of the edit_defaults mode.  Use PortletRendererUtil methods
     *  to map between the numberic mode value and its name.
     */
    public static final String MODE_NAME_EDIT_DEFAULTS = "edit_defaults";

    /**
     *  The String representation of the details mode.  Use PortletRendererUtil methods
     *  to map between the numberic mode value and its name.
     */
    public static final String MODE_NAME_SHOW_DETAILS = "details";

    /**
     *  The String representation of the preview mode.  Use PortletRendererUtil methods
     *  to map between the numberic mode value and its name.
     */
    public static final String MODE_NAME_PREVIEW = "preview";

    /**
     *  The String representation of the link mode.  Use PortletRendererUtil methods
     *  to map between the numberic mode value and its name.
     */
    public static final String MODE_NAME_LINK = "link";

    /** Renders this portlet according to the portal render mode contained in the
     *  request.<p>
     * Portlet's are responsible for ensuring the request's user has sufficient
     * rights to receive this rendering.
     *
     * @param pr PortletRenderRequest for this rendering.
     */
    public abstract void render(PortletRenderRequest request)
            throws PortletException, AccessControlException;


}
