/*
 * The Apache Software License, Version 1.1
 *
 * Copyright (c) 1999 The Apache Software Foundation.  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. The end-user documentation included with the redistribution, if
 *    any, must include the following acknowlegement:  
 *       "This product includes software developed by the 
 *        Apache Software Foundation (http://www.apache.org/)."
 *    Alternately, this acknowlegement may appear in the software itself,
 *    if and wherever such third-party acknowlegements normally appear.
 *
 * 4. The names "The Jakarta Project", "Tomcat", and "Apache Software
 *    Foundation" must not be used to endorse or promote products derived
 *    from this software without prior written permission. For written 
 *    permission, please contact apache@apache.org.
 *
 * 5. Products derived from this software may not be called "Apache"
 *    nor may "Apache" appear in their names without prior written
 *    permission of the Apache Group.
 *
 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED 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 APACHE SOFTWARE FOUNDATION OR
 * ITS 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.
 * ====================================================================
 *
 * This software consists of voluntary contributions made by many
 * individuals on behalf of the Apache Software Foundation.  For more
 * information on the Apache Software Foundation, please see
 * <http://www.apache.org/>.
 *
 */ 

package javax.servlet.jsp.jstl.core;

/**
 * <p>反復の現在の状態を表現するオブジェクトのためのインタフェースを提供します．
 * JSTL 1.0 は LoopTags のためのメカニズムを提供します．このメカニズムは，
 * 反復における現在のインデックスについての情報と，現在の回が反復の開始か最後かを
 * 判定するのに便利なメソッドとを提供します．
 * また，LoopTagStatusの実装者が反復の範囲，増分，現在のオブジェクトに関する情報を得るために
 * status object を使用することができます．
 * </p>
 *
 * <p>さらに多くの状態をもつ環境はこのインタフェースを継承して実現できます．</p>
 *
 * @author Shawn Bayern
 */

public interface LoopTagStatus {

    /**
     * 反復における現在のアイテムを取り出します．等冪な振る舞い;
     * getCurrent()を繰り返し呼び出すと反復が進まない限り同じObjectを返します．
     * (明確に言えば，getCurrent()を呼ぶことは、反復を進め<b>ません</b>．)
     *
     * @return 現在のアイテム(object)
     */
    public Object getCurrent();

    /**
     * 反復の現在の回におけるインデックスを取り出します．
     * もし反復が本質的な配列, 
     * java.lang.Collection, もしくは他の型, の部分集合上で実行されている場合は，
     * 返されるインデックスは，本質的なコレクション内の絶対的な位置です．
     * <font color="red">(訳注：getCountと比較して下さい)</font>
     * インデックスは0から始まります．
     *
     * @return 現在の反復のインデックス(インデックスは0から始まる)
     */
    public int getIndex();

    /**
     * <p>反復の現在の回の "count" を取り出します．
     * countは相対的な値です．1から始まる連続のシーケンス番号です．この番号は現在の反復の"round"を一意にします．
     * (すべてのroundsにおけるコンテキスト内では現在の反復は実行するでしょう).</p>
     *
     * <p>例としては，begin = 5, end = 15, step = 5 で指定された反復においては，
     * count は順番に 1, 2, 3, ... となります．</p>
     *
     * @return 現在まで反復した回数(回数は1から始まる)
     */
    public int getCount();

    /**
     * 現在の反復の回が最初の回であるかに関する情報を返します．
     * この現在の回は getIndex() != 0 の時でさえも，'first' です．
     * なぜなら，'index' は，
     * その本質的なコレクションにあるコンテキストの現在の 'item'の絶対的なインデックス
     * を参照しているからです．
     * isFirst() の結果が true ということは，getCount() == 1 であることを暗黙的に意味します.
     * 
     * @return 現在の回が反復の開始のときは<tt>true</tt>，それ以外は<tt>false</tt>．
     */
    public boolean isFirst();

    /**
     * 現在の反復の回が最後の回であるかに関する情報を返します．
     * isFirst()と同様，部分集合化は考慮されます．
     * isLast()は必ずしもunderlying反復の状態を問い合わせるとは限りません;
     * isLast()は現在の回がこのLoopTagStatusと関連するタグにとって最終回の反復であるか否かを問い合わせます．
     * 
     * @return 現在の回が最後の反復のときは<tt>true</tt>，それ以外は<tt>false</tt>．
     */
    public boolean isLast();

    /**
     * 関連するタグのための 'begin' 値．'begin'属性が指定されていない場合は nullを返します．
     *
     * @return 関連するタグのための 'begin' 値．'begin'属性が指定されていない場合は null
     */
    public Integer getBegin();

    /**
     * 関連するタグのための 'end' 値, 'end'属性が指定されていない場合は nullを返します．
     *
     * @return 関連するタグのための 'end' 値．'end'属性が指定されていない場合は null
     */
    public Integer getEnd();

    /**
     * 関連するタグのための 'step' 値．'step'属性が指定されていない場合は nullを返します．
     *
     * @return 関連するタグのための 'step' 値． 'step'属性が指定されていない場合は null
     */
    public Integer getStep();
}