Sun N1 Service Provisioning System 5.2 プラグイン開発ガイド

第 4 章アプリケーションプログラミングインタフェースの使用

この章では、Java ベースのアプリケーションプログラミングインタフェース (API) のクラスやメソッドを使用してサービスプロビジョニングソフトウェアを拡張する方法について説明します。各 API クラスとメソッドの具体的な構文については、プロビジョニングシステムに付属の Javadoc^TM 情報を参照してください。

この章の内容は、次のとおりです。

サービスプロビジョニング用の Java API の使用

N1 SPS には、システムの機能をさらに拡張できる Java ベースの API が含まれます。この API には、主に次の 3 つのコンポーネントがあります。

「コンポーネント API」 – コンポーネント一覧の表示など、コンポーネント固有の機能を作成できます
「execJava API」 – 任意の Java コードを実行できます
「コマンド行 API」 – コマンドを含むスクリプトを呼び出さずに Java アプリケーションから直接 N1 SPS のコマンド行機能を利用できます

コンポーネント API

Java ベースのコンポーネント API によって、プラグインにエクスポート機能と一覧機能を提供できます。ユーザーは、Sun N1 Service Provisioning System のブラウザインタフェースでディレクトリ構造を表示し、ファイルをエクスポートできます。

com.sun.n1.sps.componentdb

このパッケージには、コンポーネントデータベースを操作するためのインタフェースが 2 つあります。

InstallMode – コンポーネントのインストールモードの強く型付けされた列挙
InstallMode.Factory – InstallMode 列挙のファクトリインタフェース

com.sun.n1.sps.plugin

このパッケージには、プラグイン関連の一般機能をサポートする 1 つのインタフェースと 3 つのクラスが含まれます。

AgentContext – このインタフェースは、リモートエージェントでプラグインのコードから使用可能なサービスを発行します。
Logger – このハイレベルのラッパークラスは、サービスプロビジョニングプロジェクトのログインに使用します。
PluginMessage – このクラスのインスタンスを使用して、プラグイン実装内のメッセージを国際化します。
PluginException – メッセージの解決に PluginMessage を使用する例外を表すクラスです。

com.sun.n1.sps.plugin.browse

このパッケージには、一覧機能を指定する 5 つのインタフェースと 4 つのクラスが含まれます。

Browser – このインタフェースは、一覧をサポートするリソースハンドラがエクスポートする必要がある一連の機能を定義します。
BrowserDisplay – このインタフェースは、表示をより有益かつ正確にするために階層マネージャの「UI Browsing」部分で使用されます。
BrowserFactory – このインタフェースは、ローダーが適切なブラウザの実際のインスタンスを取得するために使用するインタフェースです。
BrowserFilter – このインタフェースは、特定の条件に従ってノードにフィルタを適用する方法を示します。
BrowserNode – このインタフェースは、一覧可能な階層ノードの機能を定義します。
BrowserContext – このクラスは、クライアントが一覧セッションの初期パラメータを設定するためのコンテナを提供します。
BrowserInfo – このクラスは、ユーザーインタフェースでの表示とシステム内からの実際のインスタンスの取得に適切なブラウザを示します。
BrowserNodeBase – このクラスは、BrowserNode インタフェースのデフォルトの実装を提供します。
BrowserException – このクラスは、一覧セッションからスローする型付けされた例外を指定します。

一覧機能の詳細と例については、「一覧機能」を参照してください。

com.sun.n1.sps.plugin.export

このパッケージには、コンポーネントの定義と作成機能を指定するための 7 つのインタフェースと 1 つの例外クラスが含まれます。

ComponentExporter – 一覧プロセスからコンポーネントを作成するには、すべてのプラグインでこの基本インタフェースを実装する必要があります。
ComponentMonitor – システムによって作成され、特定のコンポーネントのコンポーネント作成プロセスを管理するモニターです。
ComponentToken – 包含コンポーネントを CompositeComponentMonitor に追加するためにコンポーネントを表すトークンです。
CompositeComponentMonitor – ほかのコンポーネントを含むコンポーネントのモニターです。
ResourceProcessor – リソースのイントロスペクションを可能にします。
SimpleComponentMonitor – リソースを含むコンポーネントのモニターです。
SystemData – 現在のエクスポートと一覧の処理に関連するさまざまな持続システムオブジェクトによって定義される変数へのアクセスを提供します。
ComponentExportException – コンポーネントのエクスポートに関連するエラーに使用する強く型付けされた例外です。

