/*
 * $Header: /home/cvs/struts/xdocs/struts1.2/documentation/ja/src/share/org/apache/struts/action/ActionForm.java,v 1.11 2005/04/01 16:51:32 tatakaha Exp $
 * $Revision: 1.11 $
 * $Date: 2005/04/01 16:51:32 $
 *
 * Copyright 2000-2004 The Apache Software Foundation.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *      http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.apache.struts.action;


import java.io.Serializable;
import javax.servlet.ServletRequest;
import javax.servlet.http.HttpServletRequest;

import org.apache.struts.upload.MultipartRequestHandler;


/**
 * <p><strong>ActionForm</strong>は、
 * 1つ以上の<code>ActionMapping</code>に任意に関連づけることのできるJavaBeanです。
 * このBeanのプロパティは、対応する<code>Action.execute</code>メソッドが呼び出される前に、
 * 対応するリクエストパラメータで初期化されます。</p>
 * {@primary <p>An <strong>ActionForm</strong> is a JavaBean optionally associated with
 * one or more <code>ActionMappings</code>. Such a bean will have had its
 * properties initialized from the corresponding request parameters before
 * the corresponding <code>Action.execute</code> method is called.</p>}
 *
 * <p>Beanのプロパティが設定された後、
 * <code>Action</code>の<code>execute</code>メソッドが呼び出される前に、
 * このBeanの<code>validate</code>メソッドが呼び出されます。
 * これはユーザが送信したプロパティが正しくて妥当であるかを確かめる機会をBeanに与えます。
 * このメソッドで問題が見つかった場合、
 * 問題をカプセル化したエラーメッセージオブジェクトを返し、
 * コントローラサーブレットは対応する入力フォームに制御を戻します。
 * また、全てのプロパティが条件に合っていて、
 * 対応する<code>Action.execute</code>メソッドが呼び出されるべきである場合は、
 * <code>validate</code>メソッドは<code>null</code>を返します。</p>
 * {@primary <p>When the properties of this bean have been populated, but before the
 * <code>execute</code> method of the <code>Action</code> is called, this bean's
 * <code>validate</code> method will be called, which gives the bean a chance
 * to verify that the properties submitted by the user are correct and valid.
 * If this method finds problems, it returns an error messages object that
 * encapsulates those problems, and the controller servlet will return control
 * to the corresponding input form. Otherwise, the <code>validate</code>
 * method returns <code>null</code>, indicating that everything is acceptable
 * and the corresponding <code>Action.execute</code> method should be
 * called.</p>}
 *
 * <p>このクラスをインスタンス化するためにサブクラスを作成する必要があります。
 * サブクラスは公開したい全てのBeanプロパティでgetterメソッドとsetter メソッドを提供し、
 * さらににpublicメソッドやprotectedメソッドを機能の変更に応じてオーバライドすべきです。
 * </p>
 * {@primary <p>This class must be subclassed in order to be instantiated. Subclasses
 * should provide property getter and setter methods for all of the bean
 * properties they wish to expose, plus override any of the public or
 * protected methods for which they wish to provide modified functionality.
 * </p>}
 *
 * <p>ActionFormはJavaBeanですので、
 * サブクラスもJavaBean仕様を満たすように<code>Serializable</code>を実装すべきです。
 * コンテナによっては、
 * ActionFormが依存しているイントロスペクションAPIを用いるために、
 * オブジェクトがJavaBeanの全ての要件を満たすことが要求されます。</p>
 * {@primary <p>Because ActionForms are JavaBeans, subclasses should also implement
 * <code>Serializable</code>, as required by the JavaBean specification.
 * Some containers require that an object meet all JavaBean requirements
 * in order to use the introspection API upon which ActionForms rely.</p>}
 *
 * @version $Revision: 1.11 $ $Date: 2005/04/01 16:51:32 $
 * @translator 横田 健彦
 * @translator 棚澤 昌幸
 * @editor 高橋 達男
 * @status completion
 * @update 2005/03/21
 * @memo ブロックA
 */

public abstract class ActionForm implements Serializable {


    // ----------------------------------------------------- Instance Variables


    /**
     * <p>関連づけられているサーブレットのインスタンス。</p>
     * {@primary <p>The servlet instance to which we are attached.</p>}
     */
    protected transient ActionServlet servlet = null;


    /**
     * <p>このフォームのMultipartRequestHandler。
     * <code>null</code>のこともあります。</p>
     * {@primary <p>The MultipartRequestHandler for this form, can be
     * <code>null</code>.</p>}
     */
    protected transient MultipartRequestHandler multipartRequestHandler;


    // ------------------------------------------------------------- Properties


    /**
     * <p>関連づけられているサーブレットのインスタンスを返します。</p>
     * {@primary <p>Return the servlet instance to which we are attached.</p>}
     */
    protected ActionServlet getServlet() {

        return (this.servlet);

    }


