1 Oracle Data Integratorオープン・ツールの使用

この付録では、Oracle Data Integrator (ODI)ツールのリファレンス情報を提供します。Oracle Data Integratorでオープン・ツールを使用して新規のシナリオを開発する方法について説明します。

この付録の内容は次のとおりです。

Oracle Data Integratorツールの使用
オープン・ツールの使用
オープン・ツールの開発

Oracle Data Integratorツールの使用

Oracle Data Integratorツール(Oracle Data Integratorコマンドとも呼ばれます)は、実行時に特定のタスクを処理するために用意されているコマンドです。これらのタスクは、一定の時間待機したり音を鳴らすなどの簡単なタスクの場合や、Antスクリプトを実行したりサーバーから電子メールを読み込むなどの高度なタスクの場合があります。

Oracle Data Integratorツールは、パッケージ、プロシージャ・コマンドまたはナレッジ・モジュール・コマンドで使用され、コマンド行から直接使用することもできます。

注意:

Oracle Data Integratorの以前のバージョンでは、内部Javaクラス(SnpsSendMailやSendMaiなど)を使用したJythonまたはJavaスクリプトからの組込みツールのコールがサポートされていました。この方法は現在サポートされていません。

注意:

コマンド内の改行は許可されていません。

パッケージでのツールの使用

Oracle Data Integratorツールをパッケージに追加して使用する方法は、『Oracle Data Integratorでの統合プロジェクトの開発』のOracle Data Integratorツール・ステップの追加に関する項を参照してください。

パッケージ内では、ツール・ステップに順序を付け、その成否に従ってステップを編成できます。順序付けの詳細は、『Oracle Data Integratorでの統合プロジェクトの開発』のステップのレイアウトの調整に関する項およびステップの順序の定義に関する項を参照してください。

変数値、順序またはOracle Data Integrator置換メソッド・コールをツール・パラメータで直接使用できます。

ナレッジ・モジュールまたはプロシージャ・コマンドでのツールの使用

ナレッジ・モジュールまたはプロシージャでOracle Data Integratorツールを使用する方法は、『Oracle Data Integratorでの統合プロジェクトの開発』のプロシージャの使用に関する項を参照してください。

変数値、順序、Oracle Data Integrator置換メソッド・コール、またはSELECT文の結果をツール・パラメータで直接使用できます。

コマンド行からのツールの使用

Oracle Data Integratorツールのコマンド行スクリプトは、DOMAIN_HOME/binディレクトリから実行されます。コマンド行からツールを実行するには、最初にODIトポロジにODI物理エージェント・インスタンスを作成し、ドメインにODIスタンドアロン・エージェント・インスタンスを構成する必要があります。これらのタスクの実行の詳細は、『Oracle Data Integratorのインストールと構成』を参照してください。

コマンド行からツールを実行する場合は、-INSTANCEパラメータを指定する必要があります。ここで、<agent_name>は、構成した物理エージェントの名前です(OracleDIAgent1など)。

コマンド行からOracle Data Integratorツールを使用するには:

使用環境(WindowsまたはUNIX)でコマンド・シェルを起動します。
DOMAIN_HOME/binディレクトリに移動します。
次の構文を使用して、startcmd.cmd (Windows)またはstartcmd.sh (UNIX)コマンドを起動し、Oracle Data Integratorツールを実行します。
```
startcmd.<cmd|sh> -INSTANCE=<agent_name> <command_name> [<command_parameters>]*
```

コマンド名およびコマンド・パラメータは大/小文字が区別されます。

重要な注意事項

次の点に注意してください。

Windowsプラットフォームでは、等号(=)またはスペースを含むコマンド引数は、二重引用符で囲む必要があります。これは、UNIXのコマンド・コールとは異なります。次に例を示します。
```
startcmd.cmd OdiSleep "-INSTANCE=OracleDIAgent1" "-DELAY=5000"
./startcmd.sh OdiSleep -INSTANCE=OracleDIAgent1 -DELAY=5000
```
次のツールは、コマンド行からの直接起動をサポートしていません。
- OdiRetrieveJournalData
- OdiRefreshJournalCount