エクスポート機能の詳細と例については、「エクスポート機能」を参照してください。

com.sun.n1.sps.resource

このパッケージには、リソースを管理するための 7 つのインタフェースと 1 つの例外が含まれます。

CheckInMode – チェックインモードを表す強く型付けされた列挙です。
CheckInMode.Factory – CheckInMode 列挙のファクトリインタフェースです。
ResourceEntry – リソース内のエントリを表します。
ResourceEntryIterator – ResourceEntry オブジェクトの反復子です。
ResourceManifest – リソースを表すマニフェストです。
ResourceType – リソースタイプを表す強く型付けされた列挙です。
ResourceType.Factory – ResourceType 列挙のファクトリインタフェースです。
ResourceException – リソースに関連するエラー状態からスローされる型付けされた例外です。

com.sun.n1.util

このパッケージには、ユーティリティーを管理するための 1 つのインタフェースと 3 つの追加パッケージが含まれます。

RPCSerializable – このインタフェースは、RPC によって直列化できるオブジェクトを指定します。
com.sun.n1.util.enum – このパッケージには、2 つのインタフェースと 1 つの例外クラスが含まれます。
- Enum – 強く型付けされた列挙用のインタフェースです。
- Enum.Factory – クライアントが、特定の Enum サブクラスに定義された値をすべて検索し、また整数値または文字列値で特定の値を検索できるようにします。
- NoSuchEnumException – 列挙の検索に失敗したことを示す例外クラスです。
com.sun.n1.util.message – このパッケージには、2 つのインタフェースが含まれます。
- Severity – メッセージに関連付けられた重要度を表す強く型付けされた列挙です。
- Severity.Factory – Severity 列挙のファクトリインタフェースです。
com.sun.n1.util.vars – このパッケージには、3 つのインタフェースと 3 つのクラスが含まれます。
- DisplayMode – 表示モードの、強く型付けされた列挙です。
- DisplayMode.Factory – DisplayMode 列挙のファクトリインタフェースです。
- VariableSettingsSource – 変数設定のソースとして使用できるオブジェクトのインタフェースを定義します。
- PromptParam – テキストのプロンプトと表示モードを含む、プロンプトの構造に関する情報を含むパラメータです。
- PromptParamList – PromptParam オブジェクトの一覧です。
- VariableSettingsHolder – 変数の名前と値の組み合わせの指定に使用できる VariableSettingsSource インタフェースの実装です。

一覧機能

com.sun.n1.sps.plugin.browse パッケージには、一覧機能を指定する 5 つのインタフェースと 4 つのクラスが含まれます。

Browser – 一覧機能をサポートするには、リソースハンドラでこの基本インタフェースを使用する必要があります。
BrowserDisplay – このインタフェースは、表示をより有益かつ正確にするために階層マネージャの「Browsing」部分で使用されます。
BrowserFactory – このインタフェースは、ローダーが適切なブラウザの実際のインスタンスを取得するために使用するインタフェースです。
BrowserFilter – このインタフェースは、特定の条件に従ってノードにフィルタを適用する方法を示します。
BrowserNode – このインタフェースは、一覧可能な階層ノードの機能を定義します。
BrowserContext – このクラスは、クライアントが一覧セッションの初期パラメータを設定するためのコンテナを提供します。
BrowserInfo – このクラスは、ユーザーインタフェースでの表示とシステム内からの実際のインスタンスの取得に適切なブラウザを示します。
BrowserNodeBase – このクラスは、BrowserNode インタフェースのデフォルトの実装を提供します。
BrowserException – このクラスは、一覧セッションからスローする型付けされた例外を指定します。

ブラウザ API の実装

ブラウザ実装には、次の主な API セグメントが含まれます。

BrowserFilter[] getAvailableFilters(): このブラウザがサポートするフィルタを返します。BrowserFilter インタフェースを使用して、特定の条件に基づいた BrowserNodes を選別します。たとえば、*.tmp ファイルだけを表示するフィルタを適用できます。
BrowserDisplay getDisplay(): このブラウザで使用する表示プロパティオブジェクトを取得します。
BrowserNode getNode(java.lang.String location): 階層内でこのブラウザが表すノードを返します。
void setFilterName(java.lang.String name): 一覧時に使用するフィルタを指定します。

