# sticker manual

stickerは、XML形式のsticker定義ファイルに定義された内容に従って、データベースへの接続、 内部DBの生成、データのインポートやエクスポート、SQLの実行などのタスクを順次実行します。
ここではsticker定義ファイルに定義できるXMLタグについて解説します。

## Outline

sticker定義ファイルで利用できるタグ
このドキュメントの表記について

- <sticker>
  - <debug>*
  - <shell>*
  - <servers>?
    - <server>+
  - <tables>?
    - <table>+
      - <column>+
  - <connect>+
    - <debug>*
    - <sql>*
    - <import>*
    - <export>*
    - <shell>*
  - <exception>?
    - <connect>*
    - <debug>*
    - <shell>*

指定可能文字コード一覧

## このドキュメントの表記について

このドキュメントではsticker定義ファイルのXML要素が省略可能であることや複数指定が可能であることを以下のように表記しています。

表記 | 意味
--- | ---
<debug>* | <debug>タグは複数（０個以上）記述できる
<servers>? | <servers>タグは省略可能
<connect>+ | <connect>タグは１個以上定義しなければならない

## sticker定義ファイルで利用できるタグ

<sticker>
全ての要素のルート要素を表します

属性 | 値 | 必須 | 規定値 | 意味
--- | --- | --- | --- | ---
version | "0.0.1"固定 | ○ | 0.0.1 | sticker定義ファイルのバージョンを表します。ここで定義されたバージョン以外のstickerにこの定義ファイルを読み込ませてもstickerは動作しません
debug | true|false | ○ | false | trueにするとデバッグログを出力します。

sticker定義ファイルのあらゆるタグはstickerタグの子要素でなければなりません。
<debug>*
デバッグ用としてログ文字列を出力します
<sticker>タグにてdebug="true"が定義されているとき、このタグで囲まれた文字列がデバッグログに出力されます。 テスト時に処理の経過を出力したい場合に利用してください。
<shell>*
外部プロセスを実行します

属性 | 値 | 必須 | 規定値 | 意味
--- | --- | --- | --- | ---
async | trye|false | × | false | trueに指定すると外部プロセスを非同期で実行し、外部プロセスの処理結果を待たずに即時に次のタグの処理を開始します。 規定値はfalseで、外部プロセスの終了を待ちます。
exitOnError | true|false | × | false | async="false"のときexitOnErrorをtrueに指定すると、外部プロセスの実行結果(OSへのリターン値)が0以外の時にstickerの処理を停止します。 通常stickerは外部プロセスの実行結果は参照しません。

外部プロセスの実行は、Windows系OSの場合、CMD.EXEを経由して実行が行われます。
<servers>?
データベースの接続情報を表します
stickerが接続するデータベースのJDBC接続情報を定義します。 stickerは複数のデータベースに対して接続を行うことができ、それぞれの接続は<server>タグの name属性にて指定された名前で区別されます。 サーバーに対する個別の定義情報は子要素である<server>タグに定義してください。
<server>+
リレーショナルデータベースに対するJDBC接続情報を定義します。

属性 | 値 | 必須 | 規定値 | 意味
--- | --- | --- | --- | ---
name | 任意の文字列 | ○ |  | sticker処理時、JDBC接続（コネクション）を一意に特定するための名前を定義します。
driver | 任意の文字列 | ○ |  | JDBCドライバクラス名(postgresならorg.postgres.Driver、oracleならoracle.jdbc.driver.OracleDriver等)を指定します。
driverJarFile | 任意の文字列 | × |  | JDBCドライバのjarファイルを絶対パスで指定します。driverJarFileの指定がない場合、stickerはクラスパス上のJDBCドライバを自動で検索します。
url | 任意の文字列 | ○ |  | リレーショナルデータベースへの接続URLを指定します。
user | 任意の文字列 | ○ |  | リレーショナルデータベースに接続する際のユーザー名を指定します。
pass | 任意の文字列 | ○ |  | リレーショナルデータベースに接続する際のパスワードを指定します。
autocommit | true|false | × | false | trueが指定されると、SQL発行時やインポート実行時、自動でトランザクションがコミットされます。 falseの場合、<sql>タグを使ってトランザクションをコミットまたは ロールバックしなければなりません。

