# sticker manual

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

## Outline

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

- <sticker>
  - <Variables>*
    - <Variable>*
  - <stop>*
  - <debug>*
  - <info>*
  - <shell>*
  - <servers>?
    - <server>+
  - <tables>?
    - <info>*
    - <debug>*
    - <table>+
      - <column>+
  - <cursors>?
    - <cursor>+
  - <connect>+
    - <debug>*
    - <info>*
    - <sql>*
    - <import>*
    - <queryImport>*
    - <export>*
    - <shell>*
    - <stop>*
    - <if>*
      - <info>*
      - <sql>*
      - <import>*
      - <queryImport>*
      - <export>*
      - <shell>*
      - <for>*
      - <stop>*
    - <for>*
      - <info>*
      - <sql>*
      - <import>*
      - <queryImport>*
      - <export>*
      - <shell>*
      - <if>*
      - <stop>*
  - <exception>?
    - <connect>*
    - <debug>*
    - <info>*
    - <shell>*
    - <stop>*

指定可能文字コード一覧

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

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

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

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

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

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

sticker定義ファイルのあらゆるタグはstickerタグの子要素でなければなりません。
<Variables>*
変数宣言を開始します
<Variable>タグによる変数宣言を開始します
<Variable>*
定数宣言を行います。定数に対応したタグの属性やテキストに埋め込まれた置換文字列を ここで宣言された定数の値で置換します

属性 | 値 | 必須 | 規定値 | 意味
--- | --- | --- | --- | ---
name | 任意の定数名 | ○ |  | 定数名
value | 定数値 | ○ |  | 定数に設定する値を指定します。

定数を宣言します。<sql>タグのテキストなど、定数に対応したタグの値に 埋め込まれた置換文字列({定数名}と定義された値)を、ここで定義された定数値で置き換えます。
以下例では定数ownerの値はscottと定義されます。また、このとき<sql> タグ実行時にselect * from {owner}.employeeというSQL文は select * from scott.employeeに展開され実行されます。

      <Variable name="owner" value="scott" />

      ...省略...

      <sql>
        select * from {owner}.employee
      </sql>

変数定義に対応したタグ、および属性は以下の表を参照してください。

タグ | 適用範囲
--- | ---
<sql> | 子要素のテキストに適用可能
<server> | user属性、pass属性、driverJarFile属性に適用可能
<export> | 子要素のテキストに適用可能
<queryImport> | 子要素のテキストに適用可能
<shell> | 子要素のテキストに適用可能
<cursor> | 子要素のテキストに適用可能

<debug>*
<debug>で囲まれた文字列を実行時ログとして出力します
このタグはVersion1.00で廃止予定です。今後は<info>タグを利用してください。
<info>*
<info>で囲まれた文字列を実行時ログとして出力します
<info>で囲まれた文字列を実行時ログとして出力します。ログレベルはINFOです。テスト時に処理の経過を出力したい場合に利用してください。
<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 | 任意の文字列 | × |  | この列のデフォルト値を定義します
option | 任意の文字列 | × |  | この列定義に対する付加情報（GENERATED BY DEFAULT AS IDENTITYやPRIMARY_KEYなど）を定義します。 ここで定義した値がそのままcreate tableの列定義に利用されます。

ローカルデータベース(hsqldb)に作成するテーブルの列定義情報を表します。
hsqldbが利用できるデータ型についての詳細は hsqldbのドキュメント を参照してください。
<cursors>?
カーソル定義を行います
属性：なし
カーソルを定義します。
<cursor>*
<if>タグや<for>タグなどで利用するカーソルを定義します

属性 | 値 | 必須 | 規定値 | 意味
--- | --- | --- | --- | ---
name | 任意の文字列 | ○ |  | カーソル名を定義します。<for>タグ等、カーソルを利用するタグはここで定義された 名前を利用してカーソルを一意に特定します。このため、ここで指定する名前は定義ファイル内でユニークでなければなりません。

指定された名前でカーソルを定義します。 <for>タグ等のカーソルを利用するタグは、<cursor>タグで囲まれたSQL(Select文)を実行し、その結果をもって 何らかの処理を行います。
カーソルを定義しただけではSQLは実行されません。
<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>タグをご覧ください。
<info>*
<info>タグをご覧ください。
<sql>*
<connect>タグで指定したリレーショナルデータベースサーバー、または ローカルデータベース(hsqldb)に対して任意のsqlを発行します。

属性 | 値 | 必須 | 規定値 | 意味
--- | --- | --- | --- | ---
target | remote|local | × | remote | target属性を"remote"とした場合(規定値)、<sql>タグで囲ったSQL文は <connect>タグで指定したリレーショナルデータベースに対して発行されます。 "local"とした場合、<sql>タグで囲ったSQL文はローカルデータベース(hsqldb)に 対して発行されます。
ignore | true|false | × | false | この属性をtrueに設定しておくと、SQL発行時に例外(またはエラー)を無視して処理を続けます。

