/*
 * @(#)DataWebBean.java
 *
 * Copyright 1999-2002 by Oracle Corporation,
 * 500 Oracle Parkway, Redwood Shores, California, 94065, U.S.A.
 * All rights reserved.
 *
 * This software is the confidential and proprietary information
 * of Oracle Corporation.
 */

package oracle.jdeveloper.html;

import java.io.PrintWriter;
import java.util.Vector;
import javax.servlet.ServletContext;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.servlet.http.HttpSession;
import javax.servlet.jsp.PageContext;
import oracle.jbo.AttributeDef;
import oracle.jbo.Row;
import oracle.jbo.RowSet;

/**
 * Defines the base methods for a Data Web Bean. Implement this interface when
 * you define a Web Bean that must access a data source.
 *
 */
public interface DataWebBean extends WebBean
{
  /**
  * <b>Internal:<b> <em>Applications should not use this method. </em>
  *<p>
  * Allows the override of the default RowSet that was retrieved by using the
  * <TT>initialize()</TT> function.
  * <P>
  * The <TT>setRowSet()</TT> function sets up the RowSet by clearing the
  * field renderers if the selected row is null, otherwise, it populates the row
  * with its field renderers.
  *
  * @param aQuery the RowSet to be selected.
  */
  public void setRowSet(RowSet aQuery);

  /**
   * Returns the RowSet of the View Object used by the Web Bean object.
   *	@return the RowSet that the Data Web Bean is using.
   */
	public RowSet getRowSet();

    /**
    * Returns the name of the Application Module's property file. The
    * property file typically contains this information:
    * <ul>
    *  <li>database connection mode and password</li>
    *  <li>name and path of the cascading style sheet associated with the
           application</li>
    *  <li>name and path of the directory where images associated with the
    *      application can be stored</li>
    *  <li>Application Module's name</li>
    *  <li>whether the Application Module is stateful</li>
    *  <li>JNDI path</li>
    *  </ul>
    * <p>
    * @return the name of the Application Module's property file.
    */
    public String getApplicationName();

    /**
    *   Returns the name of the View Object to which this Data Web Bean is bound.
    * <p>
    * @return name of the View Object.
    */
    public String getViewObjectName();

    /**
    * Enables or disables the release of application resources associated
    * with this request. Only the last Data Web Bean on
    * a page should set this value to <TT>true</TT> because it releases the Application
    * Module that is associated
    * with the page being processed.
    * <p>
    * @param bRelease <TT>true</TT> to release application resources associated with the
    * request; <TT>false</TT> to retain the resources.
    */
    public void setReleaseApplicationResources(boolean bRelease);

  /**
   * Initializes this Data Web Bean object to:
   * <ul>
   * <li>Access the important objects of the JSP: application, session,
   * request, response, and out.</li>
   *
   * <li>Connect to a database through an Application Module and access a data
   * source represented by one of the Application Module's View Objects. The
   * parameter<TT> sRowSet</TT> provides the necessary information, specifying a
   * properties file generated by the Web Application Wizard and a View Object.
   * The properties file contains the name of an Application Module and a
   * database connnect string. The View Object must be associated
   * with the Application Module.</li>
   * </ul>
   * <p>
   * @param application    the JSP page's ServletContext.
   * @param session        the JSP page's HttpSession.
   * @param request        the JSP page's HttpServletRequest.
   * @param response       the JSP page's HttpServletResponse.
   * @param out            the PrintWriter to render to.
   * @param sRowSet        a string that specifies a Business Component JSP
   *                       Application's properties file and a View Object.
   *                       Its format is <em>properties file</em>.<em>View Object</em>
   *                       where <em>properties file</em> is the name of the
   *                       properties file without the <TT>.properties</TT> extension
   *                       and <em>View Object</em> is the name of a View Object
   *                       associated with the Application Module specified in
   *                       the properties file.
   */
	public void initialize(ServletContext appContext, HttpSession session , HttpServletRequest request, HttpServletResponse response, PrintWriter out, String sRowSet)  throws Exception;

   
  /**
   * Initializes this Data Web Bean object to:
   * <ul>
   * <li>Access the page object of the JSP.</li>
   *
   * <li>Connect to a database through an Application Module and access a data
   * source represented by one of the Application Module's View Objects. The
   * parameter <TT>sRowSet</TT> provides the necessary information, specifying a
   * properties file generated by the Web Application Wizard and a View Object.
   * The properties file contains the name of an Application Module and a
   * database connnect string. The View Object must be one of those associated
   * with the Application Module.</li>
   * </ul>
   *
   * @param page           the JSP page's PageContext.
   * @param sRowSet        a string that specifies a Business Component JSP
   *                       Application's properties file and a View Object.
   *                       Its format is <em>properties file</em>.<em>View Object</em>
   *                       where <em>properties file</em> is the name of the
   *                       properties file without the <TT>.properties</TT> extension
   *                       and <em>View Object</em> is the name of a View Object
   *                       associated with the Application Module specified in
   *                       the properties file.
   */
   public void initialize(PageContext page, String sRowSet) throws Exception;