name属性で指定する接続名は、他の接続名と重複することはできません。 また、後述のhsqldbテーブル名と重複しない名前をつけることをお勧めします。
<tables>?
ローカルデータベース(hsqldb)のテーブルを開始します
属性：なし
ローカルデータベース(hsqldb)にテーブルを作成する場合、そのテーブルを定義します。 stickerは内部にhsqldbを内蔵しており、このテーブルに作業用の一時テーブルを作成することができます。 テーブル複数定義することができ、それぞれのテーブルは<table>タグの name属性にて指定された名前で区別されます。 ローカルデータベースのテーブルに対する個別の定義情報は子要素である<table>タグに定義してください。
<table>+
ローカルデータベース(hsqldb)のテーブル定義を表します

属性 | 値 | 必須 | 規定値 | 意味
--- | --- | --- | --- | ---
name | 任意の文字列 | ○ |  | ローカルデータベース(hsqldb)に作成するテーブル名を表します

ローカルデータベース(hsqldb)に作成するテーブルの定義情報を表します。stickerは<table>タグと <column>タグの情報を併せてhsqldbに対してcreate tableのddlを発行します。 ここで定義されたテーブルに対して自由にSQLの発行、インポート、エクスポートを行うことができます。
<column>+
ローカルデータベース(hsqldb)のテーブル定義のうち、カラム情報を定義します

属性 | 値 | 必須 | 規定値 | 意味
--- | --- | --- | --- | ---
name | 任意の文字列 | ○ |  | 列名を定義します
type | 任意の文字列 | ○ |  | 列の型、列長を定義します
nullable | true|false | × | false | この列がnullを許可するのであればtrueを指定します
default | 任意の文字列 | × |  | この列のデフォルト値を定義します

ローカルデータベース(hsqldb)に作成するテーブルの列定義情報を表します。
hsqldbが利用できるデータ型についての詳細は hsqldbのドキュメント を参照してください。
<connect>+
指定したデータベースサーバーに対してstickerの処理を行います

属性 | 値 | 必須 | 規定値 | 意味
--- | --- | --- | --- | ---
name | 任意の文字列 | ○ |  | <server>タグで定義されたリレーショナルデータベース名を指定します。 stickerはここで指定したサーバーに対して処理を行います。

指定したデータベースサーバーに対して、処理を開始します。stickerでは<connect>タグで 指定したサーバーに対して、その子要素に定義された処理を順次実行します。
たとえば、<server name="my-server"....>と定義し、<connect name="my-server">の子要素に <import>タグを定義すると、my-serverに対してインポート処理を行います。
同様に<connect name="my-server">の子要素に <export>タグを定義すると、my-serverからデータをエクスポート処理します。
<debug>*
<debug>タグをご覧ください。
<sql>*
<connect>タグで指定したリレーショナルデータベースサーバー、または ローカルデータベース(hsqldb)に対して任意のsqlを発行します。

属性 | 値 | 必須 | 規定値 | 意味
--- | --- | --- | --- | ---
target | remote|local | × | remote | target属性を"remote"とした場合(規定値)、<sql>タグで囲ったSQL文は <connect>タグで指定したリレーショナルデータベースに対して発行されます。 "local"とした場合、<sql>タグで囲ったSQL文はローカルデータベース(hsqldb)に 対して発行されます。

<sql>タグで囲まれたSQLを実行します。
target属性を"remote"とした場合(規定値)、SQLは<connect>タグで 指定したデータベースサーバーに対して実行されます。
target属性を"local"とした場合、SQLはローカルデータベース(hsqldb)に対して実行されます。
<server>タグのautocommitが"false"の場合（規定値）、 <sql>タグで実行されるSQLはトランザクション境界内で実行されるため、必要に 応じてcommitまたはrollbackしなければなりません。
また、ローカルデータベース(hsqldb)に対してはSQLは常にトランザクション境界内で実行されます。
<import>*
source属性で指定したCSVファイルまたはテーブルからdestination属性で指定したテーブルに対してデータのインポートを行います。

