OpenTracing はクライアントドライバーに対してオプションです。リモート接続がスパンを伝播させるには、ドライバーに適切な OpenTracing jar がクラスパスにある必要があります。これは、maven 依存関係を使用して実行できます。

<dependency>
    <groupId>io.opentracing</groupId>
    <artifactId>opentracing-util</artifactId>
    <version>${version.opentracing}</version>
</dependency>

ここで、version.opentracing(0.31 for Data Virtualization 11.0)は、プロジェクトのインテグレーション bom で定義されます。

または、Data Virtualization クライアント jar が使用されるツールまたは他の環境で必要に応じて、opentracing-util、opentracing-api、および opentracing-noop jar を手動で含めることができます。

クライアントおよびサーバーの OpenTracing サポートには、それぞれのランタイムに適切なトレースクライアントがインストールされ、GlobalTracer 経由で利用可能である必要があります。

org.teiid.jdbc.TeiidDriver をドライバークラスとして使用します。

JDBC 接続に以下の URL 形式を使用します。

jdbc:teiid:<vdb-name>[@mm[s]://<host>:<port>][;prop-name=prop-value]*

URL コンポーネント

jdbc:teiid:<myVdb>@mms://<host>:<port>

-Djavax.net.ssl.trustStore=<dir>/server.truststore (required)
-Djavax.net.ssl.trustStorePassword=<password> (optional)
-Djavax.net.ssl.keyStoreType (optional)

-Djavax.net.ssl.keyStore=<dir>/client.keystore (required)
-Djavax.net.ssl.keyStrorePassword=<password> (optional)
-Djavax.net.ssl.trustStore=<dir>/server.truststore (required)
-Djavax.net.ssl.trustStorePassword=<password> (optioanl)
-Djavax.net.ssl.keyStroreType=<keystore type> (optional)

########################################
# SSL Settings
########################################

#
# The key store type.  Defaults to JKS
#

org.teiid.ssl.keyStoreType=JKS

#
# The key store algorithm, defaults to
# the system property "ssl.TrustManagerFactory.algorithm"
#

#org.teiid.ssl.algorithm=

#
# The classpath or filesystem location of the
# key store.
#
# This property is required only if performing 2-way
# authentication that requires a specific private
# key.
#

#org.teiid.ssl.keyStore=

#
# The key store password (not required)
#

#org.teiid.ssl.keyStorePassword=

#
# The key alias(not required, if given named certificate is used)
#

#org.teiid.ssl.keyAlias=

#
# The key password(not required, used if the key password is different than the keystore password)
#

#org.teiid.ssl.keyPassword=

#
# The classpath or filesystem location of the
# trust store.
#
# This property is required if performing 1-way
# authentication that requires trust not provided
# by the system defaults.
#

#org.teiid.ssl.trustStore=

#
# The trust store password (not required)
#

#org.teiid.ssl.trustStorePassword=

#
# The cipher protocol, defaults to TLSv3
#

org.teiid.ssl.protocol=TLSv1

#
# Whether to allow anonymous SSL
# (the TLS_DH_anon_WITH_AES_128_CBC_SHA cipher suite)
# defaults to true
#

org.teiid.ssl.allowAnon=true

#
# Whether to allow trust all server certificates
# defaults to false
#

#org.teiid.ssl.trustAll=false

#
# Whether to check for expired server certificates (no affect in anonymous mode or with trustAll=true)
# defaults to false
#

#org.teiid.ssl.checkExpired=false

org.teiid.ssl.trustStore=<dir>/server.truststore (required)

org.teiid.ssl.keyStore=<dir>/client.keystore (required)
org.teiid.ssl.trustStore=<dir>/server.truststore (required)

「teiid-client-settings.properties」ファイルを使用して、Data Virtualization 低レベルおよび SSL ソケット接続プロパティーを設定できます。現在、ドライバー/クラスローダーの組み合わせごとに単一のプロパティーファイルのみが必要です。「teiid-client-settings.properties」のサンプルファイルは、「teiid-<version>-client.jar」ファイルのルートにある「teiid-client-settings.orig.properties」です。設定をカスタマイズするには、このファイルを展開してコピーを作成し、適切なプロパティー値を変更し、このファイルを "teiid-<version>-client.jar" ファイルの前にクライアントアプリケーションのクラスパスに配置します。通常、クライアントは SSL 以外のプロパティーを調整する必要はありません。プロパティーの参照方法は次のとおりです。

########################################
# Misc Socket Configuration
########################################

#
# The time in milliseconds for socket timeouts.
# Timeouts during the initialization, handshake, or
# a server ping may be treated as an error.
#
# This is the lower bound for all other timeouts
# the JDBC login timeout.
#
# Typically this should be left at the default of 1000
# (1 second). Setting this value too low may cause read
# errors.
#

org.teiid.sockets.soTimeout=1000

#
# Set the max time to live (in milliseconds) for non-execution
# synchronous calls.
#

org.teiid.sockets.synchronousttl=240000

#
# Set the socket receive buffer size (in bytes)
# 0 indicates that the default socket setting will be used.
#

org.teiid.sockets.receiveBufferSize=0

#
# Set the socket send buffer size (in bytes)
# 0 indicates that the default socket setting will be used.
#

org.teiid.sockets.sendBufferSize=0

#
# Set to true to enable Nagle's algorithm to conserve bandwidth
# by minimizing the number of segments that are sent.
#

org.teiid.sockets.conserveBandwidth=false

#
# Maximum number of bytes per server message.
# May need to be increased when using custom types and/or large batch sizes.
#

org.teiid.sockets.maxObjectSize=33554432

Data Virtualization ステートメント拡張インターフェース org.teiid.jdbc.TeiidStatement は、JDBC 標準以外の機能を提供します。エクステンションインターフェースを使用するには、単に Connection によって返されたステートメントをキャストまたはウェイトします。エクステンションインターフェースでは、以下のメソッドが提供されます。

Data Virtualization サーバーで "partial results" クエリーモードを使用できます。このモードでは、一部のデータソースが利用できない場合でもサーバーが結果を返すようにクエリープロセッサーの動作が変更されます。

たとえば、異なるサプライヤーとデータオブジェクトに 2 つのデータソースが存在し、その 2 つのサプライヤーからの情報の間に統合を作成する仮想グループを作成しているとします。アプリケーションが部分的な結果クエリーモードを使用せずにクエリーを送信し、サプライヤーのデータベースのいずれかがダウンした場合に、仮想グループに対するクエリーは例外を返します。ただし、アプリケーションが "partial results" クエリーモードで同じクエリーを実行する場合、サーバーは実行中のデータソースからデータを返し、ダウンしているデータソースからデータを返しません。

「パート結果」モードを使用する場合、ソースが処理中に例外をスローすると、ユーザーのクエリーが失敗することはありません。代わりに、そのソースは、障害点の後に他の行が返さないものとして処理されます。通常、そのソースは 0 行を返します。

この動作は、これらの操作が不足している情報を便利な方法で処理するため、UNION または OUTER JOIN クエリーを使用する場合に最も役立ちます。他の種類のクエリーは、部分的な結果モードで使用した場合に、単に 0 行をユーザーに返し、ソースが利用できない場合にユーザーに返されます。

クエリーから除外されるソースごとに、ソースと失敗を記述する警告が生成されます。これらの警告は Statement.getWarnings（） メソッドから取得できます。このメソッドは SQLWarning オブジェクトを返しますが、「パート結果」の警告が発生した場合には、org.teiid.jdbc.PartialResultsWarning クラスのオブジェクトになります。このクラスは、名前で失敗したすべてのソースの一覧を取得し、各ソースから発生した特定の例外を取得するために使用できます。

部分的な結果モードはデフォルトでオフになっていますが、JDBC URL の DataSource または partialResultsMode=true の setPartialResultsMode("true")のいずれかを使用して Connection のすべてのクエリーに対してオンにすることができます。いずれの場合も、部分的な結果モードは、SET ステートメントで後で切り替えられます。

Statement statement = ...obtain statement from Connection...
statement.execute("set partialResultsMode true");

statement.execute("set partialResultsMode true");
ResultSet results = statement.executeQuery("SELECT Name FROM Accounts");
while (results.next()) {
  ... //process the result set
}
SQLWarning warning = statement.getWarnings();
while(warning != null) {
  if (warning instanceof PartialResultsWarning) {
    PartialResultsWarning partialWarning = (PartialResultsWarning)warning;
    Collection failedConnectors = partialWarning.getFailedConnectors();
    Iterator iter = failedConnectors.iterator();
    while(iter.hasNext()) {
      String connectorName = (String) iter.next();
      SQLException connectorException = partialWarning.getConnectorException(connectorName);
      System.out.println(connectorName + ": " + connectorException.getMessage());
    }
  }
  warning = warning.getNextWarning();
}

JDBC クエリー実行は、ステートメントが実行されると、または resultset が反復されると、呼び出しスレッドを無期限にブロックできます。場合によっては、呼び出しスレッドをこれらのブロック状態で保持したくないことがあります。埋め込み/ローカル接続を使用する場合は、オプションで org.teiid.jdbc.TeiidStatement および org.teiid.jdbc.TeiidPreparedStatement インターフェースを使用してクエリーを実行し、コールバック org.teiid.jdbc.StatementCallback でクエリーを実行できます。呼び出しスレッドは他の作業を自由に実行できます。コールバックは、必要に応じてエンジン処理スレッドにより実行されます。結果の処理自体がブロックされ、結果処理によってクエリー処理が同時に行われる場合、コールバックは onRow の処理をマルチスレッドに実装し、エンジンスレッドが続行されるようにします。

PreparedStatement stmt = c.prepareStatemen(sql);
Data VirtualizationPreparedStatement tStmt = stmt.unwrap(Data VirtualizationPreparedStatement.class);
tStmt.submitExecute(new StatementCallback() {
    @Override
    public void onRow(Statement s, ResultSet rs) {
        //any logic that accesses the current row ...
        System.out.println(rs.getString(1));
    }

    @Override
    public void onException(Statement s, Exception e) throws Exception {
        s.close();
    }

    @Override
    public void onComplete(Statement s) throws Exception {
        s.close();
    }, new RequestOptions()
});

ブロック以外のロジックは、ステートメントの実行のみに限定されます。接続の作成やバッチ実行などの他の JDBC 操作にはノンブロッキングオプションはありません。

onRow メソッドの転送の位置にアクセスする場合（次の方法、isLast、isAfterLast、絶対）、まだ有効でない可能性があり、org.teiid.jdbc.AsynchPositioningException がスローされます。この例外は、取得した場合や、Data VirtualizationResultSet.available（） を呼び出して、必要な位置が有効かどうかを判断することで回復可能となります。

Data Virtualization の結果セット拡張インターフェース org.teiid.jdbc.TeiidResultSet は、JDBC 標準以外の機能を提供します。拡張インターフェースを使用するには、Data Virtualization ステートメントによって返された結果セットをキャストまたはアンウェイトします。エクステンションインターフェースでは、以下のメソッドが提供されます。

データ仮想化接続（ org.teiid.jdbc.TeiidConnection インターフェースによって定義）は、指定の接続を再認証するために changeUser メソッドと互換性があります。再認証に成功すると、現在の接続が指定のアイデンティティーで使用されます。既存のステートメント/結果セットは引き続き古いアイデンティティーで使用できます。

使用できる説明とともに、利用可能な pg ドライバー接続オプションはすべて https://odbc.postgresql.org/docs/config.html で定義されます。コネクション文字列でこれらのプロパティーを使用する場合、プロパティー名は https://odbc.postgresql.org/docs/config-opt.html で定義されます。

ただし、Data Virtualization はすべてのプロパティーを適用しないため、Updatable Cursors などの一部の場合はクエリーに失敗します。

ロギング/デバッグ設定は必要に応じて使用できます。

「Show SystemTables」、「True is -1」、「Backend genetic optimizer」、「Bytea as LongVarBinary」、「Bools as Char」などのデータタイプ、メタデータ、または最適化を操作する設定は、Data Virtualization サーバーで無視され、クライアント側の効果はありません。これらまたはその他の設定を定義された設定が必要な場合は、製品/プロジェクトに関する問題を作成してください。

クライアント側の影響を与えるその他の設定（「LF <→ CR/LF 変換」など）は必要な場合に使用できますが、現時点では設定のサーバー側の使用はありません。

ワークステーションに ODBC Driver Client ソフトウェアをインストールしたら、Data Virtualization Runtime に接続するように設定する必要があります。以下の手順は、Microsoft Windows Platform に固有のものです。

これを行うには、管理者権限でワークステーションにログインしている必要があり、Control Panel の Data Sources(ODBC) アプレットを使用して新しいデータソース名を追加する必要があります。

設定する各データソース名は、Data Virtualization System 内で 1 つの VDB のみにアクセスできます。複数の VDB を利用できるようにするには、複数のデータソース名を設定する必要があります。

データソース名(DSN)を作成するには、以下の手順を実行します。

*nix プラットフォームで ODBC を使用して Data Virtualization にアクセスする前に、ODBC ドライバーマネージャーをインストールするか、またはすでに存在することを確認する必要があります。ODBC ドライバーマネージャー Data Virtualization は unixODBC を推奨します。RedHat Linux または Fedora を使用している場合は、グラフィカルの「yum」インストーラーを検索して unixODBC を検索し、インストールできます。それ以外の場合は、unixODBC マネージャーを ダウンロード できます。インストールするには、ファイルの内容を一時的な場所に展開し、スーパーユーザーで次のコマンドを実行します。

./configure
make
make install

インストール時に問題が発生した場合は、unixODBC の Web サイトサイトで詳細を確認してください。

これで、前の手順で PostgreSQL ドライバーが正しくインストールされたことを確認するには、以下のコマンドを実行します。

odbcinst -q -d

これにより、システムにインストールされているすべての ODBC ドライバーが表示されます。次に、DSN を作成します。「/etc/odbc.ini」ファイルを編集し、以下を追加します。

  [<DSN name>]
  Driver = /usr/lib/psqlodbc.so
  Description = PostgreSQL Data Source
  Servername = <Data Virtualization Host name or ip>
  Port = 35432
  Protocol = 7.4-1
  UserName = <user-name>
  Password = <password>
  Database = <vdb-name>
  ReadOnly = no
  ServerType = Postgres
  ConnSettings =
  UseServerSidePrepare=1
  Debug=0
  Fetch = 10000
  # enable below when dealing large resultsets to enable cursoring
  #UseDeclareFetch=1

"/etc/odbc.ini ファイルを編集するには、「sudo」パーミッションが必要な点に注意してください。DSN の定義に使用できる設定可能なすべてのオプションは、「postgreSQL ODBC」ページを参照して ください。

DSN の定義が完了したら、以下のコマンドを実行して DSN を確認できます。

isql <DSN-name> [<user-name> <password>] < commands.sql

「commands.sql」ファイルには、実行する SQL コマンドが含まれています。commands.sql ファイルを省略すると、インタラクティブシェルで提示されます。

たとえば、NW モデルに 顧客 テーブルがある northwind deployed という名前の vdb がある場合は、URL 経由で HTTP GET でそのテーブルにアクセスできます。

http://localhost:8080/odata/customers

これは、JDBC/ODBC 接続を作成し、SQL を発行するためのフォークになります。

SELECT * FROM NW.customers

OData クエリーから返される結果は Atom/AtomPub XML または JSON 形式になります。JSON 結果はデフォルトで返されます。

ユーザーはクエリーと共に述語を送信でき、結果をフィルターできます。

http://localhost:8080/odata/customers?$filter=name eq 'bob'

これは、JDBC/ODBC 接続を作成し、SQL を発行するのと似ています。

SELECT * FROM NW.customers where name = 'bob'

特定の形式で結果をフォーマットするよう要求するには、クエリーオプション $format を追加します。

http://localhost:8080/odata/customers?$format=JSON

必要に応じて、クエリーオプションを組み合わせることができます。フィルターを使用した例を以下に示します。

http://localhost:8080/odata/customers?$filter=name eq 'bob'&$format=xml

OData を使用すると、あるエンティティーから別のエンティティーへナビゲーションをクエリーできます。ナビゲーションは、リレーショナルデータベースの外部キー関係に似ています。

たとえば、customer テーブルが customer_fk と呼ばれる顧客のプライマリーキーの orders テーブルにキーをエクスポートしている場合、OData GET は以下のように発行できます。

http://localhost:8080/odata/customers(1234)/customer_fk?$filter=orderdate gt datetime'2012-12-31T21:23:38Z'

これは、JDBC/ODBC 接続を作成し、SQL を発行するためのフォークになります。

SELECT o.* FROM NW.orders o join NW.customers c on o.customer_id = c.id where c.id=1234 and o.orderdate > {ts '2012-12-31 21:23:38'}

http://localhost:8080/odata/getcustomersearch(id=120,firstname='micheal')

http://localhost:8080/odata/customers?$skiptoken=xxx

{"error":{"code":null,"message":"Cannot find EntitySet, Singleton, ActionImport or FunctionImport with name 'xxx'."}}

OData プロトコルを使用すると、上記の READ 操作と共に CREATE/UPDATE/DELETE 操作を実行できます。これらの操作は、さまざまな HTTP メソッドを使用します。

INSERT/CREATE は、HTTP メソッド「POST」を使用して実行されます。

POST /service.svc/Customers HTTP/1.1
Host: host
Content-Type: application/json
Accept: application/json
{
  "CustomerID": "AS123X",
  "CompanyName": "Contoso Widgets",
  "Address" : {
     "Street": "58 Contoso St",
     "City": "Seattle"
  }
}

アップデートは、HTTP の「PUT」で実行されます。

PUT /service.svc/Customers('ALFKI') HTTP/1.1
Host: host
Content-Type: application/josn
Accept: application/json
{
  "CustomerID": "AS123X",
  "CompanyName": "Updated Company Name",
  "Address" : {
     "Street": "Updated Street"
  }
}

DELETE 操作は HTTP の「DELETE」メソッドを使用します。

DELETE /service.svc/Customers('ALFKI') HTTP/1.1
Host: host
Content-Type: application/json
Accept: application/json

"spring.teiid.odata." で始まるプロパティーにより OData インターフェースをカスタマイズできます。

|batch-size |Number of rows to send back each time, -1 returns all rows |256

|skiptoken-cache-time |Time interval between the results recycled/expired between $skiptoken requests |300000

Data Virtualization OData サーバーは、結果行が設定されたバッチサイズを超えたときにカーソルロジックを実装します。リクエストごとに batch-size の数が返されます。このような各要求は、skip-token-cache-time で指定されたアイドル時間を指定してアクティブなカーソルと見なされます。カーソルがタイムアウトすると、カーソルが閉じられ、残りの結果がクリーンアップされ、追加のクエリーに利用できなくなります。これらのカーソルのセッションベースの追跡はないため、期限切れの時間後に skiptoken の要求が再度実行され、カーソルを相対位置に再構成しようとしますが、結果としてベースとなるソースと新しい情報が更新される可能性は保証されません。

OData4 インターフェースは、一部の機能制限の対象となります。以下の機能は使用できません。

OData のアクセスは、プログラミングモデルに応じてユーザーの出所や、アクセスレイヤーを OData に書き込むさまざまな方法が必要です。いくつかの提案を以下に示します。

利用可能なその他のフレームワークおよびツールの最新情報は、http://www.odata.org/ecosystem/を参照してください。

OData は Conceptual Schema Definition Language(CSDL)を使用してスキーマを定義します。Data Virtualization の ACTIVE 状態の VDB は、CSDL 形式で表示されるメタデータを公開します。たとえば、vdb のメタデータを取得する場合は、以下のような要求を発行する必要があります。

http://localhost:8080/odata/$metadata

OData スキーマモデルはリレーショナルデータベースモデルではないため、Data Virtualization は以下のセマンティクスを使用して、リレーショナルデータベースモデルを OData スキーマモデルにマッピングします。

設計による Data Virtualization は、EntityType の "embedded" ComplexType を定義しません。

OData のアクセスはキーベースであるため、すべてのテーブル Data Virtualization が OData 経由で公開する MANDATORY であるため、PK または少なくとも 1 つの UNIQUE キーが必要です。上記のいずれかではない表は、$metadata からドロップされます。

すべてのデータロールは OData メタデータの構築で参照されないため、テーブルや手順を明示的に非表示にする必要がある場合があります。これは、オブジェクトの拡張メタデータプロパティー「teiid_odata:visible」で行うことができます。

create foreign table HIDDEN (id long primary key, ...) OPTIONS ("teiid_odata:visible" false);

teiid_odata:visible を false に設定すると、OData レイヤーは指定されたオブジェクトを公開しません。

データタイプマッピング

geography および Geometry は、関連する {http://www.teiid.org/translator/spatial/2015}type プロパティーに基づいて、対応する Edm.GeometryXXX および Edm.GeographyXXX タイプにマッピングされます。Edm.Geometry または EdmGeography への一般的なマッピングは、値を正しくシリアライズできません。

可能な場合、配列タイプはコレクションタイプにマップされます。ただし、多次元のアレイを含めることはできません。また、配列/コレクションの値はパラメーターまたは比較として使用できません。

実験的機能 は、$metadata ではなく [swagger|openapi].json を介して Swagger 2.0 / OpenAPI メタデータを自動的に提供することができます。

http://localhost:8080/odata/swagger.json
http://localhost:8080/odata/openapi.json
http://localhost:8080/odata/openapi.json?version=2

http://localhost:8080/odata/openapi.json?version=3

superset は オープンソースのデータ可視化およびダッシュボードビルダーです。SQLAlchemy を使用してリレーショナルデータベースにアクセスします。

上記の指示に従うと、Sources メニューの下に Database を追加して、Data Virtualization VDB にアクセスできます。

URL は、SQLAlchemy 統合と同じ形式(postgresql+psycopg2://user:password@host:35432/vdb)で表示されます。

集約およびすべての基本タイプに関連する基本的な使用シナリオがテストされています。必要な追加機能がある場合は、機能強化リクエストをログに記録してください。

Connection クラスは autoCommit フラグを使用して、ローカルトランザクションを明示的に制御します。デフォルトでは、autoCommit は、リクエストレベルまたは暗黙的なトランザクション制御を示す true に設定されます。

autoCommit フラグを false に設定して、ローカルトランザクションの使用例。

// Set auto commit to false and start a transaction
connection.setAutoCommit(false);

try {
    // Execute multiple updates
    Statement statement = connection.createStatement();
    statement.executeUpdate("INSERT INTO Accounts (ID, Name) VALUES (10, 'Mike')");
    statement.executeUpdate("INSERT INTO Accounts (ID, Name) VALUES (15, 'John')");
    statement.close();

    // Commit the transaction
    connection.commit();

} catch(SQLException e) {
    // If an error occurs, rollback the transaction
    connection.rollback();
}

以下の例では、いくつかのことを紹介します。

以下の操作のいずれかがローカルトランザクションを終了します。

disableLocalTxn=true

ODBC クライアントにも適用されるトランザクション制御ステートメントが、ローカルトランザクション境界を明示的に制御します。関連するステートメントは以下のとおりです。

クエリー式（または非推奨の SELECT INTO）で INSERT を実行する場合、別のソース INSERTS で処理される複数の挿入バッチは Data Virtualization サーバーで処理される可能性があります。対象となるソースが XA をサポートするか、または障害発生時に補正アクションが実行されるようにしてください。

グローバル、ローカル、およびリクエストレベルのトランザクションの使用はすべて相互に排他的です。リクエストレベルのトランザクションは、グローバルまたはローカルトランザクションにない場合にのみ適用されます。グローバルトランザクションとローカルトランザクションを同時に組み合わせようとすると、例外が発生します。

EIS システムおよび EIS システム自体を表す基礎となるデータソースは、Data Virtualization 経由で分散 XA トランザクションに参加したい場合は XA トランザクションをサポートする必要があります。ソースシステムが XA に対応していない場合、分散トランザクションに完全に参加できません。ただし、ソースは引き続き XA サポートなしでデータ統合に参加できます。

XA トランザクションへの参加は、ソースの XA 機能を基に自動的に決定されます。XA リソースが分散トランザクションに参加する必要がある場合に XA リソースを設定するのはユーザーの責任です。