`BrowserNode` クラス

BrowserNode クラスは、階層ツリー機能全体を実装します。この機能は次の 4 つの分野に分かれています。

ノードのすべての子を表示
ノードの親を表示
ノードがリーフノードかどうかを指定
ノードに関連するその他の説明やプロパティを表示

`BrowserFactory` インタフェース

BrowserFactory インタフェースは、HierarchyBrowserLoader が適切な HierarchyBrowser の実際のインスタンスを取得するためのインタフェースです。

BrowserFactory インタフェースを実装するクラスを定義するには、次の例のような API 呼び出しを使用します。

Browser getBrowser(BrowserContext bContext,AgentContext aContext)

各オプションの意味は次のとおりです。

bContext は、このブラウザを指定したコンポーネントエクスポート機能から取得するコンテキストです。
aContext は、ネイティブライブラリをロードする必要がある場合にエージェントに指定するコンテキストです。

BrowserFactory の実装は、システムが指定する BrowserContext オブジェクトと AgentContext オブジェクトをパラメータとして getBrowser メソッドを定義します。

システムサービス内で、browserClassPathVar 変数にブラウザファクトリの完全指定のクラス名を宣言します。次のコードフラグメントでは、システムサービスに 2 つのブラウザファクトリを定義しています。

<var 
 access="PRIVATE" 
 name="EJBFileSystemBrowser" 
 default="com.raplix.rolloutexpress.plugins.weblogic.hierarchies.ejb.EJBFileBrowserFactory"
/> 
<var 
 access="PRIVATE" 
 name="EJBDomainBrowser" 
 default="com.raplix.rolloutexpress.plugins.weblogic.hierarchies.ejb.EJBDomainBrowserFactory"
/>

一覧機能のコード例

例 4–1 ブラウザフィルタ

次の例では、名前が *.tmp のファイルだけをフィルタします。

public class TmpFilter implements BrowserFilter, ExampleFilter {

    public String getName() {
        return "tmpFilter";
    }
    public String getDescription() {
        return "show only *.tmp files";
    }
    public boolean filter(ExampleBrowserNode node) {
        return node.getLocalName().endsWith(".tmp");
    }

}

エクスポート機能

com.sun.n1.sps.plugin.export パッケージには、コンポーネントの定義と作成機能を指定するための 7 つのインタフェースと 1 つの例外クラスが含まれます。

ComponentExporter – 一覧プロセスからコンポーネントを作成するには、すべてのプラグインでこの基本インタフェースを実装する必要があります。
ComponentMonitor – システムによって作成され、特定のコンポーネントのコンポーネント作成プロセスを管理するモニターです。
ComponentToken – 包含コンポーネントを CompositeComponentMonitor に追加するためにコンポーネントを表すトークンです。
CompositeComponentMonitor – ほかのコンポーネントを含むコンポーネントのモニターです。
ResourceProcessor – リソースのイントロスペクションを可能にします。
SimpleComponentMonitor – リソースを含むコンポーネントのモニターです。
SystemData – 現在のエクスポートと一覧の処理に関連するさまざまな持続システムオブジェクトによって定義される変数へのアクセスを提供します。
ComponentExportException – コンポーネントのエクスポートに関連するエラーに使用する強く型付けされた例外です。

`ComponentExporter` プロセス

エクスポート機能を有効にするには、次のような手順に従います。

コンポーネントタイプのバッキングコンポーネントで、exporterClass 変数で componentExporter の完全指定のクラス名を宣言します。
```
<varList>
  <var name="exporterClassName" 
    default="com.sun.n1.sps.pluginimpl.sample.export.StaticCompExporter"/>
</varList>
```
ComponentExporter インタフェースを実装するクラスを定義します。

ComponentExporter で ComponentMonitor 入力引数に対してさまざまなメソッドを呼び出し、コンポーネントを構築します。addComponentVar 、addSourceInfoParam、setComponentDescription、setComponentLabel などのメソッドを使用できます。

ComponentExporter では get ルーチンを呼び出して ComponentMonitor から情報を取得することもできます。get ルーチンには、getPluginComponentVars、getPluginHostVars、getActiveBrowser、getSourceInfoParam、getLocation などがあります。

