venice-main-classic/src/com/silverwrist/venice/ui/RequestInput.java

/*
 * The contents of this file are subject to the Mozilla Public License Version 1.1
 * (the "License"); you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at <http://www.mozilla.org/MPL/>.
 * 
 * Software distributed under the License is distributed on an "AS IS" basis, WITHOUT
 * WARRANTY OF ANY KIND, either express or implied. See the License for the specific
 * language governing rights and limitations under the License.
 * 
 * The Original Code is the Venice Web Communities System.
 * 
 * The Initial Developer of the Original Code is Eric J. Bowersox <erbo@silcom.com>,
 * for Silverwrist Design Studios.  Portions created by Eric J. Bowersox are
 * Copyright (C) 2001-02 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
 * 
 * Contributor(s): 
 */
package com.silverwrist.venice.ui;

import java.io.InputStream;
import java.io.IOException;
import java.util.Enumeration;
import java.util.Map;
import org.w3c.dom.Document;
import com.silverwrist.util.ServletMultipartException;
import com.silverwrist.venice.core.CommunityContext;
import com.silverwrist.venice.core.UserContext;
import com.silverwrist.venice.core.VeniceEngine;
import com.silverwrist.venice.except.*;
import com.silverwrist.venice.ui.dlg.Dialog;
import com.silverwrist.venice.ui.helpers.ErrorBox;
import com.silverwrist.venice.ui.menus.MenuComponent;
import com.silverwrist.venice.ui.script.ScriptManager;
import com.silverwrist.venice.util.ServiceProvider;

public interface RequestInput extends ServiceProvider
{
  public static final String LEFT_MENU_SESSION_ATTR = "LeftMenu";

  /**
   * Returns a <CODE>String</CODE> containing the real path for a given virtual path. For example,
   * the virtual path &quot;/index.html&quot; has a real path of whatever file on the server's filesystem
   * would be served by a request for &quot;/index.html&quot;.<P>
   * This method returns <CODE>null</CODE> if the virtual path cannot be translated to a real path for
   * any reason.
   *
   * @param s A <CODE>String</CODE> specifying a virtual path.
   * @return A <CODE>String</CODE> specifying the real path, or <CODE>null</CODE> if the translation cannot
   *         be performed.
   */
  public abstract String mapPath(String s);

  /**
   * Returns the portion of the request URI that indicates the context of the request, i.e. the servlet
   * context under which Venice is installed. The context path always comes first in a request URI. The
   * path starts with a &quot;/&quot; character but does not end with a &quot;/&quot; character.
   *
   * @return A <CODE>String</CODE> specifying the portion of the request URI that indicates the context
   * of the request.
   */
  public abstract String getContextPath();

  /**
   * Returns the part of this request's URI that calls the servlet. This includes either the servlet name
   * or a path to the servlet, but does not include any extra path information or a query string.
   *
   * @return A <CODE>String</CODE> containing the name or path of the servlet being called, as specified
   *         in the request URI.
   */
  public abstract String getServletPath();

  /**
   * Returns any extra path information associated with the URI the client sent when it made this request.
   * The extra path information follows the servlet path but precedes the query string. This method
   * returns <CODE>null</CODE> if there was no extra path information.  In Venice, the path information is
   * used to specify parameters in certain servlets.
   *
   * @return A <CODE>String</CODE> specifying extra path information that comes after the servlet path
   *         but before the query string in the request URI; or <CODE>null</CODE> if the URI does not
   *         have any extra path information.
   */
  public abstract String getPathInfo();

  /**
   * Returns the query string that is contained in the request URI after the path. This method returns
   * <CODE>null</CODE> if the URI does not have a query string.
   *
   * @return A <CODE>String</CODE> containing the query string or <CODE>null</CODE> if the URI contains
   *         no query string.
   */
  public abstract String getQueryString();

  /**
   * Returns the name of the HTTP method with which this request was made, for example, GET, POST, or PUT.
   *
   * @return A <CODE>String</CODE> specifying the name of the method with which this request was made.
   */
  public abstract String getVerb();

  /**
   * Returns the Internet Protocol (IP) address of the client that sent the request.
   *
   * @return A <CODE>String</CODE> containing the IP address of the client that sent the request.
   */
  public abstract String getSourceAddress();

  /**
   * Returns <CODE>true</CODE> if the request parameter with the specified name is defined,
   * <CODE>false</CODE> if not.  For standard Venice requests, parameters are contained in the
   * query string or posted form data.
   *
   * @param name Parameter name to be checked.
   * @return See above.
   */
  public abstract boolean hasParameter(String name);

