Cisco SCMS SM Java API プログラマ ガイド Release 3.1
API の基礎知識
API の基礎知識
発行日;2012/01/07 | ドキュメントご利用ガイド | ダウンロード ; この章pdf , ドキュメント全体pdf (PDF - 497KB) | フィードバック

目次

API の基礎知識

ブロッキング API とノンブロッキング API

ブロッキング API

ノンブロッキング API

API の初期化

API の構築

LEG 名を受け入れるコンストラクタ

例(ブロッキング API)

セットアップ操作

ブロッキング API のセットアップ

ノンブロッキング API のセットアップ

SM への接続

API の終了

サブスクライバ名のフォーマット

ネットワーク ID マッピング

IP アドレス マッピングの指定

IP 範囲マッピングの指定

VLAN タグ マッピングの指定

サブスクライバ ドメイン

サブスクライバ プロパティ

カスタム プロパティ

切断リスナ インターフェイス

DisconnectListener インターフェイス例

例外

実用的なヒント

ブロッキング API とノンブロッキング API

ここでは、ブロッキング API とノンブロッキング API の操作の相違点について説明します。

「ブロッキング API」

「ノンブロッキング API」

ブロッキング API

一般的な API であるブロッキング API 操作では、どのメソッドも、操作の 完了後に 戻ります。

SM Blocking Java API は広範な操作を提供します。この API には、ノンブロッキング API の機能のほとんどに加え、ノンブロッキング API にはない機能も多く含まれています。ブロッキング API は、信頼性機能や自動再接続機能には対応しません。

ノンブロッキング API

ノンブロッキング Java API 操作では、メソッドはたとえ操作が完了していなくても ただちに 戻ります。操作結果は、Observer オブジェクト(リスナ)に戻るか、またはまったく戻りません。

ノンブロッキング API メソッドは、入出力が含まれていて時間がかかるような操作の場合に有効です。別のスレッドで操作を実行すれば、呼び出しプログラムはほかのタスクを続行できるので、全体のシステム パフォーマンスが向上します。

SM Non-blocking Java API には、ノンブロッキング操作がいくつか含まれています。この API は、結果リスナによる操作結果の取得をサポートしています。

SM Non-blocking Java API は、信頼と非信頼という 2 種類のモードで使用できます。信頼モードについては、「信頼性のサポート」を参照してください。

API の初期化

API の初期化には、主に次の 3 つの手順があります。

いずれかのコンストラクタを使用し、API を構築します。

API 固有のセットアップ操作を実行します。

API を SM に接続します。

以下では、上記の 3 つの手順について詳しく説明します。

初期化の例は、各 API のコード例を参照してください。

「API の構築」

「セットアップ操作」

「SM への接続」

API の構築

ブロッキング API とノンブロッキング API には、共通のコンストラクタが 2 つあります。

空のコンストラクタ

パラメータとして LEG 名を受け入れるコンストラクタ

LEG 名を受け入れるコンストラクタ

SM で SM-LEG 障害ハンドリング オプションを有効にするには、LEG 名を設定します。『 Cisco SCMS Subscriber Manager User Guide 』の LEG ソフトウェア コンポーネントと SM-LEG 障害ハンドリングについての説明を参照してください。

LEG 名は、接続障害から回復するときに SM が使用します。LEG 名には、次のように API を識別する文字列定数が付加されます。

ブロッキング API: .B.SM-API.J

ノンブロッキング API: .NB.SM-API.J

例(ブロッキング API)

設定した LEG 名が my-leg.10.1.12.45-version-1.0 の場合、実際の LEG 名は my-leg.10.1.12.45-version-1.0.B.SM-API.J になります。

LEG 名を設定しないと、名前のプレフィックスとして、そのマシンのホスト名が使用されます。

LEG-SM 障害ハンドリングに関する詳細は、『 Cisco SCMS Subscriber Manager User Guide 』の「Configuration File Options」を参照してください。

ノンブロッキング API では、その他のコンストラクタも使用できます。詳細は、「ノンブロッキング API の構築」を参照してください。

セットアップ操作

セットアップ操作は、2 つの API で異なります。どちらの API も、「切断リスナ インターフェイス」に説明されている切断リスナの設定をサポートしています。

「ブロッキング API のセットアップ」

「ノンブロッキング API のセットアップ」

ブロッキング API のセットアップ

ブロッキング API をセットアップするには、操作タイムアウト値を設定する必要があります。詳細は、「ブロッキング API」を参照してください。

ノンブロッキング API のセットアップ

ノンブロッキング API をセットアップするには、切断リスナを設定する必要があります。詳細は、「ノンブロッキング API」を参照してください。

SM への接続

SM に接続するには、以下のいずれかの connect メソッドを使用します。

次の方法で、SM への接続にデフォルトの RPC TCP ポート(14374)を使用します。

connect(String host)

次の方法で、API の接続に使用する TCP ポートを呼び出し側が設定できます。

connect(String host, int port)

いずれの方法でも、host パラメータは、IP アドレスまたは到達可能なホスト名で指定できます。

