package jp.cssj.cti;

import java.io.IOException;
import java.io.OutputStream;

import jp.cssj.cti.helpers.ErrorHandler;
import jp.cssj.cti.helpers.ProgressListener;

/**
 * <p>
 * サーバーと一連の変換を実行するための、ステートフルなセッションです。
 * <p>
 * 1つのセッションで生成できるのは1つの結果のみです。
 * <p>
 * データの送信はストリームを介して行います。 ファイルなどを簡単に送信するためのユーティリティはCTIUtilsで提供しています。
 * 
 * <p>
 * <i>将来のバージョンでは、一度に複数の結果を生成するために、Keep-Aliveをサポートする可能性があります。 </i>
 * 
 * @author <a href="mailto:miyabe at gnn.co.jp">MIYABE Tatsuhiko </a>
 * @version $Id: CTISession.java,v 1.2 2005/08/18 04:51:26 harumanx Exp $
 */
public interface CTISession {
	/**
	 * <p>
	 * 出力先を設定します。
	 * 
	 * <p>
	 * このメソッドは本体の開始前に呼ぶ必要があります。
	 * 一度も呼ばない場合、出力先はSystem.out,出力タイプは"application/pdf"になります。
	 * 
	 * @param out
	 *            出力先ストリーム
	 * @param mimeType
	 *            出力データのMIME型(省略する場合はnull)
	 */
	public void setOutput(OutputStream out, String mimeType) throws IOException;

	/**
	 * <p>
	 * エラーを受け取るためのオブジェクトを設定します。
	 * 
	 * <p>
	 * このメソッドは本体の開始前に呼ぶ必要があります。
	 * 
	 * @see ErrorHandler
	 * @param eh
	 *            エラーハンドラ
	 */
	public void setErrorHandler(ErrorHandler eh);

	/**
	 * <p>
	 * 進行状況を監視するためのオブジェクトを設定します。
	 * 
	 * <p>
	 * このメソッドは本体の開始前に呼ぶ必要があります。
	 * 
	 * <p>
	 * これは、データの変換状況を監視する目的以外に、出力結果の長さを取得するためにも用いられます。
	 * HTTP通信などでContent-Lengthヘッダを送出する場合は重要です。
	 * 
	 * @see ProgressListener
	 * @param l
	 *            進行状況リスナ
	 */
	public void setProgressListener(ProgressListener l);

	/**
	 * <p>
	 * プロパティを設定します。
	 * 
	 * <p>
	 * このメソッドは本体の開始前に呼ぶ必要があります。
	 * 
	 * @param name
	 *            プロパティ名
	 * @param value
	 *            値
	 * @throws IOException
	 */
	public void setProperty(String name, String value) throws IOException;

	/**
	 * <p>
	 * サーバー側からのアクセスを許可するリソースを指定します。
	 * 
	 * <p>
	 * このメソッドは本体の開始前に呼ぶ必要があります。
	 * 
	 * <p>
	 * リソースの指定にはワイルドカードを含むことが出来る、URIパターンを用います。 詳細は「開発者ガイド」を参照してください。
	 * 
	 * @param uriPattern
	 *            URIパターン
	 * @throws IOException
	 */
	public void includeResource(String uriPattern) throws IOException;

	/**
	 * <p>
	 * サーバー側からのアクセスを禁止するリソースを指定します。
	 * 
	 * <p>
	 * このメソッドは本体の開始前に呼ぶ必要があります。
	 * 
	 * <p>
	 * リソースの指定にはワイルドカードを含むことが出来る、URIパターンを用います。 詳細は「開発者ガイド」を参照してください。
	 * 
	 * @param uriPattern
	 *            URIパターン
	 * @throws IOException
	 */
	public void excludeResource(String uriPattern) throws IOException;

	/**
	 * <p>
	 * 変換するリソース(本体)を指定すると同時に、本体の変換を開始します。
	 * 
	 * <p>
	 * このメソッドは、1つのセッションに対して一度だけ呼ぶことが出来ます。
	 * 
	 * @param uri
	 *            サーバー側の本体のURI
	 * @throws IOException
	 */
	public void formatMain(String uri) throws IOException;

	/**
	 * <p>
	 * リソースを送信するための出力ストリームを返します。
	 * 
	 * <p>
	 * <strong>リソースを送信した後、出力ストリームは必ずクローズしてください。 </strong>
	 * 
	 * <p>
	 * このメソッドは本体の開始前に呼ぶ必要があります。
	 * 
	 * @param uri
	 *            リソースの仮想URI
	 * @param mimeType
	 *            リソースのMIME型(省略する場合はnull)
	 * @param encoding
	 *            リソースのエンコーディング(省略する場合はnull)
	 * @return サーバーへの出力ストリーム。
	 * @throws IOException
	 */
	public OutputStream sendResource(String uri, String mimeType,
			String encoding) throws IOException;

	/**
	 * <p>
	 * 本体を送信するための出力ストリームを返します。
	 * 
	 * <p>
	 * <strong>本体を送信した後、出力ストリームは必ずクローズしてください。 </strong>
	 * 
	 * <p>
	 * このメソッドは、1つのセッションに対して一度だけ呼ぶことが出来ます。
	 * 
	 * @param uri
	 *            本体の仮想URI
	 * @param mimeType
	 *            本体のMIME型(省略する場合はnull)
	 * @param encoding
	 *            本体のエンコーディング(省略する場合はnull)
	 * @return サーバーへの出力ストリーム。
	 * @throws IOException
	 */
	public OutputStream sendMain(String uri, String mimeType, String encoding)
			throws IOException;

	/**
	 * <p>
	 * セッションをクローズします。
	 * 
	 * <p>
	 * このメソッドを呼び出した後は、セッションに対して何も出来ません。
	 * 
	 * @throws IOException
	 */
	public void close() throws IOException;
}