| Oracle® Database SecureFilesおよびラージ・オブジェクト開発者ガイド 11gリリース2 (11.2) B56263-04 |
|
 前 |
 次 |
この章の内容は次のとおりです。
DBFSコンテンツAPIは、ファイルシステムに類似した抽象化を提供するメソッドの集合です。これは、1つ以上のDBFSストア・プロバイダによって支えられます。DBFSコンテンツAPIの「コンテンツ」は、メタデータ付きのファイルで、表のSecureFiles BLOB(および他の列)にマップするかデータベース内で実行されるJavaまたはPL/SQLのユーザーが記述したプラグインで動的に作成するかのいずれかが可能です。後者の形式は「プロバイダ」と呼ばれます。
DBFSコンテンツAPIは、SecureFilesベースのストア・プロバイダ実装(DBMS_DBFS_SFS)に付属し、SecureFiles LOBベースのファイルシステムを作成できます。さらに、標準DBFSコンテンツAPIインタフェースを介して、別の(サード・パーティの)ストアに格納されたコンテンツをアプリケーションで読取りおよび書込みできます。
プロバイダの例を次に示します。
コンテンツDBに類似したコンテンツ・アプリケーション。
ファイルによってデータを覆うパッケージ・アプリケーション。
ファイルシステム・インタフェースを利用するカスタム・アプリケーション。医療イメージを格納するアプリケーションなどがあります。
ストアは、ドキュメントのコレクションです。各ドキュメントは、/として表された一意の絶対パス名の後ろに1つ以上のコンポーネント名が/で区切られた状態で並ぶ形式によって識別されます。一部のストアではフラットなネームスペースのみが実装されますが、他のストアではディレクトリまたはフォルダが暗黙的に実装され、さらに他のストアではファイルシステムに類似したエンティティのコレクションが包括的に実装される場合があります。これらには、階層ディレクトリ、ファイル、シンボリック・リンク、ハード・リンク、参照などが含まれる場合があります。多くの場合、これらには、ドキュメントに関連付けられた一連の豊富なメタデータや、セキュリティ、アクセス制御、ロック、バージョニング、コンテンツ・アドレッシング、保存制御などに関する一連の豊富な動作が含まれます。
一般に、ストアは別個に設計および展開されるため、特定のストアを使用するアプリケーションは、ストアの開発者によって記述またはパッケージされているか、またはユーザーがストア固有のAPIを使用することが必要です。ストア自体の実装に使用するデータ表のスキーマの詳細な知識が必要になる場合もあります。
DBFSコンテンツAPIはクライアント側プログラムAPIパッケージDBMS_DBFS_CONTENTであり、各種ストアの共通の機能を、ポータブル・クライアント・アプリケーションの作成に使用できる簡単かつ最小のインタフェースに抽象化します。これは、ストア固有のライブラリおよび実装から切り離して行われます。
DBFSコンテンツAPIは、曖昧さをなくすためにパス名の最初のコンポーネントを使用して1つ以上のストアのパス・ネームスペースを単一のネームスペースに統合し、このネームスペースをクライアント・アプリケーションに示します。これによりクライアントは、単一文字列で表された完全な絶対パス名(/store_name/store_specific_path_name)、またはタプル文字列で表されたストアで修飾されたパス名(store_name、/store_specific_path_name)のいずれかを使用して、基礎となるドキュメントにアクセスできます。
次に、DBFSコンテンツAPIは、パス名に対する各種操作を適切なストアに正しくディスパッチし、結果をクライアントで必要なネームスペースに統合します。
ストア・プロバイダは、パッケージDBMS_DBFS_CONTENT_SPIによる宣言のとおり、サービス・プロバイダ・インタフェース(SPI)に準拠する必要があります。SPIはクライアント側APIではなく、DBFSコンテンツAPIとそれらのAPIに接続する必要がある各種ストアの間のプライベート契約の役割を持ちます。
DBFSコンテンツAPIにより、クライアントで表示可能な各種ストアの操作の標準および例外的な動作が定義され、選択に応じて豊富な機能を異なるストアで実装できます。APIにより、ストアは機能を自己記述でき、インテリジェント・クライアント・アプリケーションは、名前または実装で識別されるストア固有のハードコード・ロジックではなく、これらの機能に基づいて動作のチューニングが可能です。
DBMS_DBFS_CONTENTパッケージの詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
DBMS_DBFS_CONTENTは、Oracle Database 11gリリース2以降に付属しており、インストールは必要ありません。
詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
コンテンツの操作および管理API(パッケージ、タイプ、表など)には、dbfs_roleを使用してアクセスできます。このロールは、必要に応じてすべてのユーザーに付与されます。
PATH_MAXは、クライアントで表示可能な絶対パス名の最大長です。NAME_MAXは、クライアントで表示可能な絶対パス名の個別のコンポーネントの最大長です。これらの定数は、SecureFiles LOBストアの一方に基づいて作成されます。
PL/SQLタイプpath_tおよびname_tは、パス名およびコンポーネント名を表す文字列のポータブルな別名です。
ストア内のすべてのパス名は、プロパティのセットに関連付けられています。簡易性と汎用性のために、各プロパティは文字列名で識別され、文字列値(未設定または特定のストア実装で未定義もしくは非サポートの場合はnullの可能性あり)および値タイプコード(値文字列で保持される実際の値のタイプに対する数値判別)を持ちます。
プロパティ値を文字列へ強制変換すると、各種インタフェースを統一して簡潔にできる利点があり、基礎となるストアの実装の簡素化も可能です。ただし、文字列間の変換中に情報が損失する危険性があります。
クライアントおよびストアは、これらの変換に明確に定義されたデータベース表記規則を使用し、必要に応じてtypecodeフィールドを使用することが前提です。
PROPNAME_MAXはプロパティ名の最大長で、PROPVAL_MAXはプロパティの文字列値の最大長です。
PL/SQLタイプpropname_tおよびpropval_tは、プロパティ名および値を表す文字列のポータブルな別名です。タイプコードは、数値(dbms_typesで定義される各種定数を参照)で、文字列強制変換されたプロパティ値の本当のタイプを表します。dbms_typesで定義されるすべてのタイプコードが、ストアで等しくサポート可能である必要はありません。単純なスカラー・タイプ(数値、日付、タイムスタンプなど)はクライアントで依存可能であり、ストアで実装される必要があります。
標準RDBMSタイプコードは正の整数であるため、DBFSコンテンツAPIでは、負のタイプコードによるクライアント定義タイプを負の整数で示すことができます。これらのタイプコードは標準タイプコードと競合せず、永続的になって、必要に応じてクライアントに戻されますが、DBFSコンテンツAPIやいずれか特定のストアで解析される必要はありません。ポータブル・クライアント・アプリケーションでは、特定のストアに情報を渡すバックドアの方法としてユーザー定義のタイプコードを使用しないでください。
dbms_dbfs_content_property_tオブジェクト・タイプは、単一の(名前、値、タイプコード)プロパティ・タプルを記述します。すべてのプロパティ(標準、オプションおよびユーザー定義)は、このタプルを介して記述されます。
dbms_dbfs_content_properties_tは、可変サイズのプロパティ・タプルの配列です。これら2つのタイプは、クライアント向けのAPI、およびDBFSコンテンツAPI用のストア・プロバイダの両方で使用されます。
DBMS_DBFS_CONTENT定数およびプロパティの詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』、DBMS_DBFS_CONTENT_PROPERTY_Tパッケージの詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
ストアでは、4つのタイプのエンティティへのアクセスを格納および提供します。
type_fileは、BLOBとしてアクセスするバイトの論理的な線形順序としてコンテンツを格納する標準ファイルです。
type_directoryは、ファイル・タイプを含むその他のパス名タイプのコンテナです。
type_linkは、シンボリック・リンク、つまりパス名に関連付けられた未解析の文字列値です。シンボリック・リンクは、所定のストア(またはDBFSコンテンツAPIで管理されるストアの集合全体)の範囲外にあるパス名を表す場合、またはパス名を表さない場合もあるため、クライアントではシンボリック・リンクの作成に注意が必要であり、ストアではこれらのリンクの内部的な解決を試行する際に注意が必要です。
type_referenceは、コンテンツに対するハード・リンク(必ず有効なパス名の別名)です。
すべてのストアで、すべてのディレクトリ、リンクまたは参照を実装する必要はありません。DBMS_DBFS_CONTENT定数およびパス名のタイプの詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』の「ストア機能」を参照してください。
共通のプログラム・インタフェースを、可能なかぎり多くの異なるタイプのストアに提供するために、DBFSコンテンツAPIでは、個別のストア・プロバイダが各種操作の動作の一部を定義および実装できます。ただし、クライアント側プログラマに、ポータブル・アプリケーションで役立つ豊富なAPIを提供することも重要です。
DBFSコンテンツAPIでは、これを実現するために、異なるストア・プロバイダ(および異なるストア)が機能セット(サポートする機能およびサポートしない機能を示すビット・マスク)を使用して、自ら記述することを可能にしています。
追加のロジックをクライアント側に実装し、複雑な操作をサポート可能なストアに委ねることで、特定のストアの機能の不足を補正するクライアント・アプリケーションにとって、機能セットの使用は可能ではあっても容易ではありません。
feature_foldersは、ストアで階層パス名の一部としてフォルダ(またはディレクトリ)をサポートする場合に設定されます。
feature_foiatは、(クライアントがリクエストする操作の一部として実行される)ストア内の暗黙的フォルダ操作を、自律型トランザクションの内部で実行する場合に設定されます。一般に、自律型トランザクションの使用は、同時実行性の大幅な削減による、実装の簡略化およびすべての操作に向けたクライアント制御トランザクション範囲(feature_foiatを設定しない)と、同時実行性の大幅な増加による、複雑な実装および狭いクライアント制御トランザクション範囲(feature_foiatを設定)の2つのバランスの上に成り立ちます。。
読取り専用(主に読取り)ストアへのアクセスは、この機能の影響を大きく受けることがないようにしてください。
feature_aclsは、ストアでアクセス制御リスト(ACL)およびこれらのACLに基づく内部認可ならびにチェックをサポートする場合に設定されます。ACLは標準プロパティですが、ストアはACLのいかなる解析も行わず、格納および取得のみを実行します。
feature_linksまたはfeature_link_derefは、ストアでシンボリック・リンクをサポートし、特定のタイプのシンボリック・リンク(特に絶対パス名ではない場合など)をストア自体により内部的に解決する場合に設定されます。
feature_referencesは、ストアでハード・リンクをサポートする場合に設定されます。
feature_lockingは、ストアの各種アイテムに適用可能なユーザー・レベルのロック(読取り専用、書込み専用、読取り/書込み)をストアでサポートし、ロックされたアイテムへの各種タイプのアクセスをそれらのロック設定を使用して制御する場合に設定されます。ユーザー・レベルのロックはトランザクション・ロックに対して直交で、特定のトランザクション、セッションまたは接続の範囲を超えて存続します。これは、ロックのダングリングの後にストア自体でクリーンアップできず、クライアント・アプリケーションでガベージ・コレクションを実行する必要があることを意味します。
feature_lock_hierarchyは、ストアで、ロックされたパス名下のサブツリー全体へのアクセスをユーザー・ロックが制御できるようにする場合に設定されます。単純なロック・モデルでは、ロック・セマンティクスは特定のパス名にのみ適用され、親または子に対するロックに依存します(リクエストされた操作でこれらの親または子を暗黙的に変更しない場合)。
feature_lock_convertは、ストアで、あるモードから別のモードへのロックのアップグレードまたはダウングレードをサポートする場合に設定されます。
feature_versioningは、ストアで少なくとも線形バージョニングおよびバージョン管理をサポートする場合に設定されます。同じパス名の異なるバージョンは、単調なバージョン番号と、最新バージョンを示すバージョン非修飾パス名で識別されます。
feature_version_pathは、ストアでパス名の異なるバージョンの階層ネームスペースをサポートする場合に設定されます。
feature_soft_deletesは、ストアでソフト削除、つまりパス名を削除して通常の操作で非表示にするが、後でパス名をリストア(新しい作成操作で上書きされない場合)できるようにする機能をサポートする場合に設定されます。ストアでは、ソフト削除されたパス名のパージ(完全な削除)およびソフト削除されたアイテムを表示するナビゲーション・モードもサポートされます。
feature_hashingは、ストアで、パス名(一般にtype_fileパス)のコンテンツに対するセキュアなハッシュの一部のタイプを自動的に計算し保持する場合に設定されます。
feature_hash_lookupは、ストアでコンテンツ・ベース・アドレッシング、つまりパス名ではなくコンテンツ・ハッシュに基づいてコンテンツ・アイテムを検索する機能を使用できるようにする場合に設定されます。
feature_filteringは、ストアで、指定のストア・アイテムが選択述語を満たしているかどうかを示す論理ブール値を戻すフィルタ関数(特定の関数シグネチャに準拠するPL/SQL関数)をクライアントが渡せるようにする場合に設定されます。フィルタリングをサポートするストアでは、実装内にフィルタリング・ロジックを埋め込むことで、アイテムのリスト、ディレクトリのナビゲーションおよび削除をより効率的に実行できます。フィルタリングがサポートされない場合、効率は落ちますが、クライアントでは必要以上のアイテムを取得して、自身でフィルタリング・チェックを実行できます。
フィルタ述語は、次のシグネチャを持つ関数です。
function filterFunction(
path in varchar2,
store_name in varchar2,
opcode in integer,
item_type in integer,
properties in dbms_dbfs_content_properties_t,
content in blob)
return integer;
このシグネチャに準拠する任意のPL/SQL関数を使用すると、ストア・アイテムのコンテンツおよびプロパティを調べ、アイテムが現在の操作の選択基準を満たしているかを判別できます。戻り値true(非ゼロ)では、DBFSコンテンツAPIでアイテムは現在の操作の一部として処理され、戻り値false(ゼロまたはnull)では、アイテムは処理から完全にスキップされます。
feature_searchingは、ストアで、クライアントがテキスト検索フィルタ問合せを渡し、そのコンテンツに基いてtype_fileパス名を検索できるようにする場合に設定されます。検索をサポートするストアでは、索引を使用することで検索が強化されますが、使用しない場合、クライアントでは独自の索引を作成するか、または可能性のあるアイテムの大きいセットを検索して、現在の検索の対象を特定します。
feature_asofは、ストアで、クライアントが問合せ操作(非変異getPath()、リスト、検索)でフラッシュバック・タイムスタンプを使用できるようにする場合に設定されます。
feature_provider_propsは、ストアで、(個々のアイテムに関連付けられたプロパティとは異なり、現在の操作に対するストアの動作を制御する)操作ごとのプロパティを使用できるようにする場合に設定されます。
DBMS_DBFS_CONTENT定数-ストア機能の詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
ロックをサポートするストアでは、lock_read_only、lock_write_only、lock_read_writeの3タイプのロックの実装が必要です。
ユーザー・ロック(3タイプの1つ)は、ユーザー指定のlock_dataに関連付けが可能です。これはストアにより解析されませんが、クライアント・アプリケーションで独自の目的(たとえば、クライアント・アプリケーションで、ガベージ・コレクションの失効ロックや明示的なロック解除などのアクションを制御するために後からこの情報を使用すると想定して、ユーザー・データによりロックが行われた時刻を示すことができるなど)のために使用できます。
単純なロック・モデルでは、lock_read_onlyにより、パス名に対するすべての明示的な変更ができなく(ただし暗黙的変更および親/子パス名の変更は可能)なります。lock_write_onlyにより、パス名に対するすべての明示的な読取りができなく(ただし暗黙的読取りおよび親/子パス名の読取りは可能)になります。lock_read_writeでは、両方が可能です。
すべてのロックは、ロック操作を実行するプリンシパルに関連付けられます。ロックをサポートするストアではこの情報を保持し、読取り/書込みロック・チェックの実行に使用する必要があります(opt_lockerを参照)。
より複雑なロック・モデルでは、複数の読取りロック、パス名階層間のロックの範囲指定、ロック変換、グループ・ロックなどが可能ですが、現在、DBFSコンテンツAPIでは定義されていません。
DBMS_DBFS_CONTENT定数およびロック・タイプの詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
標準プロパティは、すべてのストアで(DBFSコンテンツAPIで記述されている方法で)サポートされる必要があるすべてのコンテンツ・パス名に関連付けられた、正しく定義された必須プロパティで、いくつかの特権(たとえば、読取り専用ストアでは、modification_timeまたはcreation_timeの実装が不要であること、固定スキーマのある表に対して作成されたストアでは、これらのプロパティの必要なだけ多くに対して適切なデフォルトを選択できることなど)があります。
すべての標準プロパティでは、非公式に、std:ネームスペースが使用されます。クライアントおよびストアで、独自のプロパティの定義にこのネームスペースを使用すると、将来競合が発生する原因となるため、このネームスペースの使用は避ける必要があります。
次の標準プロパティのメニューは、長期にわたって一定である必要があります。
std_access_time(UTCのTYPECODE_TIMESTAMP)
パス名のコンテンツが最後にアクセスされた時間。
std_acl(TYPECODE_VARCHAR2)
パス名に関連付けられたアクセス制御リスト(標準ACL構文)。
std_canonical_path(TYPECODE_VARCHAR2)
適切にクリーンアップされた(最初と最後が/で閉じられた、切り捨てられたなど)、アイテムのストア固有の正規パス名。
std_change_time(UTCのTYPECODE_TIMESTAMP)
パス名のメタデータが最後に変更された時間。
std_children(TYPECODE_NUMBER)
ディレクトリ/フォルダ・パスにある子ディレクトリ/フォルダの数(このプロパティは、feature_foldersをサポートするプロバイダで使用できる必要があります)。
std_content_type(TYPECODE_VARCHAR2)
パス名(通常type_file)を記述する、クライアントで提供されるMIMEタイプ(標準RFC構文)。コンテンツ・タイプは、ストアにより必ず解析されるとはかぎりません。
std_creation_time(UTCのTYPECODE_TIMESTAMP)
アイテムが作成された時間(1回設定されると、この値はパス名の存続期間を通して変更されません)。
std_deleted(booleanのTYPECODE_NUMBER)
パス名がソフト削除(この機能については前述を参照)されたがパージされていない場合、ゼロ以外の数字に設定します。
std_guid(TYPECODE_NUMBER)
パス名に対するストア固有の一意の識別子。クライアントは、異なるストア間で一意であるGUIDに依存できませんが、指定された(store-name、store-specific-pathname)には、その存続期間を通して一定かつ一意のGUIDがあります。
std_length(TYPECODE_NUMBER)
type_fileまたはtype_referenceパスのコンテンツの長さ(BLOB)、またはtype_linkシンボリック・リンクの対象の長さ。ディレクトリの長さは正しく定義されていないため、ストアでは、このプロパティをゼロ、nullまたはその他の任意の値に設定できます。
std_modification_time(UTCのTYPECODE_TIMESTAMP)
パス名に関連付けられたデータが最後に変更された時間。type_fileまたはtype_referenceパスのコンテンツの変更、type_linkパスの対象の変更、およびtype_directoryパスの直接の子の追加/削除により、すべての構成データが変更されます。
std_owner(TYPECODE_VARCHAR2)
パス名に対する、クライアントが提供する(暗黙的な)所有者名。所有者名は、ACLまたはロック(あるいはその両方)をサポートするストアによるチェックへのアクセスで(現在のプリンシパルとともに)使用されます。
std_parent_guid(TYPECODE_NUMBER)
パス名の親に対するストア固有の一意の識別子です。クライアントは、異なるストア間で一意であるGUIDに依存できませんが、指定された(store-name、store-specific-pathname)には、その存続期間を通して一定かつ一意のGUIDがあります。
std_parent_guid (pathname == std_guid(parent(pathname))):
std_referent(TYPECODE_VARCHAR2)
type_linkパスのシンボリック・リンクのコンテンツ、それ以外の場合はnull。前述のとおり、std_referentは任意の文字列になることができ、必ずしもクライアントでパス名として解釈される必要はありません(このような解釈を行う場合は十分な注意が必要です)。
DBMS_DBFS_CONTENT定数および標準プロパティの詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
オプション・プロパティは、正しく定義されているが、すべてのストアで自由に(しかしDBFSコンテンツAPIで記述されている方法でのみ)サポートされるすべてのコンテンツ・パス名に関連付けられた必須ではないプロパティです。オプション・プロパティをまったくサポートしないストアに対応できるように、クライアントを準備する必要があります。
すべてのオプション・プロパティでは、非公式に、opt:ネームスペースが使用されます。クライアントおよびストアで、独自のプロパティの定義にこのネームスペースを使用すると、将来競合が発生する原因となるため、このネームスペースの使用は避ける必要があります。
次のオプション・プロパティのメニューは、長期にわたって拡張される必要があります。
opt_hash_type(TYPECODE_NUMBER)
opt_hash_valueプロパティ内で指定されるハッシュのタイプ。使用可能なオプションはdbms_cryptoを参照してください。
opt_hash_value(TYPECODE_RAW)
パス名のコンテンツを説明するタイプopt_hash_valueのハッシュ値。
opt_lock_count(TYPECODE_NUMBER)
パス名に対して行われた(互換)ロックの数。パスに対して異なるプリンシパルで互換(読取り)ロックを行うことが可能な場合、opt_lockerで(ロック件数が正しく保持されように繰り返して)すべてのロッカーを指定する必要があります。
opt_lock_data(TYPECODE_VARCHAR2)
ストアで解析されない、クライアントが指定したユーザー・ロックに関連付けられたユーザー・データ。
opt_locker(TYPECODE_VARCHAR2)
パス名に対してユーザー・ロックを適用する、暗黙的またはクライアントが指定したプリンシパル。
opt_lock_status(TYPECODE_NUMBER)
現在パス名に対して適用されているロックのタイプを説明する値(lock_read_only、lock_write_only、lock_read_write)のいずれか1つ。
opt_version(TYPECODE_NUMBER)
パス名の線形バージョニングの順序番号。
opt_version_path(TYPECODE_VARCHAR2)
パス名の階層バージョニングのバージョン・パス名。
DBMS_DBFS_CONTENT定数およびオプション・プロパティの詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
プロパティを取得および設定するDBFSコンテンツAPIメソッドでは、プロパティ・アクセス・フラグを組み合せて使用して、単一APIコール内の異なるネームスペースからプロパティをフェッチできます。
prop_none
クライアントがいずれのプロパティも必要としないが、別の理由(パス名の存在/ロック可能性の検証、データ・アクセスなど)によりコンテンツ・アクセス・メソッドを呼び出している場合に使用します。
prop_std
クライアントが標準プロパティを必要とする場合に使用します。このフラグが指定されると、すべての標準プロパティが取得されます。
prop_opt
クライアントがオプション・プロパティを必要とする場合に使用します。このフラグが指定されると、すべてのオプション・プロパティが取得されます。
prop_usr
クライアントがユーザー定義プロパティを必要とする場合に使用します。このフラグが指定されると、すべてのユーザー定義プロパティが取得されます。
prop_all
すべての標準、オプションおよびユーザー定義プロパティの組合せの別名です。
prop_data
クライアントがデータ・アクセスのみを必要とし、プロパティを必要としない場合に使用します。
prop_spc
クライアントで各種プロパティ・ネームスペースの異なるサブセットの組合せが必要とされ、フェッチする特定のプロパティの名前がDBFSコンテンツAPIメソッド・コールに引数として渡され、これらのプロパティ値のみがフェッチされてクライアントに戻される場合に使用します。これは、アクセス可能なプロパティが多数あるが、クライアントが必要とするプロパティはその内の少数である(そして事前にそれらのプロパティ名がわかっている)場合に役立ちます。
prop_spcは、各種のgetPath()操作にのみ適用可能です。プロパティを指定するその他の操作では、prop_spc指定は単純に無視されます。
DBMS_DBFS_CONTENT定数およびプロパティ・アクセス・フラグの詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
DBFSコンテンツAPI操作では、次のいずれかのトップレベルの例外が発生します。
クライアントでは、基礎となるエラー・シグナリング・コードの特定のストア実装を気にすることなく、エラー・ハンドラでこれらの特定の例外に対するプログラミングが可能です。
ストア・サービス・プロバイダは、必要に応じて内部例外を次の例外タイプのいずれかにトラップおよびラップするよう最大限を行う必要があります。
DBMS_DBFS_CONTENT定数およびオプション・コードの詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
property_tレコード・タイプは、単一(値、タイプコード)プロパティ値タプルを説明し、プロパティ名は暗黙的です(次のコード・スニペットのproperties_tを参照)。
properties_tは、名前で索引付けされたプロパティ・タプルのハッシュ表です。索引と値の間の暗黙的なハッシュ表の関連付けにより、クライアントでproperties_tの完全なdbms_dbfs_content_property_tタプルを作成できます。
dbms_dbfs_content_property_tとproperty_tはほぼ対応するものです。前者は完全プロパティ・タプルを説明するSQLオブジェクト・タイプであり、後者はプロパティ値コンポーネントのみを説明するPL/SQLレコード・タイプです。
dbms_dbfs_content_properties_tとproperties_t.はほぼ対応するものです。前者はSQLネスト表タイプであり、後者はPL/SQLハッシュ表タイプです。
動的SQLコール規則ではSQLタイプの使用を強制しますが、ハッシュ表タイプの点では、PL/SQLコードはより簡単に実装されます。
DBFSコンテンツAPIにより、dbms_dbfs_content_properties_tとproperties_t間の変換に便利なユーティリティ関数が提供されます(次のコード・スニペットを参照)。
PROPERTY_Tレコード・タイプの詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
管理クライアントおよびコンテンツ・プロバイダは、コンテンツ・ストアをDBFSコンテンツAPIに登録する必要があります。また、管理クライアントは、選択したトップレベルのネームスペースにストアをマウントする必要があります。
同じストアを複数回、別々のマウント・ポイントにマウントすることが可能であるため(これはクライアント制御下で行われる)、ストアの登録および登録解除は、ストアのマウントおよびアンマウントとは分離されます。
DBMS_DBFS_CONTENT内の管理メソッドは、DBMS_DBFS_CONTENT_ADMIN内の一致するメソッドに委任する単なるラッパーです。クライアントでは、いずれかのパッケージのメソッドを使用して、管理操作を実行できます。
DBMS_DBFS_CONTENTパッケージ・メソッドの概要は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
REGISTERSTORE()プロシージャでは、ストア・サービス・プロバイダとしてprovider_packageを使用するプロバイダによりバックアップされる新規のストアが登録されます(DBMS_DBFS_CONTENT_SPIパッケージ・シグネチャに準拠)。
このメソッドは、新規ストアの作成後にサービス・プロバイダで使用されるように設計されています。ストア名は、一意にする必要があります。
REGISTERSTORE()メソッドの詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
プロシージャUNREGISTERSTORE()により、(関連付けられたすべてのマウント・ポイントを無効にすることで)以前に登録されたストアが登録解除されます。登録を解除すると、ストア(およびそのマウント・ポイント)へのすべてのアクセスの動作は保証されなくなります(読取り一貫性により一時的にアクセスが継続する場合があります)。
ignore_unknown引数がtrueの場合、不明なストアを登録解除しても例外は発生しません。
UNREGISTERSTORE()メソッドの詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
プロシージャMOUNTSTORE()により、登録済ストアがマウントされてマウント・ポイントにバインドされます。
マウントされると、/store_mount/xyzの形式のパス名へのアクセスは、store_nameおよびそのコンテンツ・プロバイダにリダイレクトされます。
ストア・マウント・ポイントは一意であり、構文的に有効なパス名コンポーネントである必要があります(つまり/が埋め込まれていないname_t)。
マウント・ポイントが指定されていない場合(つまりnull)、DBFSコンテンツAPIでは、ストア名自体をマウント・ポイント名として使用します(一意性および構文的な制約の対象)。
空の特別なマウント・ポイントは単一ストアで使用可能です。つまり、DBFSコンテンツAPIが単一バックエンド・ストアを管理するシナリオです。そのような場合、これらのアクセスのリダイレクト方法は明確であるため、クライアントは/xyzの形式の完全パス名を直接処理できます。
単一マウント・ポイントは、singletonブール引数で示され、store_mount引数は無視されます。
同一のストアを別々のマウント・ポイントで複数回マウントできます。
マウント・プロパティを使用して、DBFSコンテンツAPI実行環境、つまり特定のマウント・ポイントのプリンシパル、所有者、ACLおよびasofのデフォルト値を指定できます。また、マウント・プロパティを使用して、読取り専用ストアも指定できます。
MOUNTSTORE()メソッドの詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
プロシージャUNMOUNTSTORE()により、名前またはマウント・ポイントのいずれかで以前にマウントされたストアがアンマウントされます。単一のストアは、マウント・ポイントがないため、ストア名によってのみアンマウントできます。名前によりストアをアンマウントしようとすると、そのストアに関連付けられているすべてのマウント・ポイントがアンマウントされます。
アンマウントすると、ストア(またはマウント・ポイント)へのすべてのアクセスの動作は保証されなくなります(読取り一貫性により一時的にアクセスが継続する場合があります)。ignore_unknown引数がtrueの場合、不明なストア/マウントを登録解除しても例外は発生しません。
UNMOUNTSTOREメソッドの詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
LISTSTORE()関数により、使用可能なすべてのストアがリストされます。マウント・ポイントがストア自体から分離されているため、戻されたレコードのstore_mountフィールドは、nullに設定されます。
LISTSTORES関数の詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
LISTMOUNTS()関数により、使用可能なすべてのマウント・ポイント、そのバックアップ・ストアおよびストア機能がリストされます。単一マウントの結果、store_mountフィールドがnullに設定された単一行が戻されます。
LISTMOUNTS()メソッドの詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
GETSTOREBYXXX()関数およびGETFEATUREBYXXX()関数により、パス名、ストア名またはマウント・ポイントが参照されます。
DBMS_DBFS_CONTENTメソッドの詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
クライアントではSPACEUSAGE()メソッドを使用して、ファイルシステムの領域使用量統計を問合せできます。プロバイダは、ストアに対してこのメソッドをサポートし、特にストアが複数の表、索引、LOBなどで構成される場合は、領域使用量をできるかぎり特定する必要があります。
blksizeは、ストアを保持する通常の表領域ブロック・サイズであり、ブロック・サイズが異なる複数の表領域が使用されている場合、任意の有効なブロック・サイズが許容されます。
tbytesは、ストアの合計サイズ(バイト単位)であり、fbytesはストアの空き/未使用サイズ(バイト単位)です。これらの値は、ストアを構成するすべてのセグメントから計算されます。
nfile、ndir、nlinkおよびnrefにより、ストア内で現在使用可能なファイル、ディレクトリ、リンクおよび参照の数がカウントされます。
データベース・オブジェクトは動的に増加するため、空き領域と使用済領域の区分を測定するのは容易ではありません。
トップレベルのルート・ディレクトリで領域使用量を問い合せると、その下にある使用可能なすべての個別のストアの領域使用量を合計したサマリーが戻されます(同じストアが複数回マウントされていても、1回としてカウントされます)。
SPACEUSAGE()メソッドの詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
DBFSコンテンツAPIへの通常のクライアント・アクセスは、次で構成される暗黙的コンテキストで実行されます。
現在の操作を呼び出すprincipal。
現在の操作により(暗黙的または明示的に)作成されたすべての新規要素のowner。
現在の操作により(暗黙的または明示的に)作成されたすべての新規要素のACL。
基礎となる読取り専用操作(またはその読取り専用サブコンポーネント)が実行されるASOFタイムスタンプ。
このすべての情報は、引数によって各種のDBFSコンテンツAPIメソッド・コールに明示的に渡され、クライアントによって個別の操作のファイングレイン制御が可能になります。
また、DBFSコンテンツAPIによりクライアントは、デフォルトが明示的にオーバーライドされないすべての操作で自動的に継承されるコンテキストで、セッション期間のデフォルトを設定できます。
コンテキストのすべてのデフォルトはnullとして開始され、これらをnullに設定することでクリアできます。
DBMS_DBFS_CONTENTメソッドの詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
DBFSコンテンツAPI自体の進化を可能にするために、パブリックAPIが変更されるたびに内部的な数値APIバージョンが大きくなります。
GETVERSION()メソッドの詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
DBFSコンテンツAPIのクライアントでは、絶対パス名を介してストア・アイテムが参照されます。これらのパス名は、完全パス名(/mount_point/pathname形式の単一文字列)、またはストアで修飾されたパス名(store_name、pathnameの形式のタプルで、パス名のルートがストア・ネームスペース内にある)になります。
クライアントはそれぞれに適したネーミング・スキームのいずれかを使用し、プログラム内では両方のネーミング・メソッドを使用できます。
DBFSコンテンツAPIコールによってパス名が戻されると、戻される正確な値は、クライアントがコールで使用するネーミング・スキームに依存します。たとえば、完全修飾ディレクトリ名に対するリストまたは検索の場合、完全修飾パス名でアイテムが戻され、ストア修飾ディレクトリ名のリストまたは検索の場合は、ストア固有の(つまりストア修飾を意味する)パス名でアイテムが戻されます。
DBFSコンテンツAPIの実装では、これらの2つのネーミング・スキームの間の正規化および内部変換が内部的に管理されます。
DBFSコンテンツAPIにより、クライアントでディレクトリ、ファイル、リンクおよび参照要素(ストア機能のサポート対象)を作成できます。
すべての作成メソッドでは、有効なパス名が必要であり、パス名が作成されるときにプロパティがパス名と関連付けられるようオプションとして指定できます。std_creation_timeなど、自動的に生成されたプロパティがただちにクライアントに使用可能になるように、作成完了後にクライアントが項目のプロパティをフェッチ・バックすることも可能です。フェッチ・バックされる正確なプロパティのセットは、prop_flagsにある様々なprop_xxxビット・マスクによって制御されます。
リンクおよび参照には、プライマリ・パス名と関連付けるための追加パス名が必要です。ファイル・パス名では、オプションでBLOB値を指定して、基礎となるファイルのコンテンツを最初に移入するために使用できます(指定されるBLOBは、一時LOBまたは永続LOBの任意の有効なLOBです)。prop_flagsでprop_dataが指定されている場合は、作成時に基礎となるLOBがクライアントに戻されます。
ディレクトリ以外のパス名では、親ディレクトリを最初に作成する必要があります。ディレクトリ・パス名自体を再帰的に作成できます。つまり、ディレクトリまでつながるパス名階層を1回のコールで作成できます。
既存のパスを作成しようとするとエラーが発生します。例外はソフト削除されたパス名です。この場合、ソフト削除されたアイテムは暗黙的にパージされ、新しいアイテムの作成が試行されます。
DBMS_DBFS_CONTENT()メソッドの詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
DBFSコンテンツAPIにより、クライアントでディレクトリ、ファイル、リンクおよび参照要素(ストア機能のサポート対象)を削除できます。
デフォルトでは、削除は永続的で、トランザクション・コミットで正常に削除されたアイテムを削除します。ただし、リポジトリではソフト削除の機能もサポートされます。クライアントのリクエストがあれば、ソフト削除されたアイテムはストアで保持されます。ただし、通常のリストや検索では表示されません。ソフト削除されたアイテムは、リストアまたは明示的なパージが可能です。
ディレクトリ・パス名は再帰的に削除できます(つまり、ディレクトリの下のパス名階層を1回のコールで削除できます)。再帰的でない削除は、空のディレクトリでのみ実行できます。再帰的なソフト削除では、削除されるすべてのアイテムにソフト削除が適用されます。
個別のパス名(またはディレクトリ下のソフト削除されたすべてのパス名)は、RESTOREXXX()メソッドおよびPURGEXXX()メソッドを使用してリストアまたはパージできます。
フィルタリングをサポートするプロバイダでは、プロバイダ・フィルタを使用して削除するアイテムのサブセットを識別できます。これにより、deleteDirectory()、RESTOREALL()、PURGEALL()などの一括操作が可能になりますが、削除に関連するすべての操作でフィルタ引数を受け入れることになります。
DBMS_DBFS_CONTENTメソッドの詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
既存のパス・アイテムは、単純なGETXXX()メソッドおよびPUTXXX()メソッドにより、問合せまたは更新用にアクセスして変更が可能です。
すべてのパス名で、メタデータの読取りおよび変更が可能です。コールが完了したら、クライアントは特定のプロパティがprop_flagsでフェッチされるようリクエストできます。
ファイル・パス名では、データの読取りおよび変更が可能です。コールが完了したら、クライアントは、prop_flags内のprop_dataビット・マスクを使用して、データ・アクセスの続行に使用できる新しいBLOBロケータをリクエストできます。
また、BLOBロケータを使用せずに、明示的に論理オフセット、バッファ量および適切にサイズ設定されたバッファを指定することで、ファイルを読取りおよび書込みすることも可能です。
更新アクセスでは、forUpdateフラグを指定する必要があります。リンク・パス名へのアクセスは、derefフラグが指定されている場合、暗黙的および内部的にストアによる参照を解除できます(機能サポート対象)。シンボリック・リンクを解決できるとはかぎらないため、この操作は推奨されません。
forUpdateがfalseに設定された読取りメソッドGETPATH()では、有効なasofタイムスタンプ・パラメータを受け入れます。このパラメータをストアで使用して、フラッシュバック・スタイル問合せを実装できます。
GETPATH()およびPUTPATH()メソッドのバージョンの変異では、操作のasofモードはサポートされません。
DBFSコンテンツAPIでは、GETPATH()の後にCREATEXXX()を組み合せ、コールを介した適切なデータまたはメタデータの転送によりコピーを簡単に実装できるため、明示的なCOPY()操作はありません。これにより、ストア間でのコピーが可能ですが、内部化されたコピー操作ではこの機能は提供されません。
DBMS_DBFS_CONTENTメソッドの詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
パス名は、ディレクトリ階層およびマウント・ポイントを超えることはできますが、同一のストア内のみで名前変更または移動が可能です。
前にoldPathを介してアクセス可能だったディレクトリ以外のパス名は、newPathが存在しないと想定して、引き続きnewPathを介してアクセス可能な単一アイテムとして名前変更されます。
newPathが存在し、ディレクトリではない場合、名前変更によって、oldPathの名前が変更される前に、暗黙的に既存のアイテムが削除されます。newPathが存在するディレクトリである場合は、oldPathはターゲット・ディレクトリに移動されます。
前にoldPathを介してアクセス可能だったディレクトリ・パス名は、ディレクトリとそのすべての子をnewPathに移動(存在しない場合)することで、またはnewPathの子として移動(存在する場合)することで、名前が変更されます。
存在しないか存在するか、ディレクトリ・ターゲットでないかディレクトリ・ターゲットであるかに関する名前変更と移動操作のセマンティクスは複雑なため、クライアントは、より単純な移動やコピーのシーケンスとして、複雑な名前変更および移動操作を実装することを選択できます。
DBMS_DBFS_CONTENT.RENAMEPATH()メソッドの詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
list_item_tは(パス名、コンポーネント名、タイプ)のタプルで、ディレクトリ・リスト内の単一の要素を表します。
path_item_tは、コンテンツ・ストア内の(ストア、マウント)修飾パスを説明するタプルで、すべての標準およびオプション・プロパティがこれに関連付けられます。
prop_item_tは、コンテンツ・ストア内の(ストア、マウント)修飾パスを説明するタプルで、すべてのユーザー定義プロパティがこれに関連付けられ、個別の(名前、値、タイプ)のタプルに拡張されます。
データ構造の詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
DBFSコンテンツAPIのクライアントでは、ディレクトリ・パス名をリストまたは検索可能できます。またオプションで、サブディレクトリへの再帰、ソフト削除されたアイテムの表示、指定されたタイムスタンプのasofフラッシュバックの使用、リストまたは検索述語に基づくストア内のアイテムのフィルタ・インとフィルタ・アウトが可能です。
DBFSコンテンツAPIでは、現在、リスト・アイテムのみが戻されます。クライアントはgetPath()メソッドのいずれかを明示的に使用して、アイテムに関連付けられたプロパティまたはコンテンツに適切にアクセスする必要があります。
DBMS_DBFS_CONTENTメソッドの詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
DBFSコンテンツAPIのクライアントでは、ユーザー・レベルのロックを任意の有効なパス名に適用し(ストア機能のサポート対象)、ロックをユーザー・データに関連付けて、後でこれらのパス名のロックを解除できます。ロックされたアイテムのステータスは、各種オプション・プロパティを介して使用可能です。
ロックおよびロック解除操作を整合性のある方法で実行することは、ストアの責任です(ユーザー定義のロック・チェックをサポートすることが前提)。
DBMS_DBFS_CONTENTメソッドの詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
DBFSコンテンツAPIのすべての操作は、抽象opcodesとして表されます。クライアントでは、これらのopcodesを使用して、直接および明示的にCHECKACCESS()メソッドを呼び出し、特定の操作が特定のパス名に対する指定のプリンシパルによって起動されるかどうかを確認します。
op_acl()は、std_aclプロパティを指定するop_create()コールまたはop_put()コールの際に起動される暗黙的操作です。の操作では、プリンシパルでストア・アイテムのACLを設定または変更可能かどうかがテストされます。
ソフト削除、パージおよびリストア操作はすべてop_delete()で表されます。
名前変更または移動操作のソースおよび宛先となる操作は分離されますが、ストアではこれらのopcodeを自由に統合できます。また、名前の変更を、削除と作成の組合せとして処理することもできます。
op_storeは、その他の操作APIのいずれにもあてはまらない様々なストア操作のcatch-allカテゴリです。
DBMS_DBFS_CONTENT定数-操作コードの詳細は、「DBFSコンテンツAPIのアクセス・チェック」および『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
関数CHECKACCESS()は、指定のパス名(path、pathtype、store_name)が、principalによる操作(各種op_xxx opcodeを参照)で操作可能かどうかをチェックします。
これはクライアントにとって便利な関数です。アクセス制御をサポートするストアであっても、これらのチェックが内部的に実行されて、セキュリティが保証されます。
DBMS_DBFS_CONTENTメソッドの詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
関数NORMALIZEPATH()では、次の手順を実行します。
パス名が/で始まる絶対パスであることを確認します。
複数の連続する/を1つの/に縮小します。
末尾の/を外します。
ストア固有の正規化されたパス名を、親パス名と末尾のコンポーネント名の2つのコンポーネントに分割します。
正規化された完全修飾パス名を、ストア名、親パス名、末尾のコンポーネント名の3つのコンポーネントに分割します。
ルート・パス/は特殊です。その親のパス名も/であり、そのコンポーネント名はnullです。完全修飾モードでは、名前に正しいストア名が戻される単一マウントが作成されていないかぎり、ストア名はnullです。
戻り値は、常に完全に正規化されたストア固有のパス名であるか、完全修飾のパス名です。
DBMS_DBFS_CONTENT.RENAMEPATH()メソッドの詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
DBFSコンテンツAPI統計は、永続的な収集および維持にコストがかかります。DBFSでは、メモリー内のバッファ統計が最大flush_timeのセンチ秒、または最大flush_countの操作(先に到達したいずれかの制限)だけサポートされ、その時点でバッファは暗黙的にディスクにフラッシュされます。
クライアントは、flushStatsを使用して明示的にフラッシュを起動することもできます。暗黙的フラッシュは、統計収集が無効の場合にも発生します。
setStatsを使用すると、統計の収集を有効および無効にでき、クライアントはオプションで、時間およびカウント・パラメータにnull以外の値を指定して、フラッシュ設定を制御できます。
DBMS_DBFS_CONTENTメソッドの詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
DBFSコンテンツAPIは汎用トレース機能で、すべてのDBFSコンテンツAPIユーザー(クライアントおよびプロバイダの両方)で使用可能です。DBFSコンテンツAPIディスパッチャ自体で、トレース機能が使用されます。
トレース情報は、トレース・レベル/引数で指定された様々な詳細レベルで、フォアグラウンド・トレース・ファイルに書き込まれます。グローバル・トレース・レベルには、severityおよびdetailの2つのコンポーネントがあります。これらは付加ビット・マスクと考えることができます。
severityでは、他のコンポーネントの低レベルのトレースと比較して、高レベルを分離することが可能で、トレースの量を必要に応じて増やすことができます。個々のレベルに関連付けられたセマンティクスはないため、ユーザーは任意の重大度を選択してトレース・レベルを設定できますが、一般的には、高レベルのAPI入出力トレースでは重大度1を使用し、内部操作では重大度2を、非常に低レベルのトレースでは重大度3以上を使用します。
detailにより、それぞれのトレース・レコードとともにトレースでレポートされるタイムスタンプ、ショートスタックなどの追加情報の量が制御されます。例7-1は、DBFSコンテンツAPIを使用してトレースを有効にする方法を示しています。
例7-1 DBFSコンテンツのトレース
function getTrace
return integer;
procedure setTrace(
trclvl in integer);
function traceEnabled(
sev in integer)
return integer;
procedure trace(
sev in integer,
msg0 in varchar2,
msg1 in varchar default '',
msg2 in varchar default '',
msg3 in varchar default '',
msg4 in varchar default '',
msg5 in varchar default '',
msg6 in varchar default '',
msg7 in varchar default '',
msg8 in varchar default '',
msg9 in varchar default '',
msg10 in varchar default '');
DBMS_DBFS_CONTENTメソッドの詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
