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