zkoss/zk

/* ActionContext.java

    Purpose:
        
    Description:
        
    History:
        Tue Sep  6 09:30:59     2005, Created by tomyeh

Copyright (C) 2005 Potix Corporation. All Rights Reserved.

{{IS_RIGHT
    This program is distributed under LGPL Version 2.1 in the hope that
    it will be useful, but WITHOUT ANY WARRANTY.
}}IS_RIGHT
*/
package org.zkoss.web.servlet.dsp.action;

import java.io.IOException;
import java.io.Writer;
import java.util.Map;

import org.zkoss.web.servlet.dsp.DspException;

/**
 * Encapsulates a portion of DSP page in an object that can be invoked
 * as many times as needed.
 *
 * @author tomyeh
 */
public interface ActionContext {
    /** The page scope. */
    public static final int PAGE_SCOPE = 0;
    /** The request scope. */
    public static final int REQUEST_SCOPE = 1;
    /** The session scope. */
    public static final int SESSION_SCOPE = 2;
    /** The application scope. */
    public static final int APPLICATION_SCOPE = 3;

    /** Returns the attribute of the specified scope.
     * @param scope one of {@link #PAGE_SCOPE}, {@link #REQUEST_SCOPE},
     * {@link #SESSION_SCOPE} and {@link #APPLICATION_SCOPE}.
     */
    public Object getAttribute(String name, int scope);

    /** Sets the attribute of the specified scope.
     * @param scope one of {@link #PAGE_SCOPE}, {@link #REQUEST_SCOPE},
     * {@link #SESSION_SCOPE} and {@link #APPLICATION_SCOPE}.
     */
    public void setAttribute(String name, Object value, int scope);

    /** Removes the attribute of the specified scope.
     * @param scope one of {@link #PAGE_SCOPE}, {@link #REQUEST_SCOPE},
     * {@link #SESSION_SCOPE} and {@link #APPLICATION_SCOPE}.
     */
    public void removeAttribute(String name, int scope);

    /** Finds the attribute from page, request, session to application scope
     */
    public Object findAttribute(String name);

    /** Sets the content type.
     */
    public void setContentType(String ctype);

    /** Returns the current output.
     */
    public Writer getOut() throws IOException;

    /** Returns the parent action, or null if no parent at all.
     */
    public Action getParent();

    /** Renders the nested fragment.
     *
     * @param out the output. If null, {@link #getOut} is assumed.
     */
    public void renderFragment(Writer out) throws DspException, IOException;

    /** Includes the specified URI and render the result to the specified
     * output.
     *
     * @param uri the URI to include. It is OK to relevant (without leading
     * '/'). If starts with "/", the context path of request is assumed.
     * To reference to foreign context, use "~ctx/" where ctx is the
     * context path of the foreign context (without leading '/').
     * @param params a map of parameters, or null to ignore.
     * The map is passed thru the request attribute called arg.
     */
    public void include(String uri, Map<?, ?> params) throws DspException, IOException;

    /** Returns whether this page is included.
     * @since 3.0.6
     */
    public boolean isIncluded();

    /** Encodes the specified URI.
     * <p>In additions, if uri starts with "/", the context path, e.g., /we2,
     * is prefixed.
     * In other words, "/ab/cd" means it is relevant to the servlet
     * context path (say, "/we2").
     *
     * <p>If uri starts with "~abc/", it means it is relevant to a foreign
     * context called /abc. And, it will be converted to "/abc/" first
     * (without prefix request.getContextPath()).
     *
     * <p>Finally, the uri is encoded by HttpServletResponse.encodeURL.
     */
    public String encodeURL(String uri) throws DspException, IOException;

    /** Returns the line number of this action.
     * It is used for throwing exception and debug purpose.
     */
    public int getLineNumber();
}