コレクションの使用

コレクションを使用すると、1つ以上の非スカラー値を一時的に取得できます。コレクションを使用して、現在セッション・ステートにある行および列を格納します。これによって、あるユーザーの特定のセッション中にそれらの行および列に対してアクセス、操作または処理を行うことができます。コレクションは、バケツのようなものと考えることができます。その中に情報の行を一時的に格納し、その情報を指定できます。

次に、コレクションを使用する場合の例を示します。

データ入力ウィザードを作成しており、そのウィザードで、まず論理トランザクション中に複数行の情報を収集する必要がある場合。物理トランザクションと論理トランザクションの両方の完了時、ウィザードの最終ステップを実行する前に、コレクションを使用して、複数行の情報のコンテンツを一時的に格納できます。
アプリケーションに、ユーザーが1つのページで複数の詳細行を更新する更新ページが含まれている場合。ユーザーは、複数の更新を行い、それらの更新をコレクションに適用した後、最終プロセスをコールしてそれらの変更をデータベースに適用できます。
任意の数の属性を収集するウィザードを構築している場合。コレクションに一時的に格納された情報が取得され、データベースに適用されるタスクをウィザードの最後にユーザーが実行するようにします。

この項に含まれる内容は次のとおりです。

APEX_COLLECTION APIについて
コレクションの作成
コレクションの切捨て
コレクションへのアクセス
コレクションの削除
コレクションへのメンバーの追加
コレクション・メンバーの更新
コレクション・メンバーの削除
コレクション・ステータスの判別
コレクションのマージ
コレクションの管理
コレクションのセッション・ステートのクリア

APEX_COLLECTION APIについて

各コレクションには、データ要素(メンバー)の名前付きリストが含まれます。このリストには、最大50個の文字属性(VARCHAR2(4000))および1個の大文字属性(CLOB)を含めることができます。コレクション情報は、PL/SQL API APEX_COLLECTIONを使用して挿入、更新および削除します。

コレクションの名前の指定について

コレクションを作成する場合、255文字以下の名前を付ける必要があります。コレクション名の大/小文字は区別されず、すべて大文字に変換されます。

コレクションに名前を付けた後、コレクション内の値にアクセスするには、APEX_COLLECTIONSビューに対してSQL問合せを実行します。

関連項目:

「コレクションへのアクセス」

コレクションの作成

各コレクションには、データ要素(メンバー)の名前付きリストが含まれます。このリストには、最大50個の文字属性(VARCHAR2(4000))および1個の大文字属性(CLOB)を含めることができます。次のメソッドを使用してコレクションを作成します。

CREATE_COLLECTION
CREATE_OR_TRUNCATE_COLLECTION
CREATE_COLLECTION_FROM_QUERY
CREATE_COLLECTION_FROM_QUERY_B

CREATE_COLLECTIONメソッドでは、指定したコレクションが存在する場合は例外が発生します。次に例を示します。

APEX_COLLECTION.CREATE_COLLECTION(
    p_collection_name => collection name );

CREATE_OR_TRUNCATE_COLLECTIONメソッドでは、指定したコレクションが存在しない場合に、コレクションが作成されます。名前付きコレクションが存在すると、このメソッドによって切り捨てられます。切り捨てられたコレクションは空になりますが、コレクション自体はそのまま残ります。次に例を示します。

APEX_COLLECTION.CREATE_OR_TRUNCATE_COLLECTION(
    p_collection_name => collection name);

CREATE_COLLECTION_FROM_QUERYメソッドでは、コレクションが作成され、指定した問合せの結果がそのコレクションに移入されます。次に例を示します。

APEX_COLLECTION.CREATE_COLLECTION_FROM_QUERY(
    p_collection_name => collection name,
    p_query           => your query ,
    p_generate_md5    => 'YES' or 'NO' );

また、CREATE_COLLECTION_FROM_QUERY_Bメソッドでは、コレクションが作成され、指定した問合せの結果がそのコレクションに移入されます。次に例を示します。

