/* GenericFilter.java


	Purpose: A generic class to help implementing servlet filter
	Description: 
	History:
		2001/11/13 14:46:46, Create, Tom M. Yeh.

Copyright (C) 2001 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;

import java.util.Enumeration;
import java.util.Map;

import javax.servlet.Filter;
import javax.servlet.FilterConfig;
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.web.servlet.http.Https;

/**
 * A generic class to help implementing servlet filter.
 * Its role is like javax.servlet.GenericServlet to javax.servlet.Servlet.
 *
 * @author tomyeh
 */
public abstract class GenericFilter implements Filter {
	protected FilterConfig _config;

	protected GenericFilter() {
	}

	//-- extra API --//
	/** A convenience method which can be overridden so that there's
	 * no need to call super.init(config).
	 * @see #init(FilterConfig)
	 */
	protected void init() throws ServletException {
	}
	
	/** Called by the web container to indicate to a filter that it is
	 * being placed into service.
	 * However, deriving class usually doesn't override this method
	 * but overriding {@link #init()}.
	 */
	public final void init(FilterConfig config) throws ServletException {
		_config = config;
		init();
	}

	/** Returns a String containing the value of the named initialization
	 * parameter, or null if the parameter does not exist.
	 */
	public final String getInitParameter(String name) {
		return _config.getInitParameter(name);
	}

	/** Returns a String containing the value of the named initialization
	 * parameter, or null if the parameter does not exist.
	 */
	public final Enumeration getInitParameterNames() {
		return _config.getInitParameterNames();
	}

	/** Returns the filter's name.
	 */
	public final String getFilterName() {
		return _config.getFilterName();
	}

	/** Returns the servlet context in which this filter is running.
	 */
	public final ServletContext getServletContext() {
		return _config.getServletContext();
	}

	/**
	 * Redirects to another page. Note: it supports only HTTP.
	 *
	 * <p>It resolves "*" contained in URI, if any, to the proper Locale,
	 * and the browser code.
	 * Refer to {@link Servlets#locate(ServletContext, ServletRequest, String, Locator)}
	 * for details. 
	 *
	 * @param page the page's uri; null to denote the same request
	 * @param mode one of {@link Servlets#OVERWRITE_URI}, {@link Servlets#IGNORE_PARAM},
	 * and {@link Servlets#APPEND_PARAM}. It defines how to handle if both uri
	 * and params contains the same parameter.
	 * mode is used only if both uri contains query string and params is
	 * not empty.
	 */
	protected void sendRedirect(HttpServletRequest request, HttpServletResponse response, String page, Map params,
			int mode) throws ServletException, java.io.IOException {
		Https.sendRedirect(getServletContext(), request, response, page, params, mode);
	}

	/** Forward to the specified page.
	 *
	 * <p>It resolves "*" contained in URI, if any, to the proper Locale,
	 * and the browser code.
	 * Refer to {@link Servlets#locate(ServletContext, ServletRequest, String, Locator)}
	 * for details. 
	 * @since 3.6.3
	 */
	protected final void forward(ServletRequest request, ServletResponse response, String uri)
			throws ServletException, java.io.IOException {
		Https.forward(getServletContext(), request, response, uri, null, 0);
	}

	/** Forward to the specified page with parameters.
	 *
	 * <p>It resolves "*" contained in URI, if any, to the proper Locale,
	 * and the browser code.
	 * Refer to {@link Servlets#locate(ServletContext, ServletRequest, String, Locator)}
	 * for details. 
	 * @since 3.6.3
	 */
	protected final void forward(ServletRequest request, ServletResponse response, String uri, Map params, int mode)
			throws ServletException, java.io.IOException {
		Https.forward(getServletContext(), request, response, uri, params, mode);
	}

	/** Includes the specified page.
	 *
	 * <p>It resolves "*" contained in URI, if any, to the proper Locale,
	 * and the browser code.
	 * Refer to {@link Servlets#locate(ServletContext, ServletRequest, String, Locator)}
	 * for details. 
	 * @since 3.6.3
	 */
	protected final void include(ServletRequest request, ServletResponse response, String uri)
			throws ServletException, java.io.IOException {
		Https.include(getServletContext(), request, response, uri, null, 0);
	}

	/** Includes the specified page with parameters.
	 *
	 * <p>It resolves "*" contained in URI, if any, to the proper Locale,
	 * and the browser code.
	 * Refer to {@link Servlets#locate(ServletContext, ServletRequest, String, Locator)}
	 * for details. 
	 * @since 3.6.3
	 */
	protected final void include(ServletRequest request, ServletResponse response, String uri, Map params, int mode)
			throws ServletException, java.io.IOException {
		Https.include(getServletContext(), request, response, uri, params, mode);
	}

	//-- Filter --//
	/** Called by the web container to indicate to a filter that it is
	 * being taken out of service.
	 *
	 * <p>This implementation does nothing.
	 */
	public void destroy() {
	}
}