3 SCS APIの理解

UCPM APIは、コンテンツ・サーバーと通信するAPIの呼出しであるサービスAPIのセットにモデル化されます。

この章の構成は、次のとおりです。

• 「SCS APIへのアクセス」

• 「SCS APIオブジェクトの理解」

• 「SCS APIサーブレットの理解」

• 「SCS APIの使用」

  
  

  注意: クラス/インタフェース、フィールドおよびメソッドの詳細は、Oracle Fusion Middleware Content Integration Suite (CIS) Java APIリファレンスを参照してください。

  
  

3.1 SCS APIへのアクセス

UCPM APIは、getUCPMAPI ()メソッドを介してCISApplicationクラスで使用できます。getUCPMAPI ()メソッドは、IUCPMAPIオブジェクトへの参照を戻し、すべてのUCPM APIオブジェクトにアクセスできます。パブリックなインタフェースであるIUCPMAPIは、SCS、SISおよびCISのAPIオブジェクトのロケータです。SCS APIは、SCSActiveAPIオブジェクトへの参照を戻すgetActiveAPI ()を介して使用できます。

完全修飾メソッド名は次のようになります。

CISApplication.getUCPMAPI ().getActiveAPI ()

SCS APIには、次のものが含まれます。

• ISCSSearchAPI: これは、検索コマンドのコマンドAPI実装です。

• ISCSFileAPI: コンテンツ・サーバーからのファイルの取得、およびファイルの動的変換を処理します。

• ISCSWorkflowAPI: ユーザーのワークフロー・キューを表示し、コンテンツ・サーバーのワークフロー・エンジンと対話しながら、承認および拒否などのワークフロー・コマンドを処理します。

• SCSドキュメントAPI (ISCSDocumentCheckinAPIおよびISCSDocumentCheckoutAPI)は、コンテンツのチェックインとチェックアウト、コンテンツ情報、コンテンツの削除など、コンテンツ・サーバー内のアクティブ・コンテンツを処理します。

• 管理コマンド、コンポーネント・コマンドなどの実装のための様々なAPI。

ICommandFacadeインタフェースは、コマンド・インタフェースへのエントリ・ポイントです。これは、コマンドの取得、登録、実行などのコマンド・レイヤーとの対話を可能にします。コマンドは名前で参照され、名前は任意の文字列です。ドット文字(.)で構成される名前は、最初のセグメントは最上位レベルのカテゴリ、次のセグメントは第2レベルのカテゴリというように、階層として処理されます。コマンドは、その完全なコマンド名で取得するか、または使用可能なすべてのコマンドを参照できます。

完全修飾クラス名は次のようになります。

com.stellent.command.ICommandFacade

ISCSDocumentCheckinCommandAPIを使用する例:

ISCSDocumentCheckinCommandAPI commandAPI =
  (ISCSDocumentCheckinCommandAPI)m_commandFacade.
    getCommandAPI ("document.checkin");

3.2 SCS APIオブジェクトの理解

SCS APIは、コンテンツ・サーバーへのリクエストの組立てを担当します。SCS APIの呼出しは、1つ以上のIDCサービス(Content Serverサービス)の呼出しに変換されます。

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

• 「インタフェースISCSObject」

• 「インタフェースICISTransferStream」

• 「インタフェースISCSServerBinder」

• 「インタフェースISCSServerResponse」

• 「インタフェースISCSRequestModifier」

3.2.1 インタフェースISCSObject

ISCSObjectは、SCS APIのすべてのオブジェクトのベース・インタフェースです。ICISObjectを継承し、コンテンツ・サーバー・オブジェクトに関連する特定の機能を追加します。それは、オブジェクトを作成したISCSServerResponseオブジェクトへのアクセスを可能にし、また、getModifiedProperties ()メソッドを使用してオブジェクトが初期化された以降に変更されたプロパティのコレクションへのアクセスを可能にします。

ICISObjectというクラス名はUCPM 8.0.0 APIで新規のものです。

ISCSObjectオブジェクトには、ネイティブなプロパティ名というコンセプトがあります。具体的には、ISCSObjectで使用可能なプロパティは、Javaのプロパティ名とコンテンツ・サーバーのネイティブ名の異なる2つの名前で使用可能です。たとえば、ISCSContentアイテムのタイトルを取得する次の3つの方法は同等です。

String title = content.getTitle ();
title = content.getProperty ("title").getValue ().getStringValue ();
title = content.getProperty ("dDocTitle").getValue ().getStringValue ();

コンテンツ・サーバーでは、拡張可能なメタデータ・モデルがサポートされています。ISCSObjectオブジェクトは、getProperty ()メソッドを介して公開されるものよりも多くのプロパティを持つことができます。ISCSObjectの実装では、最も一般的なプロパティは公開されていますが、拡張メタデータなどのその他のプロパティはgetProperty ()メソッドを介してのみ使用可能です。また、getProperties ()メソッドは、対応するゲッターまたはセッター・メソッドのないプロパティを含め、オブジェクトのすべてのプロパティをリスト表示します。