APEX_COLLECTION.CREATE_COLLECTION_FROM_QUERY_B(
    p_collection_name => collection name,
    p_query           => your query );

CREATE_COLLECTION_FROM_QUERY_Bメソッドでは、バルクSQL操作を実行することにより、CREATE_COLLECTION_FROM_QUERYメソッドよりも非常に速いパフォーマンスが提供されますが、次の制限があります。

問合せの選択リスト内の列値は、2,000バイトを超えることはできません。列値が2,000バイトを超える行がある場合は、実行中にエラーが発生します。
コレクション内のいずれのメンバーに対してもMD5チェックサムは計算されません。

パラメータp_generate_md5

p_generate_md5フラグを使用して、コレクション・メンバーのデータのメッセージ・ダイジェストを計算する必要があるかどうかを指定します。デフォルトでは、このフラグはNOに設定されています。このパラメータを使用して、コレクション・メンバーのMD5をチェックします(つまり、MD5を他のメンバーと比較して、メンバーが変更されたかどうかを確認します)。

関連項目:

GET_MEMBER_MD5ファンクションの使用方法については、「コレクション・ステータスの判別」を参照してください。

コレクションの切捨て

コレクションを切り捨てる場合、指定したコレクションからすべてのメンバーを削除しますが、指定したコレクションはそのまま残ります。次に例を示します。

APEX_COLLECTION.TRUNCATE_COLLECTION(
    p_collection_name => collection name );

コレクションへのアクセス

データベース・ビューAPEX_COLLECTIONSを問い合せると、コレクションのメンバーにアクセスできます。APEX_COLLECTIONSビューには、次の定義が含まれます。

COLLECTION_NAME   NOT NULL VARCHAR2(255)
SEQ_ID            NOT NULL NUMBER 
C001                       VARCHAR2(4000)
C002                       VARCHAR2(4000)
C003                       VARCHAR2(4000)   
C004                       VARCHAR2(4000)   
C005                       VARCHAR2(4000)  
...
C050                       VARCHAR2(4000)
CLOB001                    CLOB   
MD5_ORIGINAL               VARCHAR2(4000)

APEX_COLLECTIONSビューは、アプリケーションで、アプリケーション内の他の表またはビューと同様に使用します。次に例を示します。

SELECT c001, c002, c003
   FROM APEX_collections
 WHERE collection_name = 'FIREARMS'

コレクションの削除

コレクションを削除する場合は、コレクションおよびそのすべてのメンバーを削除します。次に例を示します。

APEX_COLLECTION.DELETE_COLLECTION (
    p_collection_name => collection name );

コレクションを削除しない場合は、セッションがパージされると最終的にコレクションが削除されることに注意してください。次に例を示します。

現在のアプリケーションに関するすべてのコレクションの削除

現在のアプリケーションに定義されたすべてのコレクションを削除するには、DELETE_ALL_COLLECTIONSメソッドを使用します。次に例を示します。

APEX_COLLECTION.DELETE_ALL_COLLECTIONS;

現在のセッションにおけるすべてのコレクションの削除

現在のセッションに定義されたすべてのコレクションを削除するには、DELETE_ALL_COLLECTIONS_SESSIONメソッドを使用します。次に例を示します。

APEX_COLLECTION.DELETE_ALL_COLLECTIONS_SESSION;

コレクションへのメンバーの追加

コレクションに追加したデータ要素(メンバー)には、一意の順序番号が割り当てられます。メンバーをコレクションに追加すると、最も新しいメンバーが一番大きい番号を持つように、前のメンバーより1大きい番号が新しいメンバーに割り当てられます。

コレクションに新しいメンバーを追加するには、ADD_MEMBERファンクションを使用します。このファンクションをコールすると、新しく追加したメンバーの順序番号が戻されます。次の例では、ADD_MEMBERファンクションを使用する方法を示します。