   /**
	*	Clears the list of display attributes specified for the RowSet. The result
	* is that the Web Bean will now display all
	* of the RowSet's attributes.
	*/

   public void clearDisplayAttributes();

   /**
   * Sets the list of the RowSet's attributes that will be displayed. This is
   * useful for limiting the set of attributes that are
   * to be displayed by the Web Bean. If this function is not called, all attributes are
   * displayed, except those of type <tt>Row</tt> and <tt>RowSet</tt>.
   * <p>
   * Specify the attributes as a comma-delimited list. For example, to display the
   * attributes EmpNo, Ename, and Job, enter <tt>setDisplayAttributes("EmpNo,
   * Ename, Job")</tt>.
   * <p>
   * @param sAttrs names of the attributes to be displayed.
   */
   public void setDisplayAttributes(String sAttrs);

   /**
   * Returns a Hashtable containing the names of the attributes to be displayed. This
   * function can return <tt>null</tt>.
   *	<p>
   * @return a Vector containing the names of the attributes to be displayed.
   */
   public Vector getDisplayAttributes();

   /**
   *
   *  Returns an array of AttributeDef objects representing the set of columns to be visualized.
   *
   */
   public AttributeDef[]  getDisplayAttributeDefs();
   
      /**
   *	Checks whether an attribute should be displayed by a Web Bean. This function returns
   * <tt>false</tt> if the attribute:
   * <p>
   * <ul>
   *    <li>of type <tt>Row</tt> or <tt>RowSet</tt>.</li>
   *    <li>is not in the Display Attribute List as configured with the
   *        <tt>setDisplayAttributes()</tt> function.</li>
   * </ul>
   * <p>
   * In either of these cases, the attribute will not be displayed.
   * <p>
   * Note, if the <tt>setDisplayAttributes()</tt> function has not been called, all
   * attributes are displayed
   * except <tt>Row</tt> or <tt>RowSet</tt> attributes.
   */
   public boolean shouldDisplayAttribute(AttributeDef attrDef);

	/**
	**	Returns true if you are running in statefule mode
	**/
	public boolean isAppStateful();

	/**
	** Handles commit logic properly reagrdles of stateful/stateless runtime mode.
	** Call this function after you make any data changes.
	**/
   public void handleCommit() throws Exception;

   /**
   * Retrieves the default field renderer for a specified attribute definition
   * (that is, the attribute metadata).
   * <p>
   * @param attrDef an attribute definition.
   * @return default field renderer for the attribute definition.
   */
   public HTMLFieldRenderer getEditFieldRenderer(Row row, AttributeDef attrDef);

   /**
   * Retrieves the default field renderer for a specified attribute definition
   * (that is, the attribute metadata).
   * <p>
   * @param attrDef an attribute definition.
   * @return default field renderer for the attribute definition.
   */
   public HTMLFieldRenderer getDisplayFieldRenderer(Row row, AttributeDef attrDef);

   /**
   **  Assigns an instance-level display field renderer to be used in the DataWebBean
   **/
   public void setDisplayFieldRenderer(AttributeDef attrDef, HTMLFieldRenderer rdr);

   /**
   **  Assigns an instance-level edit field renderer to be used in the DataWebBean
   **/
   public void setEditFieldRenderer(AttributeDef attrDef, HTMLFieldRenderer rdr);

    /**
   **  Assigns an instance-level display field renderer to be used in the DataWebBean
   **/
   public void setDisplayFieldRenderer(int nIndex, HTMLFieldRenderer rdr);

   /**
   **  Assigns an instance-level edit field renderer to be used in the DataWebBean
   **/
   public void setEditFieldRenderer(int nIndex, HTMLFieldRenderer rdr);

}
