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

package oracle.portal.provider.v2.render;

import oracle.portal.provider.v2.*;
import oracle.portal.provider.v2.personalize.PortletReference;

import java.io.*;
import java.util.*;
import javax.servlet.http.*;

/**
 * The PortletRenderRequest contains all the request details a renderer needs to
 * process the request and output its rendition.  A single renderer is responsible
 * for rendering each of the Portlet render modes (see getMode()).<p>
 * When this renderer is running in a servlet environment the servlet (base)
 * objects are accessible as attributes of the PortletRendererRequest.
 * To get the HttpServletRequest object call:
 * renderRequest.getAttribute(HttpCommonConstants.SERVLET_REQUEST).<br>
 * To get the ServletContext object call:
 * renderRequest.getAttribute(HttpCommonConstants.SERVLET_CONTEXT).<br>
 * To get the ServletConfig object call:
 * renderRequest.getAttribute(HttpCommonConstants.SERVLET_CONFIG).<br>
 */
public interface PortletRenderRequest {

    /**
     * @return an object containing parameters to this <code>PortletRenderRequest</code>
     */
    public RenderContext getRenderContext();

    /**
     *
     *  @return an array of mime-types in preference order being requested.  I.e.
     *  the portal may pass a list of valid mime-types it accepts for the target
     *  device.  The Portlet must emit its response in one of these mime-types.
     *  The list is ordered by reference with the first being the highest preference.
     */
    public String[] getAcceptContentTypes() throws java.lang.IllegalStateException;

    /**
     *
     *  @return the most preferred mime-type beign requested. This is the first
     *  entry in the array returned by getAcceptContentTypes();
     */
    public String getPreferredContentType() throws java.lang.IllegalStateException;

    /**
     *
     *  @return the rendering mode.  The mode is defined in the various constants
     *  in PortletRenderer.
     */
    public int getMode() throws java.lang.IllegalStateException;

    /**
     * @return the URL that invoked this portlet.  Portlets use this to
     * (re)write HREFs in their response as these references must be absolute
     * paths since the client browser considers the current target the
     * portal. Note: request parameters are always returned as part of the URLs
     * querystring regardless of whether the request was received via an HTTP
     * GET or POST.
     */
    public String getRequestURL() throws java.lang.IllegalStateException;

    /**
     *  @return the reference to the portlet instance we are intended to render.
     *  This is the object that represents what we are rendering.
     */
    public PortletReference getPortletReference();

    /**
     *  @return the portlet instance we are intended to render.
     */
    public PortletInstance getPortletInstance();

    /**
     *  @return the user making this request.
     */
    public ProviderUser getUser();

    /**
     *  If this is a mobile request iAS Wireless will have overwritten some
     *  of the client's original HTTP headers: specifically the Accept and the
     *  UserAgent header.  These routines give you access to the original values.
     *  Note: if the values haven't been overwritten then its assumed that the
     *  standard headers contain the original values.  In this situation these
     *  methods return the values for the standard headers.  In this way these
     *  methods always give you access to the header values as they originated
     *  from the client whether or not they have been overwritten.
     *
     *  @param name the header name you want the original value for.  I.e. if
     *  you pass "Accept" you will receive the original value of "Accept"
     *  whether its been overwritten or not.
     */
    public String getOriginalHeader(String name);

    /* convenience routines -- each can be accessed indirectly via the PortletReference */

    /**
     * Gets the ProviderInstance associated with this request.  This is equivalent to
     * calling getPortletInstance().getProviderInstance().
     */
    public ProviderInstance getProviderInstance();

    /**
     * Gets the PortletDefinition associated with this request.  This is equivalent to
     * calling getPortletInstance().getPortletDefinition().
     */
    public PortletDefinition getPortletDefinition();


    /**
     *  The scheme we are running in.  Most commonly this will return <b>http</b>.
     *  Return value will be <i>null</i> if not running in any scheme.  This
     *  can occur if running outside the context of a request as in a batch
     *  program filling a cache on the server.
     */
    public String getScheme();

    /**
     *  The user agent that originated this request.  May be null if user-agent is
     *  local.
     */
    public String getUserAgent();

    /**
     *  Server name.  Used to reconstruct absolute paths back to
     *  server.
     */
    public String getServerName();