オープン・ツールの使用

オープン・ツール機能には、パッケージやプロシージャで使用できるカスタムのサード・パーティ・ツールを開発するための拡張可能なプラットフォームがあります。Oracle Data Integratorに付属の標準ツールと同じように、オープン・ツールはオペレーティング・システムと相互に作用し、データを操作できます。

オープン・ツールはJavaで記述されています。独自のオープン・ツールの記述方法については、「オープン・ツールの開発」を参照してください。

オープン・ツールは、次のいくつかのファイルが格納されたJavaパッケージ(.zipまたは.jar)として配布されます。

Javaのコンパイル済.classファイル
アイコン・ファイルなどのその他のリソース

オープン・ツールのインストールおよび宣言

オープン・ツールを使用するには、オープン・ツールをインストールおよび追加する必要があります。

オープン・ツールのインストール

オープン・ツールをインストールするには、クラスパスまたはこのツールを使用しているコンポーネントに、オープン・ツールJARを追加する必要があります。

オープン・ツールJARは、DOMAIN_HOME/libディレクトリに追加される必要があります。ドライバは同じ場所に追加されます。

オープン・ツールJARとJava EEエージェントをデプロイするには、このエージェントのサーバー・テンプレートを生成します。オープン・ツールは、テンプレート生成ウィザードの「ライブラリおよびドライバ」リストに表示されます。詳細は、『Oracle Data Integratorの管理』のJava EEエージェントに対するサーバー・テンプレートの作成に関する項を参照してください。

注意:

この操作は、ツールを使用する各Oracle Data Integrator Studio、およびこのツールを使用してセッションを実行する各エージェントに対して実行する必要があります。

新しいオープン・ツールの宣言

この操作は、マスター・リポジトリでオープン・ツールを宣言し、このツールをOracle Data Integrator Studioに表示できるようにします。

オープン・ツールを宣言するには、JARを<ide.user.dir>/oracledi/userlibに追加する必要があります。

新しいツールを宣言するには:

Oracle Data Integrator Studioで、「ODI」メニューから「オープン・ツールの追加/削除」を選択します。「オープン・ツールの追加」ダイアログが表示されます。
「オープン・ツール・クラス名」フィールドにクラス名を入力します。

または

「ClassPathで検索します」をクリックし、オープン・ツールのJavaクラス名を参照します。名前でクラスを検索するには、上部にあるフィールドに名前の一部を入力します。
「OK」をクリックします。

Oracle Data Integratorで現在使用可能なすべてのクラスの中には、オープン・ツールでないツールのクラスも表示されることに注意してください。クラスを追加するには、そのクラスの名前を知っている必要があります。
「オープン・ツールの追加」をクリックします。

目的のオープン・ツールが含まれている行を選択します。

クラスパスでツールが正常に見つかった場合は、提供されているアイコン、ツールの構文、説明、プロバイダおよびバージョン番号が表示されます。
ツールが見つからない場合は、エラー・メッセージが表示されます。クラスパスを変更するか、オープン・ツールを適切なディレクトリに移動します。

注意:

新しいオープン・ツールを宣言するこの操作は、指定のマスター・リポジトリに対して1回のみ実行する必要があります。

注意:

名前がSnpまたはOdiで開始するオープン・ツール名は使用できません。これらの文字列で開始する名前のオープン・ツールは無視されます。

パッケージまたはプロシージャでのオープン・ツールの使用

オープン・ツールは、Oracle Data Integratorとともに提供されるツールと同様に、パッケージまたはプロシージャで使用できます。

オープン・ツールの開発

オープン・ツールはJavaパッケージで、インタフェースoracle.odi.sdk.opentools.IOpenToolを実装するコンパイル済Javaクラスが含まれています。クラスおよびメソッドの詳細は、Oracle Data Integrator Open Tools APIリファレンス(Javadoc)を参照してください。

オープン・ツール・パッケージには通常2つのアイコンも含まれており、Oracle Data Integratorグラフィカル・インタフェースでオープン・ツールを表すために使用されます。

クラス

次の表は、オープン・ツールのクラスおよびインタフェースを示して説明しています。