ComponentExporter では exportResource を呼び出して、制御ブロック内で、コンポーネントをエクスポートするコンポーネントタイプに固有の機能を実行することもできます。
コンポーネントの作成後、ComponentExporter では setResource を呼び出して、コンポーネントに含める物理リソースを設定し、エクスポートプロセスを完了できます。

`ComponentExporter` の例

例 4–2 `ComponentExporter`

public class  implements ComponentExporter {

    public ExampleExporter() {

    }

    public BrowserContext getBrowserContext() {
        return new BrowserContext();
    }

    public BrowserInfo[] getAvailableBrowsers() {
        return new BrowserInfo[] {
            new BrowserInfo("example",             //relevant comp type
                            "Example Browser",     //browser ui display name
                            "example ss",          //relevant ss
                            null,                  //valid for all platforms
                            null,                  //no host set restriction
                            new PromptParamList()) //no checkin params
        };
    }

    public String getBrowserClassPath(BrowserInfo browser) {
        return null;
    }
public void constructComponent(ComponentMonitor mon) 
        throws ComponentExportException {

        //It's the responsibility of the infrastructure to  identify the type
        //of component and construct the component with the appropriate monitor
        SimpleComponentMonitor sMon = (SimpleComponentMonitor)mon;

      sMon.setComponentDescription("This is an example component");
        sMon.setComponentLabel("What the hell is a label for?");
        
        sMon.setResource(ResourceType.FILE,  //our sample type is a file
                         sMon.getLocation(), //get the location specified
                         false,              //do not use differential checkin
                         false,              //not a config template
                         false,              //file->symlinks meaningless
                         true,               //capture permissions
                         null,               //file->checkinmode meaningless
                         null);              //no special processing of rsrc
    }    
}

`execJava` API

execJava 機能は、XML スキーマを通じてプランおよびコンポーネントに使用できます。必要に応じて XML で Java コードを実行できます。また、execJava には API もあります。

プリフライトと実際の動作を指定できます。クラスは通常、コンポーネントの JAR リソースを使用して配備します。execJava のクラス、メソッド、およびインタフェースについては、『Sun N1 Service Provisioning System JavaDoc』を参照してください。

<execJava
className= classname of the executor factory class
class Path=...
>

execJava API は com.sun.n1.sps.plugin.execJava パッケージに含まれます。execJava API は、5 つのインタフェースと 2 つの例外クラスから構成されます。

ActualExecJavaContext: このインタフェースは、execJava の実装が配備段階または実際の実行段階で呼び出されたときに使用可能なサービスを発行します。
ExecJavaContext: このインタフェースは、プリフライトと実際の実行レベルの両方に共通の execJava の実装の実行コンテキストを提供します。
Executor: このインタフェースは、execJava を使用してエージェントのコードを実行する必要があるクラスで実装されます。
ExecutorFactory: このインタフェースは、execJava のステップを使用してリモートエージェントで任意のコードを実行するインフラストラクチャーの一部です。
PreflightExecJavaContext: このインタフェースは、execJava の実装が実行のプリフライト段階で呼び出されたときに使用可能なサービスを発行します。
ExecutionException: ExecutionException のインスタンスを使用して、execJava の呼び出しのエラーや警告にフラグを付けます。
ExecutionTimeoutException: execJava の実行がタイムアウトになったときにこの例外のインスタンスがスローされます。

`ExecutorFactory` インタフェース

ExecutorFactory インタフェースを使用して、特定のステップのプリフライトおよび実際の実行環境のインスタンスを取得します。

Executor getActualExecutor(AgentContext callContext)
Executor getPreflightExecutor(AgentContext callContext)

プリフライトと実際の実行のステップの間で渡される呼び出しコンテキストが同じである必要はありません。

`AgentContext` メソッド

AgentContext メソッドは、特定のリモートエージェントに呼び出しコンテキストを提供します。

VariableSettingsHolder getVariables()
    // Returns the variables passed to the execJava step using <argList>

PrintStream getStandardOutput()
PrintStream getStandardError()
InputStream getStandardInput()
File getWorkingDir()

`Executor` インタフェース

Executor インタフェースは、ステップの本体の実行に使用されるエントリポイントを提供します。

