/*
 * Copyright (c) 2003, Morpho Project.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 *	  this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 *	  this list of conditions and the following disclaimer in the documentation
 *	  and/or other materials provided with the distribution.
 * 3. Neither the name of the Morpho Project nor the names of its contributors
 *	  may be used to endorse or promote products derived from this software
 *	  without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */
package jp.morpho.webapp.action;

import jp.morpho.webapp.Plugin;

/**
 * <P>
 * フレームワークがクライアントからのリクエストを振り分ける際に使用するメソッド一式を定義します。
 * 例えばアクションハンドラやビューの取得といったメソッドです。
 * </P>
 * <P>
 * アクションマッピングマネージャの実装クラスはすべて、次の標準的なコンストラクタを提供するようにしてください。
 * 標準的なコンストラクタとは、void (引数なし) コンストラクタです。このコンストラクタは空のアクションマッピングを作成します。
 * </P>
 * @author Kenichi Fukuda
 */
public interface ActionMappingManager
	extends Plugin
{

	/**
	 * <P>
	 * 要求を処理するステータスのパラメータの名前を返します。
	 * </P>
	 * @return 要求を処理するステータスのパラメータの名前
	 */
	public String getStatusParameterName();

	/**
	 * <P>
	 * 要求を処理するアクションのパラメータの名前を返します。
	 * </P>
	 * @return 要求を処理するアクションのパラメータの名前
	 */
	public String getActionParameterName();

	/**
	 * <P>
	 * アクションハンドラチェインを返します。
	 * アクションハンドラチェインは、ActionMappingManager の getActionHandlers(servletPath, status, action) メソッドと getActionView(servletPath, status) メソッドを呼び出します。
	 * </P>
	 * @param servletPath アクションマッピングが対応する URL
	 * @param status 要求を処理するステータスの値
	 * @param action 要求を処理するアクションの値
	 * @return アクションハンドラチェイン
	 */
	public ActionHandlerChain getActionHandlerChain(
		String servletPath, String status, String action);

	/**
	 * <P>
	 * アクションハンドラの配列を返します。
	 * 返されたアクションハンドラの配列は、アクションハンドラチェインの doActionHandler メソッドで順に呼び出されます。
	 * </P>
	 * <P>
	 * このメソッドは、要求を処理するアクションハンドラを取得するために、アクションハンドラチェインから呼び出されます。
	 * </P>
	 * @param servletPath アクションマッピングが対応する URL
	 * @param status 要求を処理するステータスの値
	 * @param action 要求を処理するアクションの値
	 * @return アクションハンドラの配列
	 * @exception ActionMappingNotFoundException クライアントから呼び出されたサーブレットの URL 、ステータス、アクションを使用してアクションマッピングを取得しようとしたが、対応するアクションマッピングの定義が見つからなかった場合
	 */
	public ActionHandler[] getActionHandlers(
		String servletPath, String status, String action)
		throws ActionMappingNotFoundException;

	/**
	 * <P>
	 * アクションビューのパス (JSP など) を返します。
	 * アクションビューは、アクションハンドラチェインの doActionHandler メソッドで、アクションハンドラが呼び出された後、応答にインクルードされます。
	 * </P>
	 * <P>
	 * ステータスの値は、アクションハンドラで変更されることがあるため、サーブレットが要求を受け取った時の値と必ずしも一致しません。
	 * このメソッドは、アクションハンドラチェインの doActionHandler メソッドで、すべてのアクションハンドラが実行された後に呼び出されます。
	 * </P>
	 * @param servletPath アクションマッピングが対応する URL
	 * @param status 要求を処理するステータスの値
	 * @return アクションビューのパス
	 * @exception ActionMappingNotFoundException クライアントから呼び出されたサーブレットの URL 、ステータスを使用してアクションマッピングを取得しようとしたが、対応するアクションマッピングの定義が見つからなかった場合
	 */
	public String getActionView(
		String servletPath, String status)
		throws ActionMappingNotFoundException;
}