    /**
     *  Port used by this server. Used to reconstruct absolute paths back to
     *  server.
     */
    public int getServerPort();

    /**
     *  Returns the request parameter(value) of the given name.  If there are duplicates
     *  the first value is returned.  Returned Parameter values are encoded using
     *  the RequestContext's encoding.  By default this is ISO-8859-1.
     *
     *  @param name the name of the parameter whose value is requested.
     */
    public String getParameter(String name);

    /**
     *  Returns the qualified request parameter of the given non-qualified name.  Because all
     *  portlets on a page share the same query string, portlets will often
     *  fully qualify their parameter names to the portlet instance to ensure
     *  the instance can distinguish its parameters from the others.  This qualification
     *  is of the form providerId.portletId.instanceName.paramName.  Utility
     *  methods are provided in PortletRendererUtil and HttpPortletRendererUtil
     *  to construct these fully qualified names.<p>
     *  Fully-qualified parameter names are somewhat inconvenient to use because
     *  they are dynamic.  I.e. they are isntance-based.  This method helps to overcome
     *  this inconvenience by allowing you to retrieve the fully qualified parameter
     *  name value passing only the non-qualified name.  E.g. calling
     *  request.getQualifiedParameter("symbol") will return the value for the
     *  parameter named "<i>curProviderId.curPortletId.curInstanceName</i>.symbol".

     *  As with getParameter(), if there are duplicates
     *  the first value is returned.  Returned Parameter values are encoded using
     *  the RequestContext's encoding.  By default this is ISO-8859-1.
     *
     *  @param name the unqualfied name of the parameter whose value is requested.
     *  @return the value corresponding to the fully qualified name constructed  by
     *  prepending the portlet reference information to the passed parameter name.
     */
    public String getQualifiedParameter(String name);

    /**
     *  Returns the values for the named request parameter.
     *  Returned Parameter values are encoded using
     *  the RequestContext's encoding.  By default this is ISO-8859-1.
     *
     *  @param name the name of the parameter whose value is requested.
     *  @return an array of Strings; one element per value associated with
     *     this parameter name.
     */
    public String[] getParameterValues(String name);

    /**
     *  Returns the qualified request parameter values of the given non-qualified name.  Because all
     *  portlets on a page share the same query string, portlets will often
     *  fully qualify their parameter names to the portlet instance to ensure
     *  the instance can distinguish its parameters from the others.  This qualification
     *  is of the form providerId.portletId.instanceName.paramName.  Utility
     *  methods are provided in PortletRendererUtil and HttpPortletRendererUtil
     *  to construct these fully qualified names.<p>
     *  Fully-qualified parameter names are somewhat inconvenient to use because
     *  they are dynamic.  I.e. they are isntance-based.  This method helps to overcome
     *  this inconvenience by allowing you to retrieve the fully qualified parameter
     *  name value passing only the non-qualified name.  E.g. calling
     *  request.getQualifiedParameterValues("symbol") will return the values for the
     *  parameter named "<i>curProviderId.curPortletId.curInstanceName</i>.symbol".

     *  Returned Parameter values are encoded using
     *  the RequestContext's encoding.  By default this is ISO-8859-1.
     *
     *  @param name the unqualfied name of the parameter whose value is requested.
     *  @return the values corresponding to the fully qualified name constructed  by
     *  prepending the portlet reference information to the passed parameter name.
     */
    public String[] getQualifiedParameterValues(String name);

    /**
     *  Returns an enumeration containing the parameter names passed in this request.
     */
    public Enumeration getParameterNames();

    /**
     *  Returns an enumeration containing only those parameter names that match this
     *  portlets fully qualified name.  I.e. only those parameters that are prefixed
     *  by this portlet's curProviderId.curPortletId.curInstanceName.  The return
     *  values remain fully qualified.  I.e. the names in the enumeration remain
     *  fully qualified -- hence you use the regular methods to access (getParameter()
     *  vs. getQualifiedParameter())
     */
    public Enumeration getQualifiedParameterNames();