for (Iterator it = content.getProperties ().iterator (); it.hasNext (); ) {
  ISCSProperty property = (ISCSProperty)it.next ();
  ISCSPropertyDescriptor descriptor = property.getActiveDescriptor ();
  if (descriptor.isBeanProperty ()) {
    System.out.println ("Property is available via get or set: " +
                         property.getDescriptor().getName ());
  } else {
    System.out.println ("Property is a hidden or extended property: " +
                         property.getDescriptor().getName ());
  }
    System.out.println ("Native property name: " + descriptor.getNativeName ());
}

ISCSObjectから戻されるプロパティはISCSPropertyインタフェースを実装し、このインタフェースはgetActiveDescriptor ()メソッドを追加します。ISCSPropertyDescriptorにより、アイテムの使用可能なプロパティにbeanPropertyおよびnativeNameプロパティが追加されます。

beanPropertyプロパティにより、現在のプロパティ・オブジェクトでゲッターまたはセッター・メソッドが使用可能かどうかが決定されます。このプロパティがfalseの場合、このプロパティ・オブジェクトはgetProperty ()メソッドを介してのみ使用できます。

nativeNameプロパティは、特定のプロパティのコンテンツ・サーバー・プロパティ名を戻します。

Dateオブジェクト

SCS APIのDateフィールドは、JavaのDateオブジェクトとして協定世界時(UTC時間)で処理されます。ISCSObjectの様々なプロパティに渡されるすべての日付は、UTC時間にする必要があります。SCS APIから戻されるすべての日付オブジェクトはUTC時間であり、個々のアプリケーション用に適切なタイムゾーンに変換する必要があります。

Date releaseDate = content.getReleaseDate ();

// convert from UTC time to Pacific Time Zone
  Calendar calendar = Calendar.getInstance ();
  calendar.setTime (releaseDate);
  calendar.setTimeZone (TimeZone.getTimeZone ("America/Los_Angeles"));
// use calendar to display date...

3.2.2 インタフェースICISTransferStream

コンテンツ・サーバーとの送受信ファイル・ストリームが変更されました。CIS APIに対するインタフェースのみというアプローチを維持するため、すべてのストリームはICISTransferStreamインタフェースを介して送信されます。このインタフェースは、実際の物理的なストリーム・オブジェクトおよび付加的なメタデータ(ファイル名、コンテンツ長およびMIMEタイプを含む)を表します。ICISTransferStreamはインタフェースなので、InputStreamを直接拡張できません。このため、このオブジェクトを使用する場合は、まずICISTransferStream.getStream()を呼び出してストリームを取得し、それから適切にストリームを操作する必要があります。

以前のバージョンでInputStreamを戻していたいくつかのコマンドは、現在ではICISTransferStreamオブジェクトを戻します。たとえば、コンテンツ・サーバーからのストリームにアクセスするためにFileAPIでgetFile()を呼び出す場合、コードは次のようになります。

ICISTransferStream transferStream = fileAPI.getFile (context, documentID);
InputStream inputStream = transferStream.getInputStream();

ICISTransferStreamの実装には、コマンド・クライアントとコマンド・サーバー間の送受信のストリーム転送に必要なすべての配管が含まれています。InputStreamオブジェクトは直接シリアライズできないため、いくつかの追加作業を行って、サーバーがアクセスできる場所にストリームが置かれます。そのロジックはすべて、APIのユーザーには隠されています。

ストリーム・インスタンスは、createTransferStreamメソッドを使用してルートのIUCPMAPIインタフェースから取得できます。それは、ストリーム・コンテナの空のインスタンスを戻し、そのアクセサ・メソッドを使用してストリームのプロパティを設定できます。たとえば、次の例では、転送ストリームを作成してローカル・ファイルに振り向けます。

// create the stream implementation
ICISTransferStream transferStream = ucpmAPI.createTransferStream ();

// point it at a file
transferStream.setFile (new File ("mytestdoc.doc"));

ファイル・ハンドルではなく、メモリーにすでにストリームがあり、そのストリーム内のコンテンツをコンテンツ・サーバーにチェックインする場合は、ファイル名、コンテンツ・タイプ、ストリームの長さなど、ストリームの属性をすべて指定する必要があります。

ICISTransferStream transferStream = ucpmAPI.createTransferStream ();
  transferStream.setFileName ("sample.txt");
  transferStream.setInputStream (inputStream);
  transferStream.setContentType ("text/plain");
  transferStream.setContentLength (length);
  checkinAPI.checkinFileStream (context, content, transferStream);

3.2.3 インタフェースISCSServerBinder

CIS 8.0.0 APIでは、新規オブジェクトのISCSServerBinderが提供され、これはコンテンツ・サーバーとのすべての通信に使用されるルート・オブジェクトです。ISCSServerBinderオブジェクトにより、コンテンツ・サーバーとの双方向のメッセージがカプセル化されます。それは、プロパティ、結果セット、ファイル、オプション・リスト、およびコンテンツ・サーバーが必要とするその他の特定のタイプの情報のコレクションです。