  /**
   * Returns the value of a request parameter as a <CODE>String</CODE>, or <CODE>null</CODE> if the
   * parameter does not exist. For standard Venice requests, parameters are contained in the query
   * string or posted form data.<P>
   * You should only use this method when you are sure the parameter has only one value. If the parameter
   * might have more than one value, use {@link #getParameterValues(java.lang.String)}.<P>
   * If you use this method with a multivalued parameter, the value returned is equal to the first value
   * in the array returned by <CODE>getParameterValues</CODE>.
   *
   * @param name A <CODE>String</CODE> specifying the name of the parameter.
   * @return A <CODE>String</CODE> representing the single value of the parameter.
   * @see #getParameterValues(java.lang.String)
   */
  public abstract String getParameter(String name);

  /**
   * Returns the value of a request parameter as a <CODE>int</CODE>, or a specified default value if
   * the parameter does not exist. For standard Venice requests, parameters are contained in the query
   * string or posted form data.<P>
   * If you use this method with a multivalued parameter, the value returned is equal to the
   * <CODE>int</CODE> equivalent of the first value in the array returned by <CODE>getParameterValues</CODE>.
   *
   * @param name A <CODE>String</CODE> specifying the name of the parameter.
   * @param default_value The default value to use for the parameter if the specified parameter does not exist.
   * @return An <CODE>int</CODE> representing the single value of the parameter.
   */
  public abstract int getParameterInt(String name, int default_value);

  /**
   * Returns the value of a request parameter as a <CODE>short</CODE>, or a specified default value if
   * the parameter does not exist. For standard Venice requests, parameters are contained in the query
   * string or posted form data.<P>
   * If you use this method with a multivalued parameter, the value returned is equal to the
   * <CODE>short</CODE> equivalent of the first value in the array returned by <CODE>getParameterValues</CODE>.
   *
   * @param name A <CODE>String</CODE> specifying the name of the parameter.
   * @param default_value The default value to use for the parameter if the specified parameter does not exist.
   * @return A <CODE>short</CODE> representing the single value of the parameter.
   */
  public abstract short getParameterShort(String name, short default_value);

  /**
   * Returns the value of a request parameter as a <CODE>long</CODE>, or a specified default value if
   * the parameter does not exist. For standard Venice requests, parameters are contained in the query
   * string or posted form data.<P>
   * If you use this method with a multivalued parameter, the value returned is equal to the
   * <CODE>long</CODE> equivalent of the first value in the array returned by <CODE>getParameterValues</CODE>.
   *
   * @param name A <CODE>String</CODE> specifying the name of the parameter.
   * @param default_value The default value to use for the parameter if the specified parameter does not exist.
   * @return A <CODE>long</CODE> representing the single value of the parameter.
   */
  public abstract long getParameterLong(String name, long default_value);

  /**
   * Returns an <CODE>Enumeration</CODE> of <CODE>String</CODE> objects containing the names of the
   * parameters contained in this request. If the request has no parameters, the method returns an empty
   * <CODE>Enumeration.</CODE>
   *
   * @return An <CODE>Enumeration</CODE> of <CODE>String</CODE> objects, each <CODE>String</CODE>
   *         containing the name of a request parameter, or an empty <CODE>Enumeration</CODE> if the
   *         request has no parameters.
   */
  public abstract Enumeration getParameterNames();

  /**
   * Returns an array of <CODE>String</CODE> objects containing all of the values the given request
   * parameter has, or <CODE>null</CODE> if the parameter does not exist.<P>
   * If the parameter has a single value, the array has a length of 1.
   *
   * @param name A <CODE>String</CODE> containing the name of the parameter whose value is requested.
   * @return An array of <CODE>String</CODE> objects containing the parameter's values.
   * @see #getParameter(java.lang.String)
   */
  public abstract String[] getParameterValues(String name);

  /**
   * Returns <CODE>true</CODE> if the specified parameter is a file parameter, <CODE>false</CODE> if
   * not.  If the parameter does not exist, the return value is <CODE>false</CODE>.
   *
   * @param name A <CODE>String</CODE> containing the name of the parameter to test.
   * @return See above.
   */
  public abstract boolean isFileParam(String name);

  /**
   * Returns the MIME type of the specified parameter.  If the type cannot be determined, the return
   * value is <CODE>null</CODE>.<P>
   * N.B.: For non-file parameters, or all parameters to a request that is not a file upload, the MIME
   * type is &quot;text/plain&quot;.
   *
   * @param name A <CODE>String</CODE> containing the name of the parameter to test.
   * @return See above.
   */
  public abstract String getParameterType(String name);

  /**
   * Returns the size in bytes of the specified parameter.  If the size cannot be determined, the return
   * value is -1.<P>
   * N.B.: For non-file parameters, or all parameters to a request that is not a file upload, the size
   * is the number of bytes occupied by the parameter, expressed in UTF-8 encoding.
   *
   * @param name A <CODE>String</CODE> containing the name of the parameter to test.
   * @return See above.
   */
  public abstract int getParameterSize(String name);

