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

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

/**
 * {@link EncodedData}に{@link Encodable}を書き込むためのハンドル.
 * 書き込みは以下の手順で行なう．
 * <ol>
 * <li> {@link EncodedData#getEncoder()}でEncoderを生成する．
 * <li> {@link #prepare(Encodable)}で書き込む予定のデータサイズを通知する．
 * <li> {@link #finishPrepare()}でprepareフェーズを終了し，バッファを割り付ける．
 * <li> {@link #encode(Encodable)}でデータをバッファに書き込む．
 * <li> {@link #finishEncode()}で書き込みを終了する．
 * </ol>
 * 上の手順を終了した時点で，EncodedDataは送信して良い状態になる．
 * 上の手順は，1つのEncodedDataに対して何度繰り返しても良い．
 */

public interface Encoder {

  /**
   * EncodedDataに書き込む予定のデータを通知する.
   * @param data 書き込む予定のデータ
   */
  public void prepare(Encodable data);

  /**
   * データサイズの通知を終了し，バッファを割り付ける.
   * このメソッドを呼び出すと，{@link #encode}を呼び出せる状態になる．
   * @see #prepare
   * @see encode
   */
  public void finishPrepare();

  /**
   * 指定した大きさの送信用バッファを割り付ける.
   * 同じ大きさのオブジェクトの配列を送信する場合に用いる．
   * {@link Encodable}で指定したサイズをsize個ぶん繰り返した大きさの
   * バッファを割り付ける．
   *
   * @param decoder 1つの要素の大きさを指定するEncodable
   * @param size 要素数
   * @see #finishPrepare
   */
  public void allocate(Encodable data, int size);
  /**
   * バッファにデータを1つ書き込む.
   * {@link #finishPrepare()}を読んだ後に呼び出さねばならない.
   */
  public void encode(Encodable data);

  /**
   * 書き込みを終了する.
   * このメソッドを呼び出すと，{@link EncodedData#getArray}で配列を
   * 取り出せる状態になる.
   */
  public void finishEncode();
}