コンテンツ・サーバーへのすべてのAPI呼出しで、ISCSServerBinderのインスタンスが作成されます。各API呼出し(たとえば、ISCSSearchAPI.search())では、提供されるISCSObjectパラメータを使用してバインダを移入し、おそらく、その他の特定の情報を追加します。同様に、コンテンツ・サーバーからのストリームではないすべてのレスポンスは、ISCSServerBinderを拡張したISCSServerResponseオブジェクトです。

すべてのISCSObjectsは任意のメタデータのコレクションであるため、ISCSServerBinderはいくつかのオブジェクトのそれぞれに含まれるメタデータのコレクションです。特定のISCSServerBinderには、コンテンツ・サーバー問合せのメタデータ(ISCSSearchQueryを参照)、コンテンツの一部に関連するメタデータ、およびユーザー・データを扱うオブジェクトのリストが含まれている可能性があります。各ISCSObjectにはそのオブジェクトに特有のメタデータが含まれているため、ISCSServerBinderは多くのオブジェクトのメタデータを担当します。

プロパティ

ISCSServerBinderは、コアとなるISCSObjectインタフェースを拡張しているため、getPropertyメソッドおよびsetPropertyメソッドを介して任意のプロパティを取得および設定する機能を備えています。これらの任意のプロパティは、通常、特定のコンテンツ・サーバー用の引数が置かれる場所です。これは、次のサンプル・コードに示すように、setPropertyメソッドを使用して直接追加できます。

// create an empty binder
ISCSServerBinder binder =
  (ISCSServerBinder)getUCPMAPI ().createObject (ISCSServerBinder.class);

// set some properties
  binder.setProperty ("dDocTitle", "test");
  binder.setProperty ("dSecurityGroup", "Public");

また、ISCSObjectインタフェースで使用可能なmergeObject機能を使用してプロパティを設定することもできます。次の例では、別のオブジェクトを作成し、そのオブジェクトにいくつかのプロパティを設定し、マージを使用してそのプロパティをサーバー・バインダに配置します。

// create an empty content item
ISCSContent content = (ISCSContent)getUCPMAPI ().createObject (ISCSContent.class);

// set some properties
content.setTitle ("test");
content.setSecurityGroup ("Public");

// merge into binder; this copies all the properties from content into the binder
binder.mergeObject (content);

前述の2つの例は同一であり、どちらも、ISCSServerBinderオブジェクト内にコンテンツ・アイテムのタイトル(dDocTitle)およびセキュリティ・グループ(dSecurityGroup)を設定するという結果になります。しかし、第2の方法を使用すると、コンテンツ・サーバーのネーミングの詳細を扱う必要がありません。ISCSContentオブジェクトにより、標準のJavaプロパティからコンテンツ・サーバーのメタデータへのマッピングが処理されます。

結果セット

結果セットは、コンテンツ・サーバー問合せから戻される行のコレクションです。これは、getResultSetおよびsetResultSetメソッドを介してISCSServerBinderに公開されます。そして、SCS APIの結果セットは、結果セットの各1行を表すオブジェクト型が含まれる、一様の項目からなるリストとして公開されます。コンテンツ・サーバー問合せから戻される多くの項目は、結果セットとして戻ります。すべての結果セットはISCSObjectオブジェクトのリストであるため、結果セットのアイテムは別の呼出しに使用できます。例として、検索を実行し、その中の最初のアイテムを更新する次のコードを確認してください。

// create an simple query
ISCSSearchQuery query =
  (ISCSSearchQuery)getUCPMAPI ().createObject (ISCSSearchQuery.class):
  query.setQueryText ("dDocName <substring> 'test' ");

// execute a search
ISCSSearchResponse response =
  getUCPMAPI ().getActiveAPI ().getSearchAPI ().search (context, query);

// search results come back as a result set of ISCSSearchResult items
ISCSSearchResult result = (ISCSSearchResult)response.getResults ().get (0);

// change the title and check it in
result.setTitle ("new title");
getUCPMAPI ().getActiveAPI ().getDocumentUpdateAPI ().
  updateInfo (context, result);

ファイル・オブジェクト

ISCSServerBinderにより、addFileメソッドを使用してファイルをコンテンツ・サーバーに送信できます。このメソッドはICISTransferStreamを受け取ります。作成されたファイルは、リクエスト中にバインダとともにコンテンツ・サーバーに送信されます。ファイルの追加は、プロパティの追加に似ています。

// create an empty stream
ICISTransferStream stream = getUCPMAPI ().createTransferStream ();

// point the stream at a local file
stream.setFile (new File ("testfile.txt"));

// add the stream to the binder
serverBinder.addStream ("myFile", stream);

前述のバインダがコンテンツ・サーバーに送信されるとき、ストリームがバインダとともに転送されます。コンテンツ・サーバー内では、このストリームをバインダにストリームを追加するときに指定した「myFile」というキーで使用できるようになります。

オブジェクトのコピーおよびキャスト

SCS API内の各ISCSObjectには、Oracle Content Serverと互換性のある低レベルのフォーマットでデータを保持するオブジェクトがあります。データ・オブジェクトと呼ばれるこのオブジェクトは、すべてのISCSObjectの実装で使用されます。これは、任意のISCSObjectを別の型のISCSObjectに変えられることを意味します。この機能を公開する2つのメソッドとして、ISCSObjectインタフェースで使用可能なcastObjectおよびcopyObjectメソッドがあります。

