/*
 * XMLFileWriter.java
 * Copyright (C) 2008 Cyber Beans Corporation. All rights reserved.
 */
package jp.co.cybec.cb3.accessor.fileaccess.xml;

import jp.co.cybec.cb3.accessor.Accessor;
import jp.co.cybec.cb3.exception.AccessorAlreadyOpenedException;
import jp.co.cybec.cb3.exception.AccessorNotOpenException;
import jp.co.cybec.cb3.exception.BadXmlGrammerException;
import jp.co.cybec.cb3.exception.DataFileIOException;
import jp.co.cybec.cb3.exception.DataFileNotFoundException;

/**
 * XMLファイルを書き込むためのインタフェース。
 * @author Daisuke Suga
 */
public interface XMLFileWriter extends Accessor {

	/**
	 * XMLの要素の開始タグを出力します。
	 *
	 * @param element 要素
	 * @throws AccessorNotOpenException Openしていないアクセッサに対し、操作を行ったときに発生します。
	 * @throws DataFileIOException データファイル読み書き時のIOエラーにより発生します。
	 */
	void startElement(XMLElement element) throws AccessorNotOpenException, DataFileIOException;

	/**
	 * XMLの要素の終了タグを出力します。
	 *
	 * @param element 要素
	 * @throws AccessorNotOpenException Openしていないアクセッサに対し、操作を行ったときに発生します。
	 * @throws BadXmlGrammerException XMLの文法が間違っているときに発生します。
	 * @throws DataFileIOException データファイル読み書き時のIOエラーにより発生します。
	 */
	void endElement(XMLElement element) throws AccessorNotOpenException, BadXmlGrammerException,
			DataFileIOException;

	/**
	 * XMLの要素を書き込みます。<br>
	 * startElementとcharacters、endElementを行います。
	 *
	 * @param element 要素
	 * @throws AccessorNotOpenException Openしていないアクセッサに対し、操作を行ったときに発生します。
	 * @throws DataFileIOException データファイル読み書き時のIOエラーにより発生します。
	 */
	void dataElement(XMLElement element) throws AccessorNotOpenException, DataFileIOException;

	/**
	 * XMLの要素の値を書き込みます。
	 *
	 * @param element 要素
	 * @throws AccessorNotOpenException Openしていないアクセッサに対し、操作を行ったときに発生します。
	 * @throws DataFileIOException データファイル読み書き時のIOエラーにより発生します。
	 */
	void characters(XMLElement element) throws AccessorNotOpenException, DataFileIOException;

	/**
	 * 名前空間の定義を追加します。
	 *
	 * @param uri 名前空間のURI
	 * @param prefix 接頭辞
	 * @throws AccessorNotOpenException Openしていないアクセッサに対し、操作を行ったときに発生します。
	 */
	void addNamespace(String uri, String prefix) throws AccessorNotOpenException;

	/**
	 * 名前空間の定義を追加します。
	 *
	 * @param uri 名前空間のURI
	 * @throws AccessorNotOpenException Openしていないアクセッサに対し、操作を行ったときに発生します。
	 */
	void addNamespace(String uri) throws AccessorNotOpenException;

	/**
	 * XMLファイルをオープンします。
	 *
	 * @throws AccessorAlreadyOpenedException アクセッサが二重にOpenされたときに発生します。
	 * @throws DataFileNotFoundException データファイルが存在しない場合に発生します。
	 * @throws DataFileIOException データファイル読み書き時のIOエラーにより発生します。
	 */
	void open() throws AccessorAlreadyOpenedException, DataFileNotFoundException,
			DataFileIOException;

	/**
	 * XMLファイルをオープンします。
	 *
	 * @param filepath XMLファイルのパス
	 * @throws AccessorAlreadyOpenedException アクセッサが二重にOpenされたときに発生します。
	 * @throws DataFileNotFoundException データファイルが存在しない場合に発生します。
	 * @throws DataFileIOException データファイル読み書き時のIOエラーにより発生します。
	 */
	void open(String filepath) throws AccessorAlreadyOpenedException, DataFileNotFoundException,
			DataFileIOException;

	/**
	 * XMLファイルをクローズします。
	 *
	 * @throws DataFileIOException データファイル読み書き時のIOエラーにより発生します。
	 */
	void close() throws DataFileIOException;

}