void execute() throw ExecutionException

実行出力とエラー出力は、関連付けられているエージェントコンテキストの stdout と stderr のストリームに書き込まれます。入力は、関連付けられているエージェントコンテキストの入力ストリームから読み取られます。エラーは、ExecutionException クラスのインスタンスを呼び出して報告されます。

`execJava` の例

例 4–3 Java コードの `execJava`

public class StopServerFactory extends WLFactoryBase {
    
    public static final String TARGET = "serverName";
    
    public Executor 
        getActualExecutor(AgentContext inAgentContext, ActualExecJavaContext inContext) 
        {

        VariableSettingsSource variableSettings = inContext.getVariableSettings();
        String target = variableSettings.getVarValue(TARGET);
        return new StopServerExecutor(getConnect(variableSettings), target);
    }
    
    public VariableSettingsSource getParams() {
        VariableSettingsHolder list = getWLParams();
        list.setVarValue(TARGET, null);
        return list;
    }

}
public class StopServerExecutor implements Executor {
    private WLConnect mConnect;
    private String mTarget;

    /**
     *
     **/
    public StopServerExecutor(WLConnect connect, String target) {
           mConnect = connect;
           mTarget = target;
    }

    /**
     *
     **/
    public void execute() throws ExecutionException {

  try {
    WLAdminServer server = new WLAdminServer(mConnect);
    server.stopServer(server.getServer(mTarget));
    } 
catch (Exception e) {
    throw new ExecutionException
    (new PluginMessage(WLPluginHierarchyException.MSG_WEBLOGIC_ERROR), e);
    }
  }
}

例 4–4 別の `execJava` のコード例

public class SampleExecutorFactory implements ExecutorFactory
{
    public Executor getActualExecutor(AgentContext inAgentContext, 
           ActualExecJavaContext inActualExecJavaContext)
    {
        return new EnvParamSettingActualExecutor(inActualExecJavaContext);
    }

    public Executor getPreflightExecutor(AgentContext inAgentContext,
           PreflightExecJavaContext inPreflightExecJavaContext)
    {
        return new EnvParamSettingPreflightExecutor(inPreflightExecJavaContext);
    }

    public VariableSettingsSource getParams()
    {
        VariableSettingsHolder params = new VariableSettingsHolder();
        params.setVarValue(PARAM_NAME, "");
        params.setVarValue(PARAM_VALUE, "");
        return params;
    }

    public static final String PARAM_NAME = "nameParam";
    public static final String PARAM_VALUE = "valueParam";
}
public class EnvParamSettingPreflightExecutor implements Executor
{
    VariableSettingsSource mVars;
    public EnvParamSettingPreflightExecutor
           (PreflightExecJavaContext inPreflightExecJavaContext)
    {
        mVars = inPreflightExecJavaContext.getVariableSettings();
    }

    public void execute() throws ExecutionException
    {
        String propName = mVars.getVarValue(SampleExecutorFactory.PARAM_NAME);
        if("".equals(propName)) {
            throw new ExecutionException(new PluginMessage("sample.noNameParam"));
        }

        String propValue=System.getProperty(propName);
        if(!(propValue == null || "".equals(propValue))) {
            // property already set, error out
            throw new ExecutionException(new PluginMessage("sample.propAlreadySet",
                                        new String[]{propName, propValue}));
        }
    }
}

public class EnvParamSettingActualExecutor implements Executor
{
    VariableSettingsSource mVars;
    public EnvParamSettingActualExecutor(ActualExecJavaContext inCtx)
    {
        mVars  = inCtx.getVariableSettings();
    }

    public void execute() throws ExecutionException
    {
        String propName = mVars.getVarValue(SampleExecutorFactory.PARAM_NAME);
        String propValue = mVars.getVarValue(SampleExecutorFactory.PARAM_VALUE);
        System.setProperty(propName, propValue);
        if(Logger.isDebugEnabled(this)) {
            Logger.debug("Setting prop "+propName + " to " + propValue, this);
        }
        System.out.println("Setting prop "+propName + " to " + propValue);
    }
}

コマンド行 API

公開 API は、製品メディアの sps-compSDK.jar ファイルにあります。これらの Java クラスとメソッドを使用すると、独自の Java コードを開発して N1 SPS の機能を利用できます。公開 API については、『Sun N1 Service Provisioning System JavaDoc』を参照してください。