両方のメソッドは、単一のパラメータとして、作成するオブジェクトの型を表すクラス型を受け取ります。castObjectの呼出しは、それが呼び出されたオブジェクトと同じバッキング・データを指し示す新規オブジェクトの作成という結果になります。これは、元のオブジェクトへの変更がcastObjectの呼出しから戻されるオブジェクトにも同様に反映されることを意味します。copyObjectの呼出しは、バッキング・データのコピーが実行され、新規に作成されたオブジェクトは元のオブジェクトから独立して動作できる、という結果になります。

たとえば、「MY_DOC_INFO」と呼ばれるカスタム・コンテンツ・サーバー・サービスがあり、標準の「DOC_INFO」と似ていますが、それに加えていくつかのビジネス・ロジックを処理するものとします。しかし、「MY_DOC_INFO」の呼出しから戻されるバインダは、「DOC_INFO」の呼出しから戻されるものとほとんど同じです。SCS APIにはこの「MY_DOC_INFO」サービスに対する明示的なAPI呼出しがないため、汎用のexecuteIDCServiceの呼出しを使用する必要があります。しかし、castObjectメソッドを使用して、戻り値の型をよりユーザー・フレンドリなものに変更できます。

// build our custom call
ISCSServerBinder binder =
  (ISCSServerBinder)getUCPMAPI ().createObject (ISCSServerBinder.class);
  binder.setService ("MY_DOC_INFO");

// create a document ID and add it to the binder
ISCSDocumentID documentID =
  (ISCSDocumentID)getUCPMAPI ().createObject (ISCSDocumentID.class);
  documentID.setDocumentID ("12345");
  binder.mergeObject (documentID);

// execute the call
ISCSServerResponse response =
  (ISCSServerResponse)getUCPMAPI ().getAdministrativeAPI ().
    executeIDCService (context, binder);

// use the cast to change it to a ISCSDocumentInformationResponse
ISCSDocumentInformationResponse infoResponse =
  (ISCSDocumentInformationResponse)response.
    castObject (ISCSDocumentInformationResponse.class);

// use the info response as usual
System.out.println ("Title: " + infoResponse.getDocNode ().getTitle ());

前述したように、castObject呼出しは、同じバッキング・データを共有することにより2つのオブジェクトをリンクします。前述の例では、responseオブジェクトに加えた変更は、同様にinfoResponseオブジェクトにも反映されます。

// set a property on the response
response.setProperty ("customProperty", "customValue");

// value is then available in the infoResponse object
String value = infoResponse.getPropertyAsString ("customProperty");

copyObjectがかわりに呼び出されていた場合は、responseとinfoResponseは互いに独立です。castObject呼出しでは新規のバッキング・データ・オブジェクトが作成されないため、castObjectはcopyObjectよりも小さなメモリー領域が作成されます。

3.2.4 インタフェースISCSServerResponse

SCS API呼出しの結果は、通常、ISCSServerResponseオブジェクトです。ISCSServerReponseは、すべてのレスポンス・オブジェクトのベース・インタフェースです。これは、最後のリクエストに対するコンテンツ・サーバーからのレスポンスをカプセル化します。ほとんどのメソッドは、レスポンスに固有のプロパティを提供する、このインタフェース固有の実装を持っています。特定のレスポンス・オブジェクトおよびそれぞれに使用可能なプロパティの詳細は、Javadocを参照してください。

現在のリリースでは、以前はInputStreamへの参照を戻していたいくつかの呼出しは、現在はそのかわりにICISTransferStreamオブジェクトを戻します。新しい転送ストリーム・インタフェースの使用方法は、インタフェースISCSRequestModifierを参照してください。

3.2.5 インタフェースISCSRequestModifier

SCS APIを使用したコンテンツ・サーバーへのすべてのリクエストでは、その結果としてISCSServerBinderオブジェクトが作成されます。特定の状況では、特定のコンテンツ・サーバーの要件に一致するように、指定されたAPI呼出しのバインダ・コンテンツの変更が必要になります。ISCSRequestModifierインタフェースは、まさにこの目的のために設計されており、カスタムの変更を加えてコンテンツ・サーバーへの呼出しを拡張します。

SCS APIのすべてのAPIには対応するメソッドがあり、そのメソッドは最初のパラメータとしてISCSRequestModifierオブジェクトを受け取ります。ISCSSearchAPIのAPIを次に示します。

/**
   * Command the implements searching against the content server.
  * @param SCSContext the context object representing the current user
  * @param searchQuery the content server query object
  */

public com.stellent.cis.client.api.scs.search.
  ISCSSearchResponse search (com.stellent.cis.client.api.scs.context.
    ISCSContext SCSContext,
    com.stellent.cis.client.api.scs.search.ISCSSearchQuery searchQuery)
  throws com.stellent.cis.client.command.CommandException;