isConnected メソッドにより、API の操作中いつでも、API が接続されているかどうかを確認できます。

API の終了

サーバとクライアントの両方のリソースを解放するには、 disconnect メソッドを使用します。

たとえば、次のようにメイン クラスで finally ステートメントを使用することを推奨します。

public static void main(String [] args) throws Exception {
SMNonBlockingApi smnbapi = new SMNonBlockingApi();
try {
...
}
finally {
smnbapi.disconnect();
}}

サブスクライバ名のフォーマット

どちらの API も、ほとんどのメソッドは入力パラメータとしてサブスクライバ名を必要とします。ここでは、サブスクライバ名のフォーマット ルールについて説明します。

使用できる文字数は最大 64 文字です。ASCII コード 32 ~ 126 の印刷可能な文字が使用できますが、34(")、39(')、および 96(`)は除きます。

ネットワーク ID マッピング

ネットワーク ID マッピングは、SCE デバイスが特定のサブスクライバ レコードと関連付けることのできるネットワーク識別子です。たとえば IP アドレスは、ネットワーク ID マッピング(または単純にマッピング)の典型的な例です。現在のところ、Cisco Service Control ソリューションでは、IP アドレス、IP 範囲、VLAN のマッピングがサポートされています。

ブロッキング API とノンブロッキング API のいずれにも、パラメータとしてマッピングを受け入れる操作が含まれています。例:

The addSubscriber 操作(ブロッキング API)

login メソッド(ブロッキング API またはノンブロッキング API)

API メソッドでマッピングを行う場合、呼び出し側は次に示す 2 つのパラメータを要求されます。

java.lang.String マッピング識別子またはマッピング型の配列

short マッピング型またはマッピング型の配列

配列を渡す場合、 mappingTypes 配列に含まれる要素の数は、 mappings 配列の要素数と同じであるか、または 1 つです。 mappingTypes 配列内の要素が 1 つの場合、すべてのマッピングがこの単一要素と同じ型になります。

API は、次に示すサブスクライバ マッピング型をサポートしています。

IP アドレスまたは IP 範囲

VLAN タグ

詳細については、『 Cisco SCMS Subscriber Manager User Guide 』を参照してください。

「IP アドレス マッピングの指定」

「IP 範囲マッピングの指定」

「VLAN タグ マッピングの指定」

IP アドレス マッピングの指定

IP アドレスの文字列フォーマットには、一般的に次のような 10 進表記法が使用されています。

IP-Address=[0-255].[0-255].[0-255].[0-255]

216.109.118.66

IP アドレスのマッピングの型は、 com.pcube.management.api.SMApiConstants インターフェイスで指定します。

com.pcube.management.api.SMApiConstants.MAPPING_TYPE_IP は、マッピング識別子がマッピング識別子配列内の同じインデックスと一致する単一の IP マッピングを指定します。

com.pcube.management.api.SMApiConstants.ALL_IP_MAPPINGS は、マッピング識別子配列内のすべてのエントリが IP マッピングであることを指定します。

IP 範囲マッピングの指定

IP 範囲の文字列フォーマットは、10 進表記法の IP アドレスおよびビット マスク内の 1 の数を表す 10 進数です。

IP-Range=[0-255].[0-255].[0-255].[0-255]/[0-32]

10.1.1.10/32 は、フル マスクの IP 範囲、つまり正規の IP アドレスです。

10.1.1.0/24 は、24 ビット マスクの IP 範囲で、 10.1.1.0 から 10.1.1.255 までの範囲のアドレスすべてを表します。


) IP 範囲のマッピング型は、IP アドレスのマッピング型と同じです。


VLAN タグ マッピングの指定

VLAN タグ マッピングの文字列フォーマットは VLAN-tag = 0-4095 です。

値は指定範囲の 10 進数です。

マッピングの型は、 com.pcube.management.api.SMApiConstants インターフェイスで指定します。

com.pcube.management.api.SMApiConstants.MAPPING_TYPE_VLAN は、マッピング識別子がマッピング識別子配列内の同じインデックスと一致する単一の VLAN マッピングを指定します。

com.pcube.management.api.SMApiConstants.ALL_VLAN_MAPPINGS は、マッピング識別子配列内のすべてのエントリが VLAN マッピングであることを指定します。

サブスクライバ ドメイン

The ドメインの詳細については、『 Cisco SCMS Subscriber Manager User Guide 』を参照してください。簡単にいえば、ドメインとは、どの SCE デバイスのサブスクライバ レコードをアップデートするかを SM に伝える識別子です。

ドメイン名は、 String 型です。システム ドメイン名は、システム導入時にネットワーク管理者が決めるので、導入システムによってさまざまです。API には、サブスクライバが所属するドメインを指定するメソッドやシステムのドメイン名に関するクエリーを許可するメソッドが含まれています。ある API 操作で SM ドメイン リポジトリにないドメイン名が指定された場合、その操作はエラーとみなされ、 RpcErrorException が戻ります。