始める前に

コマンド行 API を使用するには、CommandManagerBuilder から CommandManager を取得する必要があります。次のコード例に、CommandManager を取得する方法を示します。

public class CommandManagerBuilder {

  /**
    *  Set the directory for the CLI installation directory
    */
    public setHomeDirectory(File cliHomeDir){ ... }

  /**
    *  Build a command manager with the properties set in this class
    *  @throws ConfigurationException incorrect properties 
    *  specified for a valid CommandManager
    */
    public CommandManager build() throws ConfigurationException {...}

}

注 –

構築メソッドの呼び出しは、負荷が大きい処理です。したがって、コマンドを実行する CommandManager は 1 つだけ作成するようにします。

エラーの処理

コマンド行 API と実際のコマンド実行では、次の Java 例外が発生する可能性があります。

AuthenticationException - ログイン時のユーザー名とパスワードが不正
Network Exception - ネットワークトランスポートの問題
CommandException - MS でのコマンド実行時のエラー
ConfigurationException - 不正な CLI ディレクトリレイアウトまたはその他の起動時の問題

パッケージの概要

com.sun.n1.sps.client: CLI コマンドを実行し、マスターサーバーに対してクエリーを実行するためのクラスとインタフェースが含まれます
com.sun.n1.sps.model: N1 SPS オブジェクトのバージョン番号、可視性、および ID を特定するためのクラスとインタフェースが含まれます
com.sun.n1.sps.model.category: コンポーネントやプランなどの関連するオブジェクトをカテゴリにグループ分けするための 3 つのインタフェースが含まれます
com.sun.n1.sps.model.component: コンポーネント情報を定義するためのインタフェースとクラスが含まれます
com.sun.n1.sps.model.difference: プロビジョニングの比較を定義するためのインタフェースとクラスが含まれます
com.sun.n1.sps.model.executor: プランおよび OS のネイティブコマンドを実行するためのインタフェースとクラスが含まれます
com.sun.n1.sps.model.folder: N1 SPS のフォルダを定義するためのインタフェースが含まれます
com.sun.n1.sps.model.host: ホストセット、ホスト ID、ホスト検索、特定のホストで実行されているアプリケーション、特定ホストのアップグレード処理など、ホストの条件を定義するためのインタフェースとクラスが含まれます
com.sun.n1.sps.model.install: ターゲットホストにインストールされているコンポーネントに関する情報を収集するためのインタフェースが含まれます
com.sun.n1.sps.model.plan: N1 SPS のプランを実行するためのインタフェースとクラスが含まれます
Package com.sun.n1.sps.model.plugin: プラグインを定義し、ほかのユーザーがブラウザインタフェースでこれらのプラグインを一覧できるようにするためのインタフェースが含まれます
com.sun.n1.sps.model.resource: リソースを定義するためのインタフェースが含まれます
com.sun.n1.sps.model.rule: 特定の処理の条件と規則を定義するためのインタフェースとクラスが含まれます
com.sun.n1.sps.model.user: ユーザーとグループのアクセス権、ID、および変数を設定するためのインタフェースとクラスが含まれます
com.sun.n1.sps.model.util: ping および traceroute を使用してネットワーク接続の基本的な検証を行うためのインタフェース、クラス、および例外が含まれます
com.sun.n1.util.collections: 一覧およびセットを定義するためのインタフェースが含まれます
com.sun.n1.util.enum: 列挙および列挙型のインタフェース、クラス、および例外が含まれます
com.sun.n1.util.vars: 変数設定のソースを特定するための 1 つのインタフェースが含まれます

第 4 章 アプリケーションプログラミングインタフェースの使用

サービスプロビジョニング用の Java API の使用

コンポーネント API

一覧機能

ブラウザ API の実装

BrowserNode クラス

BrowserFactory インタフェース

一覧機能のコード例

例 4–1 ブラウザフィルタ

エクスポート機能

ComponentExporter プロセス

ComponentExporter の例

例 4–2 ComponentExporter

execJava API

ExecutorFactory インタフェース

AgentContext メソッド

Executor インタフェース

execJava の例

例 4–3 Java コードの execJava

例 4–4 別の execJava のコード例