/**
  * Command the implements searching against the content server.
  * @param requestModifier modify the request
  * @param SCSContext the context object representing the current user
  * @param searchQuery the content server query object
  * @see com.stellent.cis.server.api.scs.commands.search.SearchCommand
  */

public com.stellent.cis.client.api.scs.search.
  ISCSSearchResponse search (com.stellent.cis.client.api.scs.
    ISCSRequestModifier requestModifier, com.stellent.cis.client.api.scs.context.
    ISCSContext SCSContext, com.stellent.cis.client.api.scs.search.I
    SCSSearchQuery searchQuery)
    throws com.stellent.cis.client.command.CommandException;

第2のAPIは、追加のISCSRequestModifier引数とともに、第1のAPIのパラメータをすべて受け取ります。標準の検索API、およびそのすべてのロジックは、カスタム・ロジックを追加して使用できます。たとえば、カスタム・コンポーネントがコンテンツ・サーバーにインストールされており、検索問合せ中、「myCustomProperty」プロパティが設定されていることを検出したら、何か追加の処理を行うものとします。CISでこれを行うには、次のように、バインダを変更するISCSRequestModifierを使用できます。

// build a search query
ISCSSearchQuery query =
  (ISCSSearchQuery)getUCPMAPI ().createObject (ISCSSearchQuery.class);
  query.setQueryText ("dDocName <substring> `test`");

// build a request modifier
ISCSRequestModifier modifier =
  (ISCSRequestModifier)getUCPMAPI ().createObject (ISCSRequestModifier.class);

// access the binder off the modifier and add in our custom data
modifer.getServerBinder().setProperty ("myCustomProperty", "customValue");

// execute the search as normal
getUCPMAPI ().getActiveAPI ().getSearchAPI ().search (modifier, context, query);

これで、検索呼出しの間、変更されたバインダが使用されます。カスタム・プロパティの値は、標準の検索呼出しと一緒に送信されます。この同じメソッドを、任意のプロパティの設定、ファイルの追加、結果セットの設定に使用でき、またコンテンツ・サーバーで実行されるサービス・コールのオーバーライドにさえも使用できます。

3.3 SCS APIサーブレットの理解

J2EE/Web環境で運用され、サーバー・モードで実行されている場合、SCS APIは、いくつかのサーブレットがシステムで利用可能であることを必要とします。

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

• 「サーブレットの説明」

• 「SCSサーブレットのパラメータ」

• 「サーブレットのセキュリティ」

• 「サーブレットとAPIの対話」

3.3.1 サーブレットの説明

この表は、特定のWebアプリケーションのweb.xmlファイルで必要となる、サーブレットの名前および適切な構成情報をリストしています。