APEX_COLLECTION.ADD_MEMBER(
    p_collection_name => collection name,
    p_c001          => [member attribute 1],
    p_c002          => [member attribute 2],
    p_c003          => [member attribute 3],
    p_c004          => [member attribute 4],
    p_c005          => [member attribute 5],
    p_c006          => [member attribute 6],
    p_c007          => [member attribute 7],
    ...
    p_c050          => [member attribute 50]);
    p_clob001       => [CLOB member attribute 1],
    p_generate_md5  => 'YES' or 'NO');

ADD_MEMBERSメソッドを使用して、新しいメンバー(メンバーの配列)をコレクションに追加することもできます。次に例を示します。

APEX_COLLECTION.ADD_MEMBERS(
    p_collection_name => collection name,
    p_c001          => member attribute array 1,
    p_c002          => member attribute array 2,
    p_c003          => member attribute array 3,
    p_c004          => member attribute array 4,
    p_c005          => member attribute array 5,
    p_c006          => member attribute array 6,
    p_c007          => member attribute array 7,
    ...
    p_c050          => member attribute array 50);
    p_generate_md5  => 'YES' or 'NO');

指定したコレクションが、現在のユーザーの指定した名前で同じセッションに存在しない場合、このメソッドによりエラーが発生します。また、4,000文字を超える属性はすべて4,000文字に切り捨てられます。追加されるメンバーの数は、1つ目の配列の要素数に基づきます。

パラメータp_generate_md5およびp_clob001

4,000文字を超えるコレクション・メンバー属性には、p_clob001を使用します。

関連項目:

ファンクションGET_MEMBER_MD5の使用方法については、「コレクション・ステータスの判別」を参照してください。

コレクション・メンバーの更新

コレクション・メンバーを更新するには、UPDATE_MEMBERプロシージャをコールして、更新するコレクション・メンバーを順序番号を使用して参照します。次に例を示します。

APEX_COLLECTION.UPDATE_MEMBER (
    p_collection_name => collection name,
    p_seq             => member sequence number,
    p_c001            => member attribute 1,
    p_c002            => member attribute 2,
    p_c003            => member attribute 3,
    p_c004            => member attribute 4,
    p_c005            => member attribute 5,
    p_c006            => member attribute 6,
    p_c007            => member attribute 7,
    ...
    p_c050            => member attribute 50),
    p_clob001         => [CLOB member attribute 1];

UPDATE_MEMBERプロシージャでは、個々のメンバー属性ではなく、コレクション・メンバー全体が置換されます。指定したコレクションが存在しない場合、このプロシージャによりエラーが発生します。

4,000文字を超えるコレクション・メンバー属性には、p_clob001パラメータを使用します。

コレクション・メンバーの単一の属性を更新するには、UPDATE_MEMBER_ATTRIBUTEプロシージャを使用します。次に例を示します。

APEX_COLLECTION.UPDATE_MEMBER_ATTRIBUTE(
    p_collection_name       => collection_name,
    p_seq                   => member sequence number,
    p_attr_number           => member attribute number,
    p_attr_value            => member attribute value )

APEX_COLLECTION.UPDATE_MEMBER_ATTRIBUTE(
    p_collection_name        => collection_name,
    p_seq                    => member sequence number,
    p_clob_number            => CLOB member attribute number,
    p_clob_value             => CLOB member attribute value );

指定したコレクションが存在しない場合、UPDATE_MEMBER_ATTRIBUTEプロシージャをコールすると、エラーが発生します。

p_clob_numberパラメータの有効値は1のみであることに注意してください。

コレクション・メンバーの削除

コレクション・メンバーを削除するには、DELETE_MEMBERプロシージャをコールして、削除するコレクション・メンバーを順序番号を使用して参照します。次に例を示します。

APEX_COLLECTION.DELETE_MEMBER(
    p_collection_name => collection name,
    p_seq             => member sequence number);

このプロシージャでは、順序番号の欠落は指定したコレクションにそのまま残ることに注意してください。また、指定したコレクションが存在しない場合、このプロシージャをコールするとエラーが発生します。

