コレクションを使用すると、1つ以上の非スカラー値を一時的に取得できます。コレクションを使用して、現在セッション・ステートにある行および列を格納します。これによって、あるユーザーの特定のセッション中にそれらの行および列に対してアクセス、操作または処理を行うことができます。コレクションは、バケツのようなものと考えることができます。その中に情報の行を一時的に格納し、その情報を指定できます。
次に、コレクションを使用する場合の例を示します。
データ入力ウィザードを作成しており、そのウィザードで、まず論理トランザクション中に複数行の情報を収集する必要がある場合。物理トランザクションと論理トランザクションの両方の完了時、ウィザードの最終ステップを実行する前に、コレクションを使用して、複数行の情報のコンテンツを一時的に格納できます。
アプリケーションに、ユーザーが1つのページで複数の詳細行を更新する更新ページが含まれている場合。ユーザーは、複数の更新を行い、それらの更新をコレクションに適用した後、最終プロセスをコールしてそれらの変更をデータベースに適用できます。
任意の数の属性を収集するウィザードを構築している場合。コレクションに一時的に格納された情報が取得され、データベースに適用されるタスクをウィザードの最後にユーザーが実行するようにします。
この項に含まれる内容は次のとおりです。
各コレクションには、データ要素(メンバー)の名前付きリストが含まれます。このリストには、最大50個の文字属性(VARCHAR2(4000)
)および1個の大文字属性(CLOB
)を含めることができます。コレクション情報は、PL/SQL API APEX_COLLECTION
を使用して挿入、更新および削除します。
各コレクションには、データ要素(メンバー)の名前付きリストが含まれます。このリストには、最大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チェックサムは計算されません。
コレクションを切り捨てる場合、指定したコレクションからすべてのメンバーを削除しますが、指定したコレクションはそのまま残ります。次に例を示します。
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 );
コレクションを削除しない場合は、セッションがパージされると最終的にコレクションが削除されることに注意してください。次に例を示します。
コレクションに追加したデータ要素(メンバー)には、一意の順序番号が割り当てられます。メンバーをコレクションに追加すると、最も新しいメンバーが一番大きい番号を持つように、前のメンバーより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つ目の配列の要素数に基づきます。
コレクション・メンバーを更新するには、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 コレクションのマージに使用可能な引数
引数 | 説明 |
---|---|
|
コレクションの名前です。 |
|
マージするメンバーの順序番号を指定します。 |
|
マージされる1番目の属性値の配列です。最大長は4,000文字です。最大長より大きい値は4,000文字に切り捨てられます。 P_C001 PL/SQL表内の要素数は、すべてのPL/SQL表内のアイテムの合計数として使用されます。たとえば、P_C001.count = 2およびP_C002.count = 10の場合、2つのメンバーのみがマージされます。P_C001がNULLの場合は、アプリケーション・エラーが発生することに注意してください。 |
|
マージされる |
|
マージ・ファンクションで無視する行を識別するために使用します。この引数は、行をNULLとして識別します。NULL行は、コレクションから自動的に削除されます。 |
|
|
|
コレクションが存在しない場合に、この引数によって定義した問合せを使用してコレクションを作成できます。 |
コレクションの管理には、次のユーティリティを使用できます。
この項に含まれる内容は次のとおりです。
コレクション内のすべてのメンバーの合計数を戻すには、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
のどちらをコールするかによる)が割り当てられている場合、アプリケーション・エラーは戻されません。
コレクションのセッション・ステートをクリアすると、コレクションのメンバーを削除できます。ショッピング・カートは、コレクションのセッション・ステートをクリアする必要がある場合のよい例です。ユーザーがショッピング・カートを空にして再度開始するよう要求した場合に、コレクションのセッション・ステートをクリアする必要があります。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