属性 | 値 | 必須 | 規定値 | 意味
--- | --- | --- | --- | ---
source | インポート元CSVファイルパスまたはテーブル名 | ○ |  | インポート元となるCSVファイルのファイル名またはテーブル名を指定します。
destination | インポート先テーブル名 | ○ |  | インポート先となるテーブル名を定義します。 target属性が"remote"と指定されている場合(規定値)、destinationで指定するテーブル名は <connect>タグで指定したリレーショナルデータベースサーバーのテーブル名 でなければなりません。 target属性が"local"と指定されている場合、destinationで指定するテーブル名は <table>タグを用いて作成したローカルデータベース(hsqldb)のテーブル名で なければなりません。
target | remote|local | × | remote | target属性を"remote"とした場合(規定値)、インポートは<connect>タグで 指定したリレーショナルデータベースのテーブルに対して実行されます。 "local"とした場合、インポートはローカルデータベース(hsqldb)のテーブルに対して実行されます。
fileCharset | 指定可能文字コード一覧で定義されている文字コード | × | OSで規定されている文字コード(Windows系OSの場合はMS932) | source属性にCSVファイルを指定している場合、読み込み元のCSVファイルの文字コードを指定します。 source属性の指定がデータベーステーブルの場合、この属性は無視されます。
separator | ","またはタブ、または"|" | × | , | source属性にCSVファイルを指定している場合、読み込み元のCSVファイルの列区切り文字を指定します。 source属性の指定がデータベーステーブルの場合、この属性は無視されます。
quot | "または' | × |  | source属性にCSVファイルを指定している場合、読み込み元のCSVファイルの囲み文字を指定します。 source属性の指定がデータベーステーブルの場合、この属性は無視されます。
header | true|false | × | true | source属性にCSVファイルを指定している時、header="true"とすると読み込み元のCSVファイルに列ヘッダーが 定義されているとみなして２行目からインポートを行います。 source属性の指定がデータベーステーブルの場合、この属性は無視されます。

<connect>タグで指定したデータベースに対して、データのインポートを行います。
インポート元としてCSVファイルまたはローカルデータベース(hsqldb)のテーブルいずれかが指定できます。インポートはインポート元の データ全件を対象にして行われます。
CSVファイルから条件に合致したレコードのみインポートを行いたい場合は、一度ローカルデータベース(hsqldb)にインポートを行い、 ローカルデータベース内のデータを条件に合致するレコードのみになるようdelete文を発行し、リモートのデータベースサーバーに 対してインポートを行ってください。
<export>*
source属性で指定したテーブルからdestination属性で指定したCSVファイルまたはローカルデータベース(hsqldb)のテーブルに対して データのエクスポートを行います。
エクスポートは<import>タグと異なり、<export>タグで 囲ったSQLを実行した結果がエクスポートされます。

属性 | 値 | 必須 | 規定値 | 意味
--- | --- | --- | --- | ---
destination | エクスポート先となるローカルデータベース(hsqldb)のテーブル名またはCSVファイル | ○ |  | エクスポート先となるCSVファイルファイルまたはローカルデータベース(hsqldb)のテーブル名を定義します。 <export>タグで囲ったSQLを実行した結果をdestination属性で指定した CSVファイルまたはローカルデータベース(hsqldb)に対してエクスポートします。
target | remote|local | × | remote | target属性が"remote"と指定されている場合(規定値)、<export>タグで 囲ったSQLは<connect>タグで指定したリレーショナルデータベースサーバー に対して発行され、その結果がエクスポートされます。 target属性が"local"と指定されている場合、<export>タグで囲ったSQLは <table>タグを用いて作成したローカルデータベース(hsqldb)のテーブルに対し て発行され、その結果がエクスポートされます。
fileCharset | 指定可能文字コード一覧で定義されている文字コード | × | OSで規定されている文字コード(Windows系OSの場合はMS932) | destination属性にCSVファイルを指定している場合、エクスポート先のCSVファイルの文字コードを指定します。 destination属性の指定がデータベーステーブルの場合、この属性は無視されます。
separator | ","またはタブ、または"|" | × | , | destination属性にCSVファイルを指定している場合、エクスポート先のCSVファイルの列区切り文字を指定します。 destination属性の指定がデータベーステーブルの場合、この属性は無視されます。
quot | "または' | × |  | destination属性にCSVファイルを指定している場合、エクスポート先CSVファイルの囲み文字を指定します。 stickerでは文字、文字列、時刻、日付、日付時刻型の場合、quotで指定されたクォート文字で値を囲んでエクスポートを 行います。 destination属性の指定がデータベーステーブルの場合、この属性は無視されます。
header | true|false | × | true | destination属性にCSVファイルを指定している時、header="true"とするとエクスポート先CSVファイルに列ヘッダーが 付与されます。列ヘッダーは、<export>タグで囲ったSQLの実行結果の列名が そのまま列ヘッダーとして使用されます。 destination属性の指定がデータベーステーブルの場合、この属性は無視されます。
overwrite | true|false | × | true | destination属性にCSVファイルを指定している時、エクスポート先のCSVファイルが既に存在する場合に上書きするので あればtrueを指定します。falseが指定されて、エクスポート先CSVファイルが存在すると、stickerは実行エラーとして 処理を中断します。 destination属性の指定がデータベーステーブルの場合、この属性は無視されます。