属性が特定の値に一致するまで、コレクションからすべてのメンバーを削除することもできます。次に例を示します。

APEX_COLLECTION.DELETE_MEMBERS(
    p_collection_name => collection name,
    p_attr_number     => number of attribute used to match for the specified
                         attribute value for deletion, 
    p_attr_value      => attribute value of the member attribute used to 
                         match for deletion);

DELETE_MEMBERSプロシージャでも、順序番号の欠落は指定したコレクションにそのまま残ります。次の場合に、このプロシージャによりエラーが発生します。

指定したコレクションが存在しない場合。
指定した属性番号が1から50の範囲外であるか、無効である場合。

指定した属性値がNULLの場合、指定したコレクションのうち、属性(p_attr_numberで指定)がNULLであるすべてのメンバーが削除されます。

コレクション・ステータスの判別

p_generate_md5パラメータは、コレクションの各メンバーに対してMD5メッセージ・ダイジェストを計算するかどうかを判別します。コレクションの作成直後、コレクション・ステータス・フラグはFALSEに設定されます。コレクションに対して操作(追加、更新、切捨てなど)が行われると、このフラグはTRUEに設定されます。

このフラグは、RESET_COLLECTION_CHANGEDをコールすることで、手動でリセットできます。次に例を示します。

APEX_COLLECTION.RESET_COLLECTION_CHANGED (
    p_collection_name => collection name)

このフラグをリセットした後にコレクションが変更されたかどうかを判別するには、COLLECTION_HAS_CHANGEDをコールします。次に例を示します。

l_changed := APEX_COLLECTION.COLLECTION_HAS_CHANGED(
  p_collection_name => collection_name);

p_generated_md5パラメータがYESに設定されている場合、コレクションに新しいメンバーを追加すると、50個のすべての属性とCLOB属性に対してMD5メッセージ・ダイジェストが計算されます。この値にはAPEX_COLLECTIONビューのMD5_ORIGINAL列からアクセスできます。GET_MEMBER_MD5ファンクションを使用して、指定したコレクション・メンバーの現在の値に対するMD5メッセージ・ダイジェストにアクセスできます。次に例を示します。

APEX_COLLECTION.GET_MEMBER_MD5 (
    p_collection_name => collection name,
    p_seq             => member sequence number );
    RETURN VARCHAR2;

コレクションのマージ

コレクションのメンバーを、配列の集合として渡した値とマージできます。p_init_query引数を使用することで、指定した問合せからコレクションを作成できます。

コレクションが存在する場合、次のことが発生することに注意してください。

コレクション内に存在し、配列内に存在しない行が削除されます。
コレクションおよび配列内の行が更新されます。
配列内に存在し、コレクション内に存在しない行が挿入されます。

4,000文字を超える属性は、4,000文字に切り捨てられます。表 15-1に、コレクションのマージに使用可能な引数を示します。

表 15-1 コレクションのマージに使用可能な引数

引数	説明
`p_collection_name`	コレクションの名前です。参照: 「コレクションの名前の指定について」
`p_seq`	マージするメンバーの順序番号を指定します。
`p_c001`	マージされる1番目の属性値の配列です。最大長は4,000文字です。最大長より大きい値は4,000文字に切り捨てられます。 P_C001 PL/SQL表内の要素数は、すべてのPL/SQL表内のアイテムの合計数として使用されます。たとえば、P_C001.count = 2およびP_C002.count = 10の場合、2つのメンバーのみがマージされます。P_C001がNULLの場合は、アプリケーション・エラーが発生することに注意してください。
`p_c0xx`	マージされる`XX`番目の属性値の属性です。最大長は4,000文字です。最大長より大きい値は4,000文字に切り捨てられます。
`p_null_index`	マージ・ファンクションで無視する行を識別するために使用します。この引数は、行をNULLとして識別します。NULL行は、コレクションから自動的に削除されます。
`p_null_value`	`p_null_index`とともに使用します。この引数は、null値を識別します。この値をNULLにすることはできません。この引数の通常の値は0 (ゼロ)です。
`p_init_query`	コレクションが存在しない場合に、この引数によって定義した問合せを使用してコレクションを作成できます。