クラスまたはインタフェース	説明
`IOpenTool`	すべてのオープン・ツールが実装する必要のあるインタフェース。
`OpenToolAbstract`	いくつかのヘルパー・メソッドを備えたインタフェースの抽象化。可能なかぎり、インタフェースを直接実装するのではなく、このクラスを拡張してください。
`IOpenToolParameter`	オープン・ツールで使用されるパラメータが実装する必要のあるインタフェース。ほとんどの場合は、このインタフェースを実装せずに、`OpenToolParameter`を使用します。
`OpenToolParameter`	`IOpenToolParameter`の完全な実装。各`OpenToolParameter`が1つのパラメータを保持します。
`OpenToolsExecutionException`	オープン・ツールのメソッドによって必要に応じてスローされる例外クラス。
`SimpleOpenToolExample`	オープン・ツールの簡単な例であり、開始点として使用できます。

新しいオープン・ツールの開発

次の手順では、基本的なオープン・ツールであるSimpleMessageBoxの開発について説明します。このクラスのソース・コードは、demo/plugins/srcディレクトリにあります。

構文を定義します。この例では、オープン・ツールは次のようにコールされます:
```
SimpleMessageBox "-TEXT=<text message>" "-TITLE=<window title>"
```
16x16および32x32のアイコンを作成します(通常は.gif形式)。
クラスを作成し、実装します。「クラスの実装」を参照してください。
クラスをコンパイルし、2つのアイコン・ファイルが含まれたパッケージを作成します。
「オープン・ツールのインストールおよび宣言」の説明に従って、オープン・ツールのインストールと宣言を実行します。

クラスの実装

クラスの実装は、次の手順で構成されます。

宣言
パッケージのインポート
パラメータの定義
情報関数の実装
実行

宣言

クラスを宣言するには、その前に、パッケージ名を指定する必要があります。

パッケージ名の指定

適切な名前のパッケージにクラスを配置します。パッケージ名は、インストール時にオープン・ツールを識別するために使用されます。

package com.myCompany.OpenTools;

クラスの宣言

オープン・ツールの開発には、2つの基本的な手法があります:

既存のクラスを拡張してオープン・ツールに変換します。この場合は、インタフェースIOpenToolを既存のクラスに直接単純に実装します。
新規のクラスを開発します。この場合は、抽象クラスOpenToolAbstractを拡張する方法が最も容易です。この抽象クラスには、パラメータで使用するための追加のヘルパー・メソッドも含まれています。
```
public class SimpleMessageBox extends OpenToolAbstract {
```

パッケージのインポート

ほぼすべてのオープン・ツールには、次のオープン・ツールSDKパッケージをインポートする必要があります。

import oracle.odi.sdk.opentools.IOpenTool; /* All Open Tool classes need these three classes */

import oracle.odi.sdk.opentools.IOpenToolParameter;

import oracle.odi.sdk.opentools.OpenToolExecutionException;

import oracle.odi.sdk.opentools.OpenToolAbstract; /* The abstract extended for the Open Tool */

import oracle.odi.sdk.opentools.OpenToolParameter; /* The class used for parameters */

この特定の例では、メッセージ・ボックスを作成するために次のパッケージも必要です。

import javax.swing.JOptionPane; /* Needed for the message box used in this example */

パラメータの定義

OpenToolParameterオブジェクトを格納するプロパティを追加します。これは、構文に対してオブジェクトを定義する目的と、実際のユーザーからパラメータの値を取得する目的の両方に使用されます。このオープン・ツールのパラメータは、次のように静的配列を使用して定義するのが最も簡単です。この配列は、アクセッサ関数を介してアクセスされるため、プライベートにする必要があります。

private static final IOpenToolParameter[] mParameters = new IOpenToolParameter[]
{
    new OpenToolParameter("-TEXT", "Message text", "Text to show in the messagebox (Mandatory).", true),
    new OpenToolParameter("-TITLE", "Messagebox title", "Title of the messagebox.", false)
};

OpenToolParameter()コンストラクタに渡される4つのパラメータは、次のとおりです。

