src/main/java/jp/sfjp/mikutoga/xml/XmlExporter.java

   1 /*
   2  * xml exporter
   3  *
   4  * License : The MIT License
   5  * Copyright(c) 2013 MikuToga Partners
   6  */
   7
   8 package jp.sfjp.mikutoga.xml;
   9
  10 import java.io.Closeable;
  11 import java.io.Flushable;
  12 import java.io.IOException;
  13
  14 /**
  15  * XMLエクスポータ基本機能のセット。
  16  */
  17 public interface XmlExporter extends Appendable, Flushable, Closeable{
  18
  19     /**
  20      * 1文字を生出力する。
  21      * @param ch 文字
  22      * @return this本体
  23      * @throws IOException 出力エラー
  24      */
  25     XmlExporter putRawCh(char ch) throws IOException;
  26
  27     /**
  28      * 文字列を生出力する。
  29      * @param seq 文字列
  30      * @return this本体
  31      * @throws IOException 出力エラー
  32      */
  33     XmlExporter putRawText(CharSequence seq) throws IOException;
  34
  35     /**
  36      * 空白を出力する。
  37      * @return this本体
  38      * @throws IOException 出力エラー
  39      */
  40     XmlExporter sp() throws IOException;
  41
  42     /**
  43      * 空白を指定回数出力する。
  44      * @param count 空白回数。0以下の場合は何も出力しない。
  45      * @return this本体
  46      * @throws IOException 出力エラー
  47      */
  48     XmlExporter sp(int count) throws IOException;
  49
  50     /**
  51      * 改行文字列を返す。
  52      * @return 改行文字列
  53      */
  54     String getNewLine();
  55
  56     /**
  57      * 改行文字列を設定する。
  58      * @param newLine 改行文字列
  59      * @throws NullPointerException 引数がnull
  60      */
  61     void setNewLine(String newLine) throws NullPointerException;
  62
  63     /**
  64      * 改行を出力する。
  65      * @return this本体
  66      * @throws IOException 出力エラー
  67      */
  68     XmlExporter ln() throws IOException;
  69
  70     /**
  71      * 改行を指定回数出力する。
  72      * @param count 改行回数。0以下の場合は何も出力しない。
  73      * @return this本体
  74      * @throws IOException 出力エラー
  75      */
  76     XmlExporter ln(int count) throws IOException;
  77
  78     /**
  79      * インデント単位文字列を返す。
  80      * @return インデント単位文字列
  81      */
  82     String getIndentUnit();
  83
  84     /**
  85      * インデント単位文字列を設定する。
  86      * <p>デフォルトでは空白2個。
  87      * @param indUnit インデント単位文字列。
  88      * @throws NullPointerException 引数がnull
  89      */
  90     void setIndentUnit(String indUnit) throws NullPointerException;
  91
  92     /**
  93      * インデントレベルを一段下げる。
  94      */
  95     void pushNest();
  96
  97     /**
  98      * インデントレベルを一段上げる。
  99      * インデントレベル0の状態をさらに上げようとした場合、何も起こらない。
 100      */
 101     void popNest();
 102
 103     /**
 104      * インデントレベルを返す。
 105      * <p>深さ1の場合1を返す。
 106      * @return インデントレベル
 107      */
 108     int getIndentLevel();
 109
 110     /**
 111      * インデントを出力する。
 112      * インデント単位文字列をネストレベル回数分出力する。
 113      * @return this本体
 114      * @throws IOException 出力エラー
 115      */
 116     XmlExporter ind() throws IOException;
 117
 118     /**
 119      * BasicLatin文字だけを出力する状態か判定する。
 120      * <p>コメント部中身は対象外。
 121      * @return BasicLatin文字だけで出力するならtrue
 122      */
 123     boolean isBasicLatinOnlyOut();
 124
 125     /**
 126      * BasicLatin文字だけで出力するか設定する。
 127      * <p>BasicLatin以外の文字(≒日本語)を、そのまま出力するか、
 128      * 文字参照で出力するか、の設定が可能。
 129      * <p>コメント部中身は対象外。
 130      * @param bool BasicLatin文字だけで出力するならtrue
 131      */
 132     void setBasicLatinOnlyOut(boolean bool);
 133
 134     /**
 135      * 指定された文字を16進2桁の文字参照形式で出力する。
 136      * <p>「A」は「&amp;#x41;」になる。
 137      * <p>2桁で出力できない場合(&gt;0x00ff)は4桁で出力する。
 138      * @param ch 文字
 139      * @return this本体
 140      * @throws IOException 出力エラー
 141      * @see <a href="http://www.w3.org/TR/xml11/#NT-CharRef">
 142      * W3C XML1.1 Character Reference
 143      * </a>
 144      */
 145     XmlExporter putCharRef2Hex(char ch) throws IOException;
 146
 147     /**
 148      * 指定された文字を16進4桁の文字参照形式で出力する。
 149      * <p>「亜」は「&amp;#x4E9C;」になる。
 150      * <p>UCS4に伴うサロゲートペアは未サポート
 151      * @param ch 文字
 152      * @return this本体
 153      * @throws IOException 出力エラー
 154      * @see <a href="http://www.w3.org/TR/xml11/#NT-CharRef">
 155      * W3C XML1.1 Character Reference
 156      * </a>
 157      */
 158     XmlExporter putCharRef4Hex(char ch) throws IOException;
 159
 160     /**
 161      * 要素の中身および属性値中身を出力する。
 162      * <p>XMLの構文規則を守る上で必要な各種エスケープ処理が行われる。
 163      * @param ch 文字
 164      * @return this本体
 165      * @throws IOException 出力エラー
 166      */
 167     XmlExporter putCh(char ch) throws IOException;
 168
 169     /**
 170      * 要素の中身および属性値中身を出力する。
 171      * <p>必要に応じてXML定義済み実体文字が割り振られた文字、
 172      * コントロールコード、および非BasicLatin文字がエスケープされる。
 173      * <p>半角円通貨記号U+00A5はバックスラッシュU+005Cに置換される。
 174      * <p>連続するスペースU+0020の2文字目以降は文字参照化される。
 175      * <p>全角スペースその他空白文字は無条件に文字参照化される。
 176      * @param content 内容
 177      * @return this本体
 178      * @throws IOException 出力エラー
 179      */
 180     XmlExporter putContent(CharSequence content) throws IOException;
 181
 182     /**
 183      * コメントの内容を出力する。
 184      * <p>コメント中の'\n'記号出現に伴い、
 185      * あらかじめ指定された改行文字が出力される。
 186      * <p>コメント中の'\n'以外のコントロールコードは
 187      * Control Pictures(U+2400〜)で代替される。
 188      * <p>それ以外の非BasicLatin文字はそのまま出力される。
 189      * <p>連続するハイフン(-)記号間には強制的にスペースが挿入される。
 190      * @param comment コメント内容
 191      * @return this本体
 192      * @throws IOException 出力エラー
 193      * <a href="http://www.unicode.org/charts/PDF/U2400.pdf">
 194      * Unicode 6.2 Controll Pictures
 195      * </a>
 196      */
 197     XmlExporter putCommentContent(CharSequence comment) throws IOException;
 198
 199     /**
 200      * 1行コメントを出力する。
 201      * コメント内部の頭及び末尾に空白が1つ挿入される。
 202      * @param comment コメント内容
 203      * @return this本体
 204      * @throws IOException 出力エラー
 205      */
 206     XmlExporter putLineComment(CharSequence comment) throws IOException;
 207
 208     /**
 209      * ブロックコメントを出力する。
 210      * <p>コメント内部の頭の前に改行が出力される。
 211      * <p>コメント内部の末尾が改行でない場合、改行が挿入される。
 212      * <p>ブロックコメント末尾は改行で終わる。
 213      * <p>インデント設定は無視される。
 214      * @param comment コメント内容
 215      * @return this本体
 216      * @throws IOException 出力エラー
 217      */
 218     XmlExporter putBlockComment(CharSequence comment) throws IOException;
 219
 220     /**
 221      * 開始タグ開き表記を出力する。
 222      * @param tagName タグ名
 223      * @return this本体
 224      * @throws IOException 出力エラー
 225      */
 226     XmlExporter putOpenSTag(CharSequence tagName) throws IOException;
 227
 228     /**
 229      * 開始タグ閉じ表記を出力する。
 230      * @return this本体
 231      * @throws IOException 出力エラー
 232      */
 233     XmlExporter putCloseSTag() throws IOException;
 234
 235     /**
 236      * 属性の無いシンプルな開始タグ表記を出力する。
 237      * @param tagName タグ名
 238      * @return this本体
 239      * @throws IOException 出力エラー
 240      */
 241     XmlExporter putSimpleSTag(CharSequence tagName) throws IOException;
 242
 243     /**
 244      * 終了タグ表記を出力する。
 245      * @param tagName タグ名
 246      * @return this本体
 247      * @throws IOException 出力エラー
 248      */
 249     XmlExporter putETag(CharSequence tagName) throws IOException;
 250
 251     /**
 252      * 属性の無い単出タグ表記を出力する。
 253      * @param tagName タグ名
 254      * @return this本体
 255      * @throws IOException 出力エラー
 256      */
 257     XmlExporter putSimpleEmpty(CharSequence tagName) throws IOException;
 258
 259     /**
 260      * 単出タグ閉じ表記を出力する。
 261      * @return this本体
 262      * @throws IOException 出力エラー
 263      */
 264     XmlExporter putCloseEmpty() throws IOException;
 265
 266     /**
 267      * xsd:int値をXMLスキーマ準拠の形式で出力する。
 268      * @param iVal int値
 269      * @return this本体
 270      * @throws IOException 出力エラー
 271      * @see <a href="http://www.w3.org/TR/xmlschema11-2/#int">
 272      * XML Schema 1.1 Datatypes int
 273      * </a>
 274      */
 275     XmlExporter putXsdInt(int iVal) throws IOException;
 276
 277     /**
 278      * xsd:float値をXMLスキーマ準拠の形式で出力する。
 279      * @param fVal float値
 280      * @return this本体
 281      * @throws IOException 出力エラー
 282      * @see <a href="http://www.w3.org/TR/xmlschema11-2/#sec-lex-float">
 283      * XML Schema 1.1 Datatypes float Lexical Mapping
 284      * </a>
 285      */
 286     XmlExporter putXsdFloat(float fVal) throws IOException;
 287
 288     /**
 289      * int型属性値を出力する。
 290      * @param attrName 属性名
 291      * @param iVal int値
 292      * @return this本体
 293      * @throws IOException 出力エラー
 294      */
 295     XmlExporter putIntAttr(CharSequence attrName, int iVal)
 296             throws IOException;
 297
 298     /**
 299      * float型属性値を出力する。
 300      * @param attrName 属性名
 301      * @param fVal float値
 302      * @return this本体
 303      * @throws IOException 出力エラー
 304      */
 305     XmlExporter putFloatAttr(CharSequence attrName, float fVal)
 306             throws IOException;
 307
 308     /**
 309      * 属性値を出力する。
 310      * @param attrName 属性名
 311      * @param content 属性内容
 312      * @return this本体
 313      * @throws IOException 出力エラー
 314      */
 315     XmlExporter putAttr(CharSequence attrName, CharSequence content)
 316             throws IOException;
 317
 318 }