<connect>タグで指定したデータベースから、データのエクスポートを行います。
エクスポートするテーブル、列、エクスポート対象となるデータの条件などは、<export>タグで 囲ったSQLで指定します。
エクスポート先としてCSVファイルまたはローカルデータベース(hsqldb)のテーブルいずれかが指定できます。
<shell>*
シェルを起動し、<shell>タグで囲った文字列をコマンドとして実行します。

属性 | 値 | 必須 | 規定値 | 意味
--- | --- | --- | --- | ---
async | true|false | × | false | 非同期でコマンドを実行する場合はtrueとします。この場合stickerはコマンドの終了を待つことなく次の処理を実行します。 falseが指定された場合(規定値)stickerはコマンドが終了するまで処理を中断します。
exitOnError | true|false | × | true | async="false"の時(規定値)でexitOnError="true"の時(規定値)、stickerはシェルに投げたコマンドの終了コードを 参照して次の処理の継続を決定します。 シェルに投げたコマンドが終了コード0(正常終了)で終了していれば、stickerは以降の処理を継続します。 0以外の値である場合、stickerはコマンドが異常終了したとみなして以降の処理を中断します(別途 <exception>タグが指定されていればそこから処理を継続します)。

シェルを起動し、<shell>タグで囲まれた文字列をコマンドとして実行します。
指定するコマンドに対して適切な実行権限がなければなりません。
<exception>?
sticker実行中に例外が発生した場合、<exception>タグで囲まれた子要素の処理を 行います。
sticker実行中に例外が発生した場合、<exception>タグで囲まれた子要素の処理を 行います。

## 指定可能文字コード一覧

stickerでCSVファイルを読み書きする際に利用できる文字コードを以下に挙げます。

文字コード | 備考
--- | ---
ISO2022JP | ISO 2022-JP(俗に「JISコード」と呼ばれる文字コード)
SJIS | Shift JIS
8859_1 | ISO 8859-1
MS932 | Microsoftコードページ932。ShiftJISのマイクロソフト実装
EUC_JP | UNIX上で日本語の文字を扱う場合によく利用されている文字コード
ASCII | コンピュータその他の通信機器において最もよく使われている文字コード。いわゆる１バイト文字
UnicodeBig | 16 ビット Unicode Transformation Format、ビッグエンディアンバイト順、バイト順マーク付きの文字コード
UnicodeBigUnmarked | 16 ビット Unicode Transformation Format、ビッグエンディアンバイト順の文字コード
UnicodeLittle | 16 ビット Unicode Transformation Format、リトルエンディアンバイト順、バイト順マーク付きの文字コード
UnicodeLittleUnmarked | 16 ビット Unicode Transformation Format、リトルエンディアンバイト順の文字コード
UTF8 | 8 ビット Unicode Transformation Format
UTF-16 | 16 ビット Unicode Transformation Format。Windows XPなどのOSの内部コードに利用
Cp500 | EBCDIC 500V1
Cp930 | UDC 4370 文字を含む日本語カタカナ漢字、5026 のスーパーセット
Cp939 | UDC 4370 文字を含む日本語ラテン文字漢字、5035 のスーパーセット
Cp942 | IBM OS/2 日本語、Cp932 のスーパーセット
Cp942C | Cp942 の拡張
Cp943 | IBM OS/2 日本語、Cp932 および Shift-JIS のスーパーセット
Cp943C | Cp943 の拡張
Cp33722 | IBM-eucJP - 日本語 (5050 のスーパーセット)
JIS0201 | JIS X 0201、日本語
JIS0208 | JIS X 0208、日本語
JIS0212 | JIS X 0212、日本語