完全修飾名	マッピング	説明
SCSFileDownloadServlet com.stellent.web.servlets.SCSFileDownloadServlet	/getfile	クライアントはコンテンツ・サーバーからファイルを取得できます。
SCSCommandClientServlet com.stellent.web.servlets.SCSCommandClientServlet	/scscommandclient	CISクライアント用にCISサーバーの設定情報を公開します。
SCSFileTransferServlet com.stellent.web.servlets.SCSFileTransferServlet	/scsfiletransfer	UCPM APIは、CISクライアントにファイルを転送できます。
SCSInitialize com.stellent.web.servlets.SCSInitialize	N/A	CISアプリケーション・インスタンスを初期化します。LoadOnStartupサーブレットとして設定する必要があります。
SCSDynamicConverterServlet com.stellent.web.servlets.SCSDynamicConverterServlet	/getdynamicconversion/*	動的変換を実行し、結果をクライアントにストリーミングします。
SCSDynamicURLServlet com.stellent.web.servlets.SCSDynamicURLServlet	/scsdynamic/*	コンテンツ・サーバーから動的なファイルを取得します。動的に変換されたドキュメントのURLを書き換えるときに使用されます。

3.3.2 SCSサーブレットのパラメータ

この項では、次のサーブレットのパラメータについて説明します。

• 「SCSFileDownloadServlet」

• 「SCSDynamicConverterServlet」

• 「SCSDynamicURLServlet」

この項では、使用可能なセキュリティ・パラメータは何も指定していません(セキュリティ・パラメータは「サーブレットのセキュリティ」で詳しく説明しています)。サーブレットのセキュリティの項で示されているコンテンツ・サーバーに対して行うすべての呼出しは、IDを使用しています。

3.3.2.1 SCSFileDownloadServlet

プロパティ	必須	説明
adapterName	true	ドキュメントの問合せを行うアダプタ名。
dDocName	該当なし	取得するドキュメントのコンテンツID。
rendition	false	コンテンツのレンディション。dDocNameを指定するときのみ有効。
revisionSelection	false	コンテンツを選択するときに使用するrevisionSelection。dDocNameを指定するときのみ有効。
forceStream	false	trueの場合、アダプタの最適化されたファイル転送の設定には関係なく、コンテンツはGET_FILEの呼出しを介してコンテンツ・サーバーからストリーミングされます。デフォルトはfalse。

3.3.2.2 SCSDynamicConverterServlet

プロパティ	必須	説明
adapterName	true	ドキュメントの問合せを行うアダプタ名。
contentID	contentIDまたはdocumentIDのいずれかが必須。	取得するドキュメントのコンテンツID(dDocName)。
documentID	該当なし	取得するドキュメントのドキュメントID(dID)。
rendition	false	取得するドキュメントのレンディション。contentIDが指定されている場合のみ有効。
revisionSelectionMethod	false	ドキュメントの選択に使用するrevisionSelectionMethod。contentIDが指定されている場合のみ有効。
viewFormat	false	変換の表示形式(つまり、NativeまたはWebViewable)。
useAlternate	false	trueの場合、変換に代替ファイルを使用します。デフォルトはfalse。

3.3.2.3 SCSDynamicURLServlet

プロパティ	必須	説明
adapterName	true	ドキュメントを問い合せるアダプタ名。パラメータとして渡されるのではなく、次のようにURLの最後のセグメントとして指定されます。 /cis-server/scsdynamic/ <adaptername>?...
fileUrl	true	取得するコンテンツ・サーバーのファイルへの相対パス。

3.3.3 サーブレットのセキュリティ

SISFileDownloadServletおよびSCSInitializeServletを除くすべてのサーブレットは、UCPM APIの呼出しを行うため、ユーザー・コンテキストを持つ必要があります。デフォルトでは、HttpServletRequest.getUserPrincipal()メソッドを使用してユーザーIDを決定し、ISCSContextオブジェクトを介してUCPM API呼出しにそのIDを渡します。この動作は、サーブレットに次のような初期化パラメータをいくつか指定することでオーバーライドできます。

• principalLookupAllowed: TRUEに設定すると、サーブレットは構成されたスコープ内でユーザーIDを検索します。デフォルトのスコープはsessionです。

• principalLookupScope: 検索のスコープ。principalLookupAllowedがTRUEの場合に有効です。定義されたスコープは、getAttribute ()メソッドを呼び出して現在のユーザーの名前を検出するために使用されます。request、sessionまたはapplicationのいずれかを指定できます。デフォルトはsessionです。

• principalLookupName: ユーザーIDを保持するスコープ・パラメータの名前。principalLookupAllowedがTRUEの場合に有効です。デフォルトはprincipalです。

• getUserPrincipalEnabled: FALSEに設定すると、ユーザーIDを決定するためのHttpServletRequest.getUserPrincipal ()メソッドの呼出しは実行されません。デフォルトはTRUEです。

• principal: ユーザーIDを決定できない場合のデフォルトのユーザーID。デフォルトは、guestです。

現在のユーザーIDを決定するため、サーブレットは最初にprincipalLookupAllowedフラグのステータスをチェックします。TRUEの場合、principalLookupScopeパラメータの設定によりスコープを決定し、ユーザーの名前を検索します。現在のスコープで、パラメータとしてprincipalLookupNameを使用してgetAttribute ()メソッドが呼び出されます。principalを検出できない場合は、次にgetUserPrincipalEnabledフラグのステータスをチェックします。このフラグがTRUEの場合、HttpServletRequest.getUserPrincipal ()メソッドを呼び出します。それがnullを返す場合、デフォルトのprincipalを使用してリクエストを実行します。

サーブレットに何も変更を加えなくても、デフォルトの動作により、HttpServletRequest.getUserPrincipal ()メソッドがチェックされ、それから必要に応じてデフォルトが使用されます。もう一方のrequest、sessionおよびapplicationのチェックは、web.xmlファイル内のサーブレット定義のinit-paramで指定されている場合にのみ実行されます。

3.3.4 サーブレットとAPIの対話

ISCSFileAPI.getDynamicConversion()メソッドは、指定されたドキュメントの動的な変換を行います(Dynamic Converterコンポーネントはコンテンツ・サーバーにインストールされているものと想定します)。getDynamicConversion()の呼出しでも、CISサーブレットへの戻り先を指すように(直接コンテンツ・サーバーを指すのではなく)戻されるURLがリライトされ、Web/Portal環境でレンダリングされたときに正しく表示されます。

リライトされたURLはSCSDynamicURLServletを指し示し、そして、それはSCS APIを介してコンテンツ・サーバーからアイテムを取得し、クライアントにストリーミングを戻します。サーブレットは、「サーブレットのセキュリティ」で説明する方法でコンテキストのユーザーIDを決定します。

サーブレットがユーザーIDを決定するため、getDynamicConversion()の呼出しを実行したユーザーは、レンダリングされたHTMLのリンクをクリックしたユーザーと同じユーザーIDを持っていない可能性があります。HttpServletRequest.getUserPrincipal()のユーザーIDがISCSContextのユーザーIDと一致しない場合がこのケースになります。

その場合は、「サーブレットのセキュリティ」で説明する方法を使用してSCSDynamicURLServletをカスタマイズし、セッションでユーザー・パラメータを探すように指示できます。または、SCSDynamicURLServletでgetDynamicConversion()を呼び出し、ユーザーがURLにパラメータを追加することを可能にするオプションでISCSConvertedUrlInfoオブジェクトを渡すことができ、このパラメータをアプリケーションがコンテキストを識別するために使用できます。

たとえば、アプリケーションでstellentPrincipalという名前のセッション属性に現在のユーザーIDを保存している場合、SCSDynamicURLServletのweb.xmlを次のように変更します(必要に応じて、その他のサーブレットについても)。

<servlet>
  <servlet-name>scsdynamic</servlet-name>
  <servlet-class>com.stellent.web.servlets.SCSDynamicURLServlet</servlet-class>
  <init-param>
    <param-name>sessionPrincipalAllowed</param-name>
    <param-value>true</param-value>
  </init-param>
  <init-param>
    <param-name>sessionPrincipalName</param-name>
    <param-value>stellentPrincipal</param-value>
  </init-param>
</servlet>

3.4 SCS APIの使用

SCS検索、SCSファイル、SCSドキュメントおよびSCSワークフローの各APIについて説明し、サンプル・コードを提供します。これらのAPIにより、検索、コンテンツのチェックインとチェックアウト、およびワークフローの承認と拒否などのタスクが実行できます。

CISApplicationインスタンス(m_cisApplicationという名前)は初期化済で、コンテキスト・オブジェクト(m_contextという名前)は作成済であるものとします。追加のサンプルは、SDK/Samples/CodeSamples/ディレクトリにあります。

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

• 「SCS検索API」

• 「SCSファイルAPI」

• 「SCSドキュメントAPI」

• 「SCSワークフローAPI」

3.4.1 SCS検索API

ISCSSearchAPIは、検索コマンドのコマンドAPI実装です。ISCSSearchAPIを使用し、次のコードを使用してコンテンツ・サーバーを検索できます。

// get a handle to the SCS Search API
ISCSSearchAPI searchAPI =
  m_cisApplication.getUCPMAPI ().getActiveAPI ().getSearchAPI ();
ISCSSearchResponse searchResponse =
  searchAPI.search (m_context, "dDocTitle <substring> 'HR'",  25);

// iterate all results
for (Iterator it = searchResponse.getResults ().iterator (); it.hasNext (); ) {
  ISCSSearchResult searchResult = (ISCSSearchResult)it.next ();

// print out the title and author
System.out.println ("Found result: " + searchResult.getTitle () + " by " +
  searchResult.getAuthor ());
}

3.4.2 SCSファイルAPI

ISCSFileAPIは、コンテンツ・サーバーからのファイルの取得、およびファイルの動的変換を処理します。コンテンツのIDを渡すことで、簡単にファイルを取得できます。または、ファイルのWebおよびAlternateバージョンへの参照を取得するオプションのISCSFileInfoオブジェクトを使用して、異なるバージョンのファイルを取得できます。

// get the SCS File API
ISCSFileAPI fileAPI =
  m_cisApplication.getUCPMAPI ().getActiveAPI ().getFileAPI ();

ICISTransferStream transferStream =
  fileAPI.getFile (m_context, content.getDocumentID ());

InputStream stream = transferStream.getInputStream();
// do something with the stream...

ISCSFileInfoオブジェクトを取得する_createFileInfo()メソッドも使用できます。このオブジェクトにはいくつかのプロパティがあり、それにより、取得するファイルのレンディションをさらに選択できます。次のサンプルでは、fileInfoオブジェクトを使用してファイルのWeb表示可能レンディションを取得しています。同様の処理を使用して、Alternateレンディションを取得できます。

// get the web viewable version of the file
ISCSFileInfo fileInfo =
  (ISCSFileInfo) m_cisApplication.getUCPMAPI ().createObject(ISCSFileInfo.class);
  fileInfo.setRendition ("Web");

// get the file
ICISTransferStream transferStream =
  fileAPI.getFile (m_context, content.getDocumentID (), fileInfo);
  InputStream stream = transferStream.getInputStream();
// do something with the stream...

SCSファイルAPIは、コンテンツ・サーバーのDynamic Converterコンポーネントを介してコンテンツのHTMLレンディションを生成するために使用できます(Dynamic Converterコンポーネントがインストールされている必要があります)。

getFile ()の呼出しも同様で、IDとともにgetDynamicConversion ()を呼び出してHTML変換を取得するか、またはISCSFileInfoおよびISCSConvertedFileInfoオブジェクトを使用して、処理する変換ルールと適用する明示的なテンプレートの情報をAPIに渡すことができます。

ICISTransferStream transferStream =
  fileAPI.getDynamicConversion (m_context, content.getDocumentID ());
// process the stream...

次のサンプルは前述の機能を1つのメソッドに組み合せたもので、カスタム変換テンプレートを使用して、指定されたコンテンツ・オブジェクトの代替レンディションを動的に変換します。

// create the converted file bean and set our properties
ISCSConvertedFileInfo convertedInfo = fileAPI.__createConvertedFileInfo ();
convertedInfo.setConversionLayout ("custom_layout");
convertedInfo.setRendition ("Alternate");

// execute the dynamic conversion
ICISTransferStream transferStream =
  fileAPI.getDynamicConversion (m_context, content.getDocumentID (),
    convertedInfo);
// do something with the stream...

3.4.3 SCSドキュメントAPI

SCSドキュメントAPIは、コンテンツのチェックインとチェックアウト、コンテンツ情報、コンテンツの削除など、コンテンツ・サーバー内のアクティブ・コンテンツを処理します。

この項では、次のAPIについて説明します。

• 「ISCSDocumentCheckinAPI」

• 「ISCSDocumentCheckoutAPI」

3.4.3.1 ISCSDocumentCheckinAPI

このAPIは、すべてのコンテンツのコンテンツ・サーバーへのチェックインを処理します。ディスクからのファイルのシンプルなチェックインでは、次のコードが使用できます。

// get the checkin api
ISCSDocumentCheckinAPI checkinAPI =
  m_cisApplication.getUCPMAPI ().getActiveAPI ().getDocumentCheckinAPI ();

// create an empty content object with the specified content ID
ISCSContent content =
(ISCSContent) m_cisApplication.getUCPMAPI ().createObject(ISCSContent.class);

ISCSContentID contentID =
(ISCSContentID) m_cisApplication.getUCPMAPI ().createObject(ISCSContentID.class);
  contentID.setContentID("my_test_file");
  content.setContentID(contentID);
  content.setAuthor (m_context.getUser ());
  content.setTitle ("Custom Title");
  content.setSecurityGroup ("Public");
  content.setType ("ADACCT");

// get the file stream
File myFile = new File ("c:/test/testcheckin.txt");
ICISTransferStream transferStream =
  m_cisApplication.getUCPMAPI ().createTransferStream();
  transferStream.setFile(myFile);

// execute the checkin
checkinAPI.checkinFileStream (m_context, content, transferStream);

コンテンツ・サーバーの多くのデプロイメントでは、新しいコンテンツのために設定を必要とする必須の拡張プロパティがあります。これらのプロパティは、すべてのICISObjectオブジェクトで使用可能なsetProperty()呼出しを使用してコンテンツ・オブジェクトに設定できます。たとえば、いくつかのカスタム・プロパティを次のように設定できます。

// set an extended property
  content.setProperty ("xCustomProperty", "Custom Value");

セッター・メソッドを呼び出すのではなく、すべてのプロパティを設定するsetProperty()メソッドを使用できます。JavaBeanの名前(たとえば、title)またはJavaBeanプロパティと対応するネイティブのコンテンツ・サーバーのプロパティ名(つまり、dDocTitle)のいずれかを使用できます。次のサンプルでは、すべて同等の3つの方法でtitleプロパティを設定します。

// set via a standard property setter
  content.setTitle ("My Title");

// set a standard property using the JavaBean property name
  content.setProperty ("title", "My Title");

// set a property using the native content server property name
  content.setProperty ("dDocTitle", "My Title");

3.4.3.2 ISCSDocumentCheckoutAPI

このAPIは、すべてのコンテンツのコンテンツ・サーバーからのチェックアウトを処理します。コンテンツ・アイテムは、そのIDによって識別されます。

// get the checkout api
ISCSDocumentCheckoutAPI checkoutAPI =
  m_cisApplication.getUCPMAPI ().getActiveAPI ().getDocumentCheckoutAPI ();

// checkout the file
checkoutAPI.checkout (m_context, content.getDocumentID ());

3.4.4 SCSワークフローAPI

ISCSWorkflowAPIは、ユーザーのワークフロー・キューを表示し、コンテンツ・サーバーのワークフロー・エンジンと対話しながら、承認および拒否などのワークフロー・コマンドを処理します。次のサンプル・コードは、ワークフロー・エンジンにシステムで現在アクティブなワークフローを問い合せる例を示します。

// get the workflow API
ISCSWorkflowAPI workflowAPI =
  m_cisApplication.getUCPMAPI ().getActiveAPI().getWorkflowAPI ();
ISCSWorkflowResponse workflowResponse =
  workflowAPI.getActiveWorkflows (m_context);

// iterate through the workflows
for (Iterator it = workflowResponse.getActiveWorkflows().iterator();
  it.hasNext (); ) {
    ISCSWorkflow workflow = (ISCSWorkflow)it.next ();
    String name = workflow.getName ();
    String status = workflow.getWorkflowStatus ();
    System.out.println ("SCS workflow: " + name + "; status = " + status);
}

ワークフローとの最も一般的な対話は、ワークフローを拒否または承認し、ワークフローの次のステップに進めることです。次のコードは、ユーザーの個人的なワークフロー・キューを取得し、保留中のすべてのワークフローを承認する方法を示しています。

// get the workflow API
ISCSWorkflowAPI workflowAPI =
  m_cisApplication.getUCPMAPI ().getActiveAPI().getWorkflowAPI ();

// get the workflow queue
ISCSWorkflowQueueResponse queueResponse =
  workflowAPI.getWorkflowQueueForUser (m_context);
for (Iterator it = queueResponse.getWorkflowInQueue().iterator(); it.hasNext();) {
ISCSWorkflowQueueItem queueItem =
  (ISCSWorkflowQueueItem)it.next();

// approve the workflow
workflowAPI.approveWorkflow(m_context, queueItem.getDocumentID ());
}