SM の自動ドメインローミング機能により、アップデートしたドメイン パラメータを持つサブスクライバ向けの方法を利用して、サブスクライバはドメイン間を移動することができます。


) 自動ドメイン ローミングは、サブスクライバのドメイン変更が出来なかった SM API の旧バージョンとの下位互換性はありません。


サブスクライバ プロパティ

サブスクライバ プロパティを扱う操作もいくつかあります。サブスクライバ プロパティは、サブスクライバによって生成されたネットワーク トラフィックに対する SCE の分析や反応に影響する一組のキー値です。

プロパティの詳細については、『 Cisco SCMS Subscriber Manager User Guide 』および『 Cisco Service Control Application for Broadband User Guide 』を参照してください。アプリケーション ユーザ ガイドには、アプリケーション固有の情報が記載されているので、ご使用のシステムで稼働しているアプリケーション内のサブスクライバ プロパティ、許可値、各プロパティ値の重要性を知ることができます。

Java API 操作のサブスクライバ プロパティをフォーマットするには、文字列配列 propertyKeys および propertyValues を使用します。


) この配列は同じ長さにする必要があり、また NULL エントリは許可されません。キー配列内の各キーには値の配列内に一致するエントリがあります。たとえば、propertyKeys[j] の値は propertyValues[j] にあります。IP 範囲のマッピング型は IP アドレスのマッピング型と同じです。


プロパティ キー配列が {"packageId","monitor"} でプロパティ値配列が {"5","1"} である場合、プロパティは packageId=5 , monitor=1 となります。

カスタム プロパティ

カスタム プロパティを扱う操作もあります。カスタム プロパティはサブスクライバ プロパティと似ていますが、サブスクライバのトラフィックに対する SCE の分析や操作には影響しません。アプリケーション管理モジュールはカスタム プロパティを使用して各サブスクライバに関する追加情報を保存します。

カスタム プロパティをフォーマットするには、「サブスクライバ プロパティ」のフォーマットと同様に、 文字列 配列の customPropertyKeys および customPropertyValues を使用します。

切断リスナ インターフェイス

ブロッキングとノンブロッキングのいずれの API も、切断リスナの設定が可能です。切断リスナは、単一のメソッドによるインターフェイスです。

public interface DisconnectListener {
/**
* called when the connection with the server is down.
*/
public void connectionIsDown();
}

API が SM から切断されたときに通知を受けるようにするには、このインターフェイスを実装します。

切断リスナの設定には、 setDisconnectListener メソッドを使用します。

DisconnectListener インターフェイス例

次の例では、 stdout にメッセージを出力して終了する簡単な切断リスナの実装です。

import com.pcube.management.framework.rpc.DisconnectListener;
public class MyDisconnectListener implements DisconnectListener {
public void connectionIsDown(){
System.out.println("Message: connection is down.");
System.exit(0);
}
}

例外

SM Java API のすべての関数エラーは、同じ Java クラスの
com.pcube.management.framework.rpc.RpcErrorException
で提供されます。これは、通常の Java の使い方とは対照的です。このような「対照的」なアプローチが採用されたのは、SM API の「言語横断的」な特性のためです。このようなアプローチを採ることによって、SM API の実装(Java、C、C++)は、概観上の統一性を保つことができます。

各例外は、次の情報を提供します。

固有のエラー コード( long

情報メッセージ( java.lang.String

サーバ側スタック トレース( java.lang.String

エラー コードは、 com.pcube.management.api.SMApiConstants を使用して解釈できます。エラー コードとその重要性についての詳細は、「エラー コードのリスト」を参照してください。


) ブロッキング API 使用時のみに発生するエラーもいくつかあります。また、操作タイムアウト処理に関連した操作エラーもあります。これらについての詳細は、「ブロッキング API」を参照してください。


実用的なヒント

API とアプリケーションを統合するコードを実装する場合、次の実用的なヒントを考慮する必要があります。

SM に接続したら、API を何度も使用して SM へのオープンな API 接続を常時維持します。接続を確立することは、SM 側と API クライアント側にリソースを割り当てるタイムリーな手順です。

スレッドの間で API 接続を共有します。LEG ごとに 1つの接続を持つことを推奨します。複数の接続では、SM 側とクライアント側でより多くのリソースを必要とします。

API に対するコールの同期化を実行しないでください。クライアントが API に対するコールを自動的に同期化します。

API クライアント(LEG)を SM マシン プロセッサ番号と同じ順で配置することを推奨します。

LEG アプリケーションにログオン操作のバーストがある場合、このバーストを保持するため内部バッファ サイズを適宜拡大します(ノンブロッキング式)。

統合中、問題が発生したときに統合をトラブルシューティングするため、SM ログ内に API 操作を表示するよう SM logon_logging_enabled 設定パラメータを設定します。

ノンブロッキング操作の戻り値をログ/出力する LEG アプリケーションのデバッグ モードを使用します。

SM への接続の復元力を改善するには、自動再接続機能を使用します。

クラスタのセットアップでは、1 つのマシンの管理 IP アドレスではなく、クラスタの仮想 IP アドレスを使用して API を接続します。