<sql>タグで囲まれたSQLを実行します。
target属性を"remote"とした場合(規定値)、SQLは<connect>タグで 指定したデータベースサーバーに対して実行されます。
target属性を"local"とした場合、SQLはローカルデータベース(hsqldb)に対して実行されます。
<server>タグのautocommitが"false"の場合（規定値）、 <sql>タグで実行されるSQLはトランザクション境界内で実行されるため、必要に 応じてcommitまたはrollbackしなければなりません。
また、ローカルデータベース(hsqldb)に対してはSQLは常にトランザクション境界内で実行されます。
Sticker Version0.1.4からストアドプロシージャの実行ができるようになりました（引数、戻り値には非対応)。 call プロジージャ名でプロジージャを実行できます。
<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文を発行し、リモートのデータベースサーバーに 対してインポートを行ってください。
<queryImport>*
<queryImport>タグで囲ったSQLを内部DB(HSQLDB)に対して実行し、選択された結果をdestination属性で指定したテーブルに インポートします。

属性 | 値 | 必須 | 規定値 | 意味
--- | --- | --- | --- | ---
destination | インポート先テーブル名 | ○ |  | クエリを実行し、得られた結果のインポート先となるテーブル名

<connect>タグで指定したデータベースに対して、データのインポートを行います。
<import>タグと異なり、インポート元はローカルデータベース(hsqldb)に限られます。また、 インポート対象のデータを絞り込むために、<queryImport>タグの子要素としてSQL 文を記述します。
Stickerは、<queryImport>タグで指定されたSQLを実行し、その結果セットを インポートデータとして、destination属性で指定したリモートデータベースのテーブルに対してデータのインポートを行います。
<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>タグで囲まれた文字列をコマンドとして実行します。
指定するコマンドに対して適切な実行権限がなければなりません。
<if>*
条件分岐を行います

属性 | 値 | 必須 | 規定値 | 意味
--- | --- | --- | --- | ---
name | 分岐条件となるカーソル名 | ○ |  | <cursor>タグで定義されたカーソル名
value | 比較値 | ○ |  | カーソルで指定されたSQLの実行結果と比較する値
target | remote|local | × | remote | target属性が"remote"と指定されている場合(規定値)、<cursor>タグで 囲ったSQLは<connect>タグで指定したリレーショナルデータベースサーバー に対して発行されます。 target属性が"local"と指定されている場合、<cursor>タグで囲ったSQLは <table>タグを用いて作成したローカルデータベース(hsqldb)のテーブルに対し て発行されます。

条件分岐を行います。
name属性で指定されたカーソルのSQLを実行し、先頭レコードの最初のフィールド値と、value属性で指定した値が一致した場合に子要素の各タグを実行します。
<for>*
<cursor>タグで囲まれたSQLを実行し、得られた結果のレコード数分繰り返し処理を行います。

属性 | 値 | 必須 | 規定値 | 意味
--- | --- | --- | --- | ---
name | 繰り返しで利用するカーソル名 | ○ |  | <cursor>タグで定義されたカーソル名
target | remote|local | × | remote | target属性が"remote"と指定されている場合(規定値)、<cursor>タグで 囲ったSQLは<connect>タグで指定したリレーショナルデータベースサーバー に対して発行され、その結果が繰り返し処理に利用されます。 target属性が"local"と指定されている場合、<cursor>タグで囲ったSQLは <table>タグを用いて作成したローカルデータベース(hsqldb)のテーブルに対し て発行され、その結果が繰り返し処理に利用されます。

カーソルを開き、１レコードずつ繰り返し処理を行います。
このとき、<connect>タグで定義されたSelect文で得られた各フィールド値を利用して <info>、<sql>、<shell>、 <export>、<queryImport> の各タグで囲まれた文字列を置換することができます。また、<export>、<queryImport>と<import> タグではsource属性、destination属性の値にも置換文字を利用することができます。
たとえば、以下のようにカーソルを定義し、ループを定義します

      <cursor name="user">
        select id, name from UserTable
      </cursor>

      ...省略...

      <for name="user">
        <info>私の名前は_$$name$$_です。</info>
        <sql>
          select * from employee where userId=_$$id$$_
        </sql>
      </for>

このとき、<cursor>タグのSQLが実行され、結果としてidフィールドとnameフィールドを持つ結果セットが生成され、 レコード数の分だけ<for>タグが繰り返されます。
繰り返し時、結果セットのフィールド名を「_$$」と「$$_」で囲むと、結果セットの値で置換され、各タグが実行されます。 sample5.xmlファイルにループのサンプルが示されています。
<exception>?
sticker実行中に例外が発生した場合、<exception>タグで囲まれた子要素の処理を 行います。
sticker実行中に例外が発生した場合、<exception>タグで囲まれた子要素の処理を 行います。
<stop>*
このタグが記載された部分でStickerの実行を終了します
<stop />と記述すると、ここでStickerの実行が終了します。

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

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、日本語