  /**
   * Returns an <CODE>InputStream</CODE> reading from the data of the named file parameter.  If the
   * named parameter does not exist or is not a file parameter, returns <CODE>null;
   *
   * @param name A <CODE>String</CODE> containing the name of the parameter whose value is requested.
   * @return See above.
   * @exception com.silverwrist.util.ServletMultipartException If there is a problem retrieving
   *            the parameter data stream.
   */
  public abstract InputStream getParameterDataStream(String name) throws ServletMultipartException;

  /**
   * Returns <CODE>true</CODE> if the parameter set reflects the clicking of an image button with a
   * specified name, <CODE>false</CODE> if not.
   *
   * @param name A <CODE>String</CODE> containing the name of the image button to test.
   * @return See above.
   */
  public abstract boolean isImageButtonClicked(String name);

  /**
   * Returns the application-level attribute with the given name, or <CODE>null</CODE> if there is no
   * attribute by that name.
   *
   * @param name A <CODE>String</CODE> specifying the name of the attribute.
   * @return An <CODE>Object</CODE> containing the value of the attribute, or <CODE>null</CODE> if no
   *         attribute exists matching the given name.
   */
  public abstract Object getAppAttribute(String name);

  /**
   * Sets the application-level attribute with the given name.
   *
   * @param name A <CODE>String</CODE> specifying the name of the attribute.
   * @param o The object to be bound as the value of that attribute, or <CODE>null</CODE> if the binding
   *          is to be removed.
   */
  public abstract void setAppAttribute(String name, Object o);

  /**
   * Returns the session-level attribute with the given name, or <CODE>null</CODE> if there is no
   * attribute by that name.
   *
   * @param name A <CODE>String</CODE> specifying the name of the attribute.
   * @return An <CODE>Object</CODE> containing the value of the attribute, or <CODE>null</CODE> if no
   *         attribute exists matching the given name.
   */
  public abstract Object getSessionAttribute(String name);

  /**
   * Sets the session-level attribute with the given name.
   *
   * @param name A <CODE>String</CODE> specifying the name of the attribute.
   * @param o The object to be bound as the value of that attribute, or <CODE>null</CODE> if the binding
   *          is to be removed.
   */
  public abstract void setSessionAttribute(String name, Object o);

  /**
   * Returns the request-level attribute with the given name, or <CODE>null</CODE> if there is no
   * attribute by that name.
   *
   * @param name A <CODE>String</CODE> specifying the name of the attribute.
   * @return An <CODE>Object</CODE> containing the value of the attribute, or <CODE>null</CODE> if no
   *         attribute exists matching the given name.
   */
  public abstract Object getRequestAttribute(String name);

  /**
   * Sets the request-level attribute with the given name.
   *
   * @param name A <CODE>String</CODE> specifying the name of the attribute.
   * @param o The object to be bound as the value of that attribute, or <CODE>null</CODE> if the binding
   *          is to be removed.
   */
  public abstract void setRequestAttribute(String name, Object o);

  /**
   * Returns the instance of the Venice engine associated with the application.
   *
   * @return See above.
   */
  public abstract VeniceEngine getEngine();

  /**
   * Returns the instance of the Venice user object associated with the session.
   *
   * @return See above.
   */
  public abstract UserContext getUser();

  /**
   * Returns the current servlet location.  This is used, for instance, as the context to return to
   * after a login.
   *
   * @return The current servlet location.
   */
  public abstract String getLocation();

  /**
   * Sets the &quot;current&quot; servlet location that is displayed.  This is used, for instance,
   * as the context to return to after a login.
   *
   * @param str The new location to be set.
   */
  public abstract void setLocation(String str);

  /**
   * Returns <CODE>true</CODE> if the &quot;Log In&quot; link is to be displayed on the outer frame,
   * <CODE>false</CODE> if not.
   *
   * @return See above.
   */
  public abstract boolean getDisplayLogin();

  /**
   * Sets whether or not the &quot;Log In&quot; link is to be displayed on the outer frame.
   *
   * @param val <CODE>true</CODE> to display the &quot;Log In&quot; link on the outer frame,
   *            <CODE>false</CODE> to omit it.
   */
  public abstract void setDisplayLogin(boolean val);

  public abstract MenuComponent getMenu(String name);

  public abstract MenuComponent getMenu(String name, Map vars);

  public abstract Dialog getDialog(String name);

  public abstract Content[] getSideBoxes() throws AccessError, DataException;

  public abstract CommunityContext getCommunity();

  public abstract CommunityContext getCommunity(boolean required, String on_error) throws ErrorBox;

  public abstract String getDefaultServletAddress(CommunityContext comm);

  public abstract void registerCleanup(AutoCleanup ac);

  public abstract String getConfigProperty(String name);

  public abstract String getConfigProperty(String name, String default_val);

} // end interface RequestInput