    /**
     * Returns a PrintWriter used to emit this request's response. If
     * applicable the passed contentType is used to prepare the response
     * (header).  <p>Note: <p>if <b>null</b> is passed the content type of the
     * response is set to "text/html". The character encoding used is based on
     * the default encoding of the request.
     * <p> After the first call to any of the getWriter() methods the content
     * type cannot be changed.
     */
    public PrintWriter getWriter() throws java.io.IOException;

    /**
     * Returns a PrintWriter used to emit this request's response. If
     * applicable the passed contentType is used to prepare the response
     * (header).  <p>Note: <p>Uses the content type specified by calling
     * setContentType() or defaults the content type of the response to
     * "text/html".  The character encoding used is based on the default
     * encoding of the request.
     * <p> After the first call to any of the getWriter() methods the content
     * type and character encoding cannot be changed.
     */
    public PrintWriter getWriter(String contentType) throws java.io.IOException;


    /**
     *  Sets the contentType for this request's response.
     *  After the first call to any of the getWriter() methods the
     *  content type and character encoding cannot be changed.
     */
    public void setContentType(String contentType);

    /**
     *  Gets the current contentType of this request's response.
     *  After the first call to any of the getWriter() methods the
     *  content type and character encoding cannot be changed.
     */
    public String getContentType();

    /**
     * The Java Locale to be used for this response.
     */
    public Locale getLocale();

    /**
     * Returns an Enumeration of Locale objects indicating, in
     * decreasing order starting with the preferred locale, the locales that are
     * acceptable to the client based on the Accept-Language header.
    */

    public Enumeration getLocales();

    /**
     *  Returns the Portal's default Locale.  Used by portlets/personalization managers
     *  to properly default to the correct language when preferred languages aren't
     *  supported.  This value may be <code>null</code>.  When <code>null</code> or
     *  when the portlet doesn't support this locale the Portlet's default Locale should
     *  be used.  This is accessible via the Portlet interface (<code>getDefaultLocale()</code>).<p>
     *  Alternatively, you might consider using the <code>getDefaultLocale()</code> method in the
     *  <code>PortletReference</code> interface.  This method is defined to return the Portlet's
     *  default locale if the Portal hasn't passed one.
     */
    public Locale getDefaultLocale();

    /**
     *  Returns the Provider resource associated with the Locale of this request.
     *  This resource contains locale specific strings for the title bar.
     */
    public ResourceBundle getProviderResource();


    /**
     *  A session is an object that maintains state across requests. For those
     *  familiar with ServletSessions, the ProviderSession is a thin wrapper
     *  that isolates this interface from any servlet dependencies.  When your
     *  provider runs in an Http/servlet environment values you get/set on the
     *  ProviderSession are passed through to the HttpSession.
     *
     */
    public ProviderSession getSession();

    /**
     *  An array of cookies passed to this request.  Cookies must be established
     *  in the Provider's initSession method.  Again the return type is
     *  indiscriminant to isolate us from the servlet interface.  When running
     *  in the Http/servlet environment the objects returned in this array are
     *  type javax.servlet.http.Cookie.
     *
     */
    public Object[] getCookies();


    /**
     *  Data can be passed between object in a request via attr/value pairs
     *  hung off the RequestContext.  Clients are encouraged to prefix attribute
     *  names with fully qualified class names to avoid collisions.  E.g.
     *  setAttribute("oracle.jdeveloper.chart.color", chartColor);
     *
     *  @param name the name of the attribute.
     *  @param value the value for the attribute.
     */
    public void setAttribute(String name, Object value);


    /**
     *  Data can be passed between object in a request via attr/value pairs
     *  hung off the RequestContext.  Clients are encouraged to prefix attribute
     *  names with fully qualified class names to avoid collisions.  E.g.
     *  setAttribute("oracle.jdeveloper.chart.color", chartColor);
     *
     *  @param name the name of the attribute.
     *  @return value the value for the attribute.
     */
    public Object getAttribute(String name);

    /**
     *  returns the names of this request's attributes
     */
    public java.util.Enumeration getAttributeNames();

    /**
     *  Removes an existing attribute.
     *
     *  @param name the name of the attribute.
     */
    public void removeAttribute(String name);

    /**
    * Returns the character set that was used when the parameters of the
    * request were encoded.  Used when encoding parameters for inclusion in
    * a URL
    */
    public String getURLCharSet();
}