コレクションの管理

コレクションの管理には、次のユーティリティを使用できます。

この項に含まれる内容は次のとおりです。

メンバー数の取得
コレクションの再順序付け
コレクションの存在の確認
メンバーの順序番号の調整
コレクション・メンバーのソート

メンバー数の取得

コレクション内のすべてのメンバーの合計数を戻すには、COLLECTION_MEMBER_COUNTを使用します。この数は、コレクション内の順序番号の最大値ではないことに注意してください。次に例を示します。

l_count := APEX_COLLECTION.COLLECTION_MEMBER_COUNT (
  p_collection_name => collection name );

コレクションの再順序付け

要素の順序を保持したままで、コレクションを再順序付けして順序番号の欠落を排除するには、RESEQUENCE_COLLECTIONを使用します。次に例を示します。

APEX_COLLECTION.RESEQUENCE_COLLECTION (
   p_collection_name => collection name )

コレクションの存在の確認

コレクションが存在するかどうかを確認するには、COLLECTION_EXISTSを使用します。次に例を示します。

l_exists := APEX_COLLECTION.COLLECTION_EXISTS  (
  p_collection_name => collection name );

メンバーの順序番号の調整

順序番号を上下に移動することで、コレクション内の特定のメンバーの順序番号を調整できます。順序番号を調整すると、指定した番号が別の番号と入れ替えられます。たとえば、番号2を1つ上に移動すると、2が3になり、3が2になります。

メンバーの順序番号を1つ上に移動するには、MOVE_MEMBER_UPを使用します。メンバーの順序番号を1つ下に移動するには、MOVE_MEMBER_DOWNを使用します。次に例を示します。

APEX_COLLECTION.MOVE_MEMBER_DOWN(
    p_collection_name => collection name,
    p_seq             => member sequence number);

これらのいずれかのメソッドの使用中は、次の場合にアプリケーション・エラーが表示されることに注意してください。

指定したコレクションが、カレント・ユーザーのカレント・セッションに存在しない場合
p_seq順序番号によって指定されたメンバーが存在しない場合

ただし、指定したメンバーにコレクション内で最も大きい番号または最も小さい番号(MOVE_MEMBER_UPまたはMOVE_MEMBER_DOWNのどちらをコールするかによる)が割り当てられている場合、アプリケーション・エラーは戻されません。

コレクション・メンバーのソート

コレクションのメンバーを列番号で並べ替えるには、SORT_MEMBERSメソッドを使用します。このメソッドは、特定の列番号でコレクションをソートし、各メンバーの順序番号の欠落を排除するように順序番号の再割当ても行います。次に例を示します。

APEX_COLLECTION.SORT_MEMBERS(
    p_collection_name       => collection name,
    p_sort_on_column_number => column number to sort by);

コレクションのセッション・ステートのクリア

コレクションのセッション・ステートをクリアすると、コレクションのメンバーを削除できます。ショッピング・カートは、コレクションのセッション・ステートをクリアする必要がある場合のよい例です。ユーザーがショッピング・カートを空にして再度開始するよう要求した場合に、コレクションのセッション・ステートをクリアする必要があります。TRUNCATE_COLLECTIONメソッドをコールするか、f?p構文を使用して、コレクションのセッション・ステートを削除できます。

TRUNCATE_COLLECTIONメソッドをコールすると、既存のコレクションが削除され、そのコレクションが再作成されます。次に例を示します。

APEX_COLLECTION.TRUNCATE_COLLECTION(
    p_collection_name => collection name);

f?p構文の6つ目の引数を使用してセッション・ステートをクリアすることもできます。次に例を示します。

f?p=App:Page:Session::NO:collection name

関連項目:

「URL構文の理解」