    /**
     * <p>関連づけられているサーブレットのインスタンスを<code>ActionServletWrapper</code>として返します。</p>
     * {@primary <p>Return the controller servlet instance to which we are attached.
     * as an <code>ActionServletWrapper</code>.</p>}
     *
     * @see org.apache.struts.action.ActionServletWrapper
     * @since Struts 1.0.1
     */
    public ActionServletWrapper getServletWrapper() {

        return new ActionServletWrapper(getServlet());

    }


    /**
     * <p>このフォームの<code>MultipartRequestHandler</code>を返します。
     * この背景にある理由は、
     * <code>MultipartRequestHandler</code>の<code>finish</code>メソッドと<code>rollback</code>
     * メソッドのどちらか、または両方を使用することによって、
     * フォームBeanの開発者がマルチパートのリクエストのライフサイクルを操作できるようにするためです。
     * このフォームのenctypeが"multipart/form-data"でない場合はこのメソッドは<code>null</code>を返します。</p>
     * {@note "multipart/form-data"が正しいです。Bug#33619}
     * {@primary <p>Return the <code>MultipartRequestHandler</code> for this form
     * The reasoning behind this is to give form bean developers
     * control over the lifecycle of their multipart requests
     * through the use of the <code>finish</code> and/or <code>rollback</code>
     * methods of <code>MultipartRequestHandler</code>.  This method will return
     * <code>null</code> if this form's enctype is not
     * "multipart/request-data".</p>}
     *
     * @see org.apache.struts.upload.MultipartRequestHandler
     */
    public MultipartRequestHandler getMultipartRequestHandler() {
        return multipartRequestHandler;
    }


    /**
     * <p>(<code>servlet</code>がnullでない場合は)
     * 関連づけられているサーブレットのインスタンスをセットします。
     * (<code>servlet</code>がnullである場合は) 割り当てられた全てのリソースを解放します。
     * </p>
     * {@primary <p>Set the servlet instance to which we are attached (if
     * <code>servlet</code> is non-null), or release any allocated resources
     * (if <code>servlet</code> is null).</p>}
     *
     * @param servlet もしあれば、新しいコントローラサーブレット
     * {@primary servlet The new controller servlet, if any}
     */
    public void setServlet(ActionServlet servlet) {

        this.servlet = servlet;
            // :FIXME: Should this be releasing resources?

    }


    /**
     * <p>ファイルアップロードの処理に使うために提供されるHandlerを設定します。
     * {@note provides toはprovided forが正しいです。Bug#33612}
     * {@primary <p>Set the Handler provides to use in dealing with file uploads.</p>}
     *
     * @param multipartRequestHandler   ファイルアップロードに使用するHandler
     * {@primary multipartRequestHandler The Handler to use for fileuploads.}
     */
    public void setMultipartRequestHandler(MultipartRequestHandler multipartRequestHandler) {

        this.multipartRequestHandler = multipartRequestHandler;

    }

    // --------------------------------------------------------- Public Methods


    /**
     * <p>Beanの全てのプロパティをデフォルトの状態にリセットします。
     * このメソッドはコントローラがプロパティを再設定する前に呼び出されます。</p>
     * {@primary <p>Reset all bean properties to their default state.  This method is
     * called before the properties are repopulated by the controller.</p>}
     *
     * <p>デフォルトの実装はこのメソッドのHTTPバージョンにフォワードします。</p>
     * {@primary <p>The default implementation attempts to forward to the HTTP
     * version of this method.</p>}
     *
     * @param mapping このインスタンスを選択するために用いられたマッピング
     * {@primary mapping The mapping used to select this instance}
     * @param request 処理中のサーブレットリクエスト
     * {@primary request The servlet request we are processing}
     */
    public void reset(ActionMapping mapping, ServletRequest request) {

        try {
            reset(mapping, (HttpServletRequest) request);
        } catch (ClassCastException e) {
            ;//FFIXME: Why would this every happen except a null
        }

    }


