// -*- mode: Java; file-coding-system: *euc-japan*; -*-
// $Id: Decoder.java,v 1.2 1999/09/22 07:27:07 maeda Exp $
// Copyright (C) 1999 MAEDA Atusi

package jp.ac.tohoku.is.archi.mpi2.util;

/**
 * {@link EncodedData}から{@link Encodable}を読み出すためのハンドル.
 * 読み出しは以下の手順で行なう．
 * <ol>
 * <li> {@link EncodedData#getDecoder()}でDecoderを生成する．
 * <li> {@link #prepare(ObjectDecoder)}で受信するデータサイズを通知する．
 * <li> {@link #finishPrepare()}でprepareフェーズを終了し，バッファを割り付ける．
 * <li> {@link EncodedData#getArray()}で得られるバッファにデータを受信する．
 * <li> {@link #decode(ObjectDecoder)}でデータをバッファから読み出す．
 * </ol>
 * 上で，{@link #prepare(Encodable)}と{@link #finishPrepare()}を用いて
 * 受信するデータサイズをセットするかわりに，{@link #allocate(int)}を用いて
 * 一気にバッファを割り付けても良い．
 */

public interface Decoder {
  /**
   * 受信する予定のデータを1つ通知する.
   * ObjectDecoderが正しくサイズを予測できる場合にのみ用いることができる．
   * @param od 受信する予定のデータをデコードできるObjectDecoder
   * @see #finishPrepare
   */
  public void prepare(ObjectDecoder od);

  /**
   * {@link prepare(ObjectDecoder)}を繰り返したのち，最後にこのメソッドを
   * 用いて受信用バッファを割り付ける．
   * @see #prepare
   * @see #allocate
   */
  public void finishPrepare();

  /**
   * 指定した大きさの受信用バッファを割り付ける.
   * 同じ大きさのオブジェクトの配列を受信する場合に用いる．
   * {@link ObjectDecoder}で指定したサイズをnelem個ぶん繰り返した大きさの
   * バッファを割り付ける．
   *
   * @param decoder 1つの要素の大きさを指定するObjectDecoder
   * @param nelem 要素数
   * @see #finishPrepare
   */
  public void allocate(ObjectDecoder decoder, int nelem);

  /**
   * 指定した大きさの受信用バッファを割り付ける.
   *
   * @param size バッファの大きさ(配列の要素数)
   * @see #finishPrepare
   */
  public void allocate(int size);

  /**
   * 受信し終えたバッファから，データを1つ読み出して返す.
   * @param od 次のデータをデコードできるObjectDecoder
   */
  public Object decode(ObjectDecoder od);
}
