zkoss/zk

/* ExtendletContext.java

    Purpose:
        
    Description:
        
    History:
        Mon Aug 29 18:27:04     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.util.resource;

import java.io.IOException;
import java.io.InputStream;
import java.net.URL;
import java.util.Map;

import javax.servlet.RequestDispatcher;
import javax.servlet.ServletContext;
import javax.servlet.ServletException;
import javax.servlet.ServletRequest;
import javax.servlet.ServletResponse;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import org.zkoss.util.resource.Locator;

/**
 * This interface defines an extended context that
 * {@link org.zkoss.web.servlet.Servlets#getRequestDispatcher} will try to
 * resolve.
 * When {@link org.zkoss.web.servlet.Servlets#getRequestDispatcher} is
 * called, it detects whether ~xxx/ is specified.
 * If specified, it looks up any extended context
 * is registered as xxx. If found, the extend context is used.
 * If not found, it looks up any servlet context called xxx.
 *
 * <p>To registers an extended context, use 
 * {@link org.zkoss.web.servlet.Servlets#addExtendletContext}.
 *
 * @author tomyeh
 */
public interface ExtendletContext {
    /** Returns the encoded URL.
     * The returned URL is also encoded with HttpServletResponse.encodeURL.
     *
     * <p>It resolves "*" contained in URI, if any, to the proper Locale,
     * and the browser code.
     * Refer to {@link org.zkoss.web.servlet.Servlets#locate(javax.servlet.ServletContext, ServletRequest, String, org.zkoss.util.resource.Locator)}
     * for details. 
     *
     * @param uri it must be empty or starts with "/". It might contain
     * "*" for current browser code and Locale.
     * @return the complete URL (excluding the machine name).
     * It includes the context path and the servlet to interpret
     * this extended resource.
     */
    public String encodeURL(ServletRequest request, ServletResponse response, String uri)
            throws ServletException, IOException;

    /** Returns  the encoded URL for send redirect.
     * The URL is also encoded with HttpServletResposne.encodeRedirectURL.
     */
    public String encodeRedirectURL(HttpServletRequest request, HttpServletResponse response, String uri, Map params,
            int mode);

    /* Returns the request dispatcher that acts as a wrapper for
     * the resource located at the given path, or null if not found.
     */
    public RequestDispatcher getRequestDispatcher(String uri);

    /** Includes the specified page.
     *
     * <p>Note: if you want to include the content into a different
     * writer, you have to use {@link org.zkoss.web.servlet.BufferedResponse}
     * to 'wrap' the writer in the response.
     *
     * @since 3.5.2 
     */
    public void include(HttpServletRequest request, HttpServletResponse response, String uri, Map params)
            throws ServletException, IOException;

    /** Returns the URL of the specified URI, or null if not found.
     *
     * <p>Unlike {@link #getLocator}, {@link #getResourceAsStream}
     * handles the JavaScript debugging. In other words,
     * if the JavaScript debugging is turned on, it will try to load
     * the non-compressed version.
     */
    public URL getResource(String uri);

    /** Returns the resource of the specified URI as input stream,
     * or null if not found.
     *
     * <p>Unlike {@link #getLocator}, {@link #getResourceAsStream}
     * handles the JavaScript debugging. In other words,
     * if the JavaScript debugging is turned on, it will try to load
     * the non-compressed version.
     */
    public InputStream getResourceAsStream(String uri);

    /** Returns the servlet context.
     */
    public ServletContext getServletContext();

    /** Returns the locator of this context used to locate resources.
     *
     * <p>Unlike {@link #getResource} and {@link #getResourceAsStream},
     * {@link #getLocator} doesn't handle the JavaScript debugging.
     */
    public Locator getLocator();

    /** Tests whether to compress the specified extension, e.g, "js" and
     * "css".
     *
     * <p>It returns false if the request is included by other Servlets.
     */
    public boolean shallCompress(ServletRequest request, String ext);
}