    /**
     * <p>Beanの全てのプロパティを必要に応じてデフォルトの状態にリセットします。
     * このメソッドはコントローラがプロパティを再設定する前に呼び出されます。</p>
     * {@primary <p>Reset bean properties to their default state, as needed.  This method is
     * called before the properties are repopulated by the controller.</p>}
     *
     * <p>デフォルトの実装は何もしません。
     * 実際に使う場合、
     * リセットが必要なプロパティはセッションスコープのフォームにあるチェックボックスだけです。
     * 別の方法として、プロパティはフィールドの宣言時に初期値を設定できます。</p>
     * {@primary <p>The default implementation does nothing. In practice, the only properties
     * that need to be reset are those which represent checkboxes on a session-scoped
     * form. Otherwise, properties can be given initial values where the field is
     * declared. </p>}
     *
     * <p>もし複数のリクエストにわたって値を集められるように(「ウィザード」形式)
     * フォームをセッションスコープに格納する場合、プロパティをリセットするのなら、
     * どのプロパティをリセットするかに十分に注意しなければいけません。
     * 上述の通り、セッションスコープのチェックボックスは、
     * プロパティを設定するどのページでもfalseにリセットしなければなりません。
     * これは、チェックボックスがクリアされた(false)時には値を送信しないためです。
     * セッションスコープのチェックボックスは、事前にリセットしない限り
     * falseに設定されることはありません。
     * </p>
     * {@primary <p>If the form is stored in session-scope so that values can be collected
     * over multiple requests (a "wizard"), you must be very careful of which
     * properties, if any, are reset. As mentioned, session-scope checkboxes
     * must be reset to false for any page where this property is set. This is
     * because the client does not submit a checkbox value when it is clear (false).
     * If a session-scoped checkbox is not proactively reset, it can never be set
     * to false.</p>}
     *
     * <p>「更新」タイプのページに関しては、
     * フォームの値を初期化する場所として、このメソッドは<strong>ふさわしくありません</strong>
     * (値の初期化はセットアップ用のActionの中で行なうべきです)。
     * たいていの場合にチェックボックスの値がfalseに設定されているかを気にする必要はありますが、
     * ほとんどの場合はこのメソッドを実装しないでおいて構いません。
     * </p>
     * {@primary <p>This method is <strong>not</strong> the appropriate place to initialize
     * form value for an "update" type page (this should be done in a setup Action).
     * You mainly need to worry about setting checkbox values to false; most of the
     * time you can leave this method unimplemented.
     * </p>}
     *
     * @param mapping このインスタンスを選択するために用いられたマッピング
     * {@primary mapping The mapping used to select this instance}
     * @param request 処理中のサーブレットリクエスト
     * {@primary request The servlet request we are processing}
     */
    public void reset(ActionMapping mapping, HttpServletRequest request) {

        ;       // Default implementation does nothing

    }


    /**
     * <p>非HTTPリクエストにセットされているプロパティの妥当性を検証して、
     * 見つかった全ての検証エラーをカプセル化した<code>ActionErrors</code>オブジェクトを返します。
     * エラーが見つからなかった場合、
     * <code>null</code>もしくは、
     * エラーメッセージが何も記録されていない<code>ActionErrors</code>オブジェクトを返します。</p>
     * {@primary <p>Validate the properties that have been set for this non-HTTP request,
     * and return an <code>ActionErrors</code> object that encapsulates any
     * validation errors that have been found. If no errors are found, return
     * <code>null</code> or an <code>ActionErrors</code> object with no
     * recorded error messages.</p>}
     *
     * <p>デフォルトの実装はこのメソッドのHTTPバージョンにフォワードします。</p>
     * {@primary <p>The default implementation attempts to forward to the HTTP version of
     * this method.</p>}
     *
     * @param mapping このインスタンスを選択するために用いられたマッピング
     * {@primary mapping The mapping used to select this instance}
     * @param request 処理しているサーブレットリクエスト
     * {@primary request The servlet request we are processing}
     */
    public ActionErrors validate(ActionMapping mapping,
                                 ServletRequest request) {

        try {
            return (validate(mapping, (HttpServletRequest) request));
        } catch (ClassCastException e) {
            return (null);
        }

    }


    /**
     * <p>HTTPリクエストにセットされているプロパティの妥当性を検証して、
     * 見つかった全ての検証エラーをカプセル化した<code>ActionErrors</code>オブジェクトを返します。
     * エラーが見つからなかった場合、
     * <code>null</code>もしくは、
     * エラーメッセージが何も記録されていない<code>ActionErrors</code>オブジェクトを返します。</p>
     * {@primary <p>Validate the properties that have been set for this HTTP request,
     * and return an <code>ActionErrors</code> object that encapsulates any
     * validation errors that have been found. If no errors are found,
     * return <code>null</code> or an <code>ActionErrors</code> object with
     * no recorded error messages.</p>}
     *
     * <p>デフォルトの実装は何の検証も行なわずに<code>null</code>を返します。
     * サブクラスは独自の妥当性の検証を行なうためにこのメソッドをオーバライドしなくてはいけません。</p>
     * {@primary <p>The default implementation performs no validation and returns
     * <code>null</code>. Subclasses must override this method to provide
     * any validation they wish to perform.</p>}
     *
     * @see DynaActionForm
     *
     * @param mapping このインスタンスを選択するために用いられたマッピング
     * {@primary mapping The mapping used to select this instance}
     * @param request 処理しているサーブレットリクエスト
     * {@primary request The servlet request we are processing}
     */
    public ActionErrors validate(ActionMapping mapping,
                                 HttpServletRequest request) {

        return (null);

    }


}