パラメータのコード(先頭のハイフンを含みます)。このコードは、getSyntax()によって返される構文に対応している必要があります。
ユーザーが理解しやすい名前。この名前は、ユーザーがグラフィカル・インタフェースを使用してパラメータを設定する際に使用されます。
説明のヘルプ・テキスト。

パラメータが必須であるかどうか。これはユーザーに表示する目印です。

注意:

Oracle Data Integratorでは、パラメータに必須フラグを付けなくてもかまいません。ただし、入力されるパラメータの組合せはすべて処理可能である必要があります。

パラメータを取得するには、アクセッサ関数getParameters()を実装する必要があります。

public IOpenToolParameter[] getParameters()
{
      return mParameters;
}

情報関数の実装

オープン・ツールに関する情報を戻す関数であるgetDescription()、getVersion()、getProvider()を実装します。

public String getDescription() { return "This Open Tool displays a message box when executed."; }
public String getVersion() { return "v1.0"; }
public String getProvider() { return "My Company, Inc."; }

getSyntax()関数によって、Oracle Data Integratorのグラフィカル・インタフェースに表示されるオープン・ツールの名前と、パラメータの初期値が決定されます。パラメータ名が、getParameters()によって戻されたパラメータ名と一致していることを確認します。

public String getSyntax()
{
        return "SimpleMessageBox \"-TEXT=<text message>\" \"-TITLE=<window title>\"";
}

getIcon()メソッドが、適切なサイズの2つのイメージにパスを戻します。次の例のようになります。

public String getIcon(int pIconType)
{
        switch (pIconType)
        {
               case IOpenTool.SMALL_ICON:
               return "/com/myCompany/OpenTools/images/SimpleMessageBox_16.gif";
             case IOpenTool.BIG_ICON:
             return "/com/myCompany/OpenTools/images/SimpleMessageBox_32.gif";
             default:
             return "";
     }
}

実行

最後は、オープン・ツールが提供する機能を実行するexecute()メソッドです。この場合は、メッセージ・ボックスが表示されます。OpenToolAbstractクラスを拡張する場合は、getParameterValue()メソッドを使用すると、実行時に設定されるパラメータ値を容易に取得できます。

注意:

すべての実行を捕捉して、OpenToolExecutionExceptionのみが発生するように対処する必要があります。

public void execute() throws OpenToolExecutionException
{
     try
     {
     if (getParameterValue("-TITLE") == null || getParameterValue("-TITLE").equals("")) /* title was not filled in by user */
     {
               JOptionPane.showMessageDialog(null, (String) getParameterValue("-TEXT"), (String) "Message", JOptionPane.INFORMATION_MESSAGE);
          } else
          {
               JOptionPane.showMessageDialog(null, (String) getParameterValue("-TEXT"),
                       (String) getParameterValue("-TITLE"),
                       JOptionPane.INFORMATION_MESSAGE);
          }
     }
     /* Traps any exception and throw them as OpenToolExecutionException */
     catch (IllegalArgumentException e)
     {
          throw new OpenToolExecutionException(e);
     }
}

実行時にツールを開く

一般に、オープン・ツール・クラスは、非常に簡潔にインスタンス化され、次の方法で使用されます。

インストール

ユーザーがオープン・ツールのインストールを選択すると、Oracle Data Integratorはクラスをインスタンス化し、getDescription()、getProvider()、getIcon()およびgetVersion()の各メソッドをコールして、クラスに関する情報を取得します。

パッケージでの使用

オープン・ツールがパッケージ内で使用される場合、そのクラスは、getDescription()、getProvider()、getIcon()およびgetVersion()の各メソッドをコールするために一時的にインスタンス化されます。さらに、オープン・ツールのコード名とそのデフォルト引数を取得するために、getSyntax()がコールされます。getParameters()メソッドは、引数のリストをユーザーに対して表示するためにコールされます。

実行

オープン・ツールがパッケージまたはプロシージャ内で実行される都度、クラスは繰り返しインスタンス化されます。実行完了後までインスタンスが維持されることはありません。execute()メソッドは1回のみコールされます。

ヒント:

オープン・ツールの使用およびオープン・ツールSDKドキュメント(JavaDoc)も参照してください。