package jp.cssj.cti.transcoder;

import java.util.Properties;

import jp.cssj.cti.helpers.AbortException;
import jp.cssj.cti.helpers.ContentBuilder;
import jp.cssj.cti.helpers.ErrorHandler;
import jp.cssj.cti.resolver.Source;
import jp.cssj.cti.resolver.SourceResolver;

/**
 * トランスコーダは、jp.cssj.cti.resolver.Sourceによる入力を、java.cssj.cti.helpers.ContentBuilderへと出力するAPIです。
 * <p>
 * jp.cssj.cti.CTISessionとの違いは、ユーザーが実装したjp.cssj.cti.resolver.SourceResolverにリソースが要求されるため、
 * あらかじめ必要なリソースをユーザーが送る必要がありません。
 * </p>
 * <p>
 * ContentBuilder,Source,SourceResolverの典型な実装がFileContentBuilder,URISource,URISourceResolverとして用意されています。
 * ほとんどの場合、これらの実装を用いれば十分です。 以下はhttp://www.cssj.jp/をトランスコーダで変換する例です。
 * </p>
 * 
 * <pre>
 * Transcoder trans = TranscoderFactory.newTranscoderFactory().newTranscoder();
 * FileContentBuilder builder = new FileContentBuilder(out);
 * trans.transcode(builder, new URISource(&quot;http://www.cssj.jp/&quot;),
 * 		new URISourceResolver(), null, null);
 * builder.finish();
 * </pre>
 * 
 * <p>
 * <em>現在、トランスコーダはJavaでライブラリをリンクする場合のみサポートされています。</em>
 * </p>
 * 
 * @see TranscoderFactory
 * 
 * @author <a href="mailto:miyabe at gnn.co.jp">MIYABE Tatsuhiko </a>
 * @version $Id: Transcoder.java,v 1.5 2005/08/18 04:51:26 harumanx Exp $
 */
public interface Transcoder {
	/**
	 * データの変換を実行します。
	 * 
	 * @param builder
	 *            出力先。
	 * @param source
	 *            入力データ。
	 * @param resolver
	 *            リソースの要求先。
	 * @param props
	 *            変換プロパティ。省略する場合はnull。
	 * @param errorHandler
	 *            エラーハンドラ。省略する場合はnull。
	 * @throws TranscoderException
	 */
	public void transcode(ContentBuilder builder, Source source,
			SourceResolver resolver, Properties props, ErrorHandler errorHandler)
			throws TranscoderException, AbortException;
}
