DBFSコンテンツAPI

23.1 DBFSコンテンツAPIの概要

クライアント側のプログラムによるAPIパッケージであるDBFSコンテンツAPI (DBMS_DBFS_CONTENT)を使用して、アプリケーションによるDBFSの使用を可能にすることができます。

アプリケーションは、SQL、PL/SQL、JDBC、OCIおよび他のプログラミング環境で作成できます。

DBFSコンテンツAPIは、ファイルシステムに類似した抽象化を提供するメソッドの集合です。これは、1つ以上のDBFSストア・プロバイダによって支えられます。DBFSコンテンツ・インタフェースのコンテンツは、メタデータを含むファイルを指し、表のSecureFiles LOB (およびその他の列)にマップしたり、データベース内部で実行されるJavaまたはPL/SQLにあるユーザー記述のプラグインによって動的に作成することができます。プラグインの形式はプロバイダと呼ばれます。

ノート:

DBFSコンテンツAPIには、SecureFilesストア・プロバイダDBMS_DBFS_SFSが含まれます。これは、スキーマ内の列としてLOBをすでに使用しているアプリケーションがLOB列にファイルとしてアクセスできるようにするためのデフォルトの実装です。

関連項目:

DBFS SecureFilesストア

プロバイダの例を次に示します。

ファイルによってデータを覆うパッケージ・アプリケーション。
カスタム・アプリケーション開発者が、医療イメージを格納するアプリケーションなどのファイルシステム・インタフェースを活用するために使用します。

23.2 ストアおよびDBFSコンテンツAPI

DBFSコンテンツAPIは、様々なストアに共通の機能を取り出し、ポータブル・クライアント・アプリケーションを作成するために使用できる簡単なインタフェースとしてこれらを構成すると同時に、各種ストアが選択する機能セットを実装できるようにします。

DBFSコンテンツAPIは、曖昧さをなくすためにパス名の最初のコンポーネントを使用して1つ以上のストアのパス・ネームスペースを単一のネームスペースに統合し、このネームスペースをクライアント・アプリケーションに示します。これによりクライアントは、単一の文字列として表される完全絶対パス名を次の形式で使用することにより、基礎となるドキュメントにアクセスします。

/store-name/store-specific-path-name

または、次の形式で、ストア修飾されたパス名を文字列2タプルとして使用します。

["store-name","/store-specific-path-name"]

次に、DBFSコンテンツAPIは、パス名に対する各種操作を適切なストアに正しくディスパッチし、結果をクライアントで必要なネームスペースに統合します。

ストア・プロバイダは、パッケージDBMS_DBFS_CONTENT_SPIによる宣言のとおり、ストア・プロバイダ・インタフェース(SPI)に準拠する必要があります。

独自のDBFSストアの作成
DBMS_DBFS_CONTENTパッケージ構文参照の詳細は、Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンスを参照してください

23.3 DBMS_DBFS_CONTENTパッケージの開始

DBMS_DBFS_CONTENTは、Oracle Database 11gリリース2以降に付属しており、インストールは必要ありません。

23.3.1 DBFSコンテンツAPIのロール

コンテンツの操作および管理API (パッケージ、タイプ、表など)には、DBFS_ROLEを使用してアクセスできます。

DBFS_ROLEは、必要に応じてすべてのユーザーに付与できます。

23.3.2 パス名の定数およびタイプ

パス名の定数は、SecureFiles LOBストアの一方に基づいて作成されます。

関連項目:

パス名の定数およびそのタイプの詳細は、Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンスを参照してください

23.3.3 パス・プロパティ

ストアにあるすべてのパス名はプロパティのセットと関連付けられています。

簡易性と汎用性のために、各プロパティは文字列名で識別され、文字列値(未設定または特定のストア実装で未定義もしくは非サポートの場合はnullの可能性あり)および値タイプコード(値文字列で保持される実際の値のタイプに対する数値判別)を持ちます。

プロパティの値を文字列に強制することは、様々なインタフェースを一様かつコンパクトにするというメリットがあります(また、基礎となるストアの実装を簡単にすることもできます)が、文字列への変換および文字列からの変換で情報が失われる可能性があります。

クライアントおよびストアは、これらの変換に明確に定義されたデータベース表記規則を使用し、必要に応じてtypecodeフィールドを使用することが前提です。

PL/SQLタイプpath_tおよびname_tは、パス名およびコンポーネント名を表す文字列のポータブルな別名です。

typecodeは、文字列が強制されたプロパティ値の真のタイプを表す数値です。単純なスカラー・タイプ(数字、日付、タイムスタンプなど)がクライアントにより依存でき、ストアによって実装される必要があります。

標準RDBMSのtypecodeは正の整数であるため、DBMS_DBFS_CONTENTインタフェースでは、負の整数が負のtypecodeによるクライアント定義のタイプを表すことができます。これらのtypecodeは標準のtypecodeとは競合せず、永続的に保持され、必要に応じてクライアントに戻されますが、DBFSコンテンツAPIや特定のストアによる解釈は必要ありません。ポータブル・クライアント・アプリケーションでは、特定のストアに情報を渡す裏口としてユーザー定義のtypecodeを使用することはできません。

関連項目:

DBMS_DBFS_CONTENT定数およびプロパティとDBMS_DBFS_CONTENT_PROPERTY_Tパッケージの詳細は、Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンスを参照してください

23.3.4 コンテンツID

コンテンツIDは、ストア内のパスを表す一意の識別子です。

関連項目:

DBMS_DBFS_CONTENTコンテンツIDの定数およびプロパティの詳細は、Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンスを参照してください

23.3.5 パス名タイプ

ストアでは、4つのタイプのエンティティへのアクセスを格納および提供します。

4つのタイプのエンティティとは、type_file、type_directory、type_directoryおよびtype_referenceです。

すべてのストアで、すべてのディレクトリ、リンクまたは参照を実装する必要はありません。

関連項目:

DBMS_DBFS_CONTENT定数およびパス名タイプの詳細は、Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンスを参照してください

23.3.6 ストア機能

共通のプログラム・インタフェースを、可能なかぎり多くの異なるタイプのストアに提供するために、DBFSコンテンツAPIでは、個別のストア・プロバイダが各種操作の動作の一部を定義および実装できます。

DBFSコンテンツAPIは、異なるストア・プロバイダ(および異なるストア)が自らを機能セットとして記述することを可能にすることにより、豊富な機能を維持するとともに、ポータブル・アプリケーションをサポートします。機能セットは、サポートする機能およびサポートしない機能を示すビット・マスクです。追加のロジックをクライアント側に実装し、複雑な操作をサポート可能なストアに委ねることで、特定のストアの機能の不足を補正するクライアント・アプリケーションにとって、この使用は可能ではあっても容易ではありません。

関連項目:

ストア機能および定数の詳細は、Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンスを参照してください

23.3.7 ロック・タイプ

ロックをサポートするストアでは、3タイプのロックを実装する必要があります。

3タイプのロックとは、lock_read_only、lock_write_only、lock_read_writeです。

ユーザー・ロック(これらのタイプの1つ)は、ユーザー指定のlock_dataに関連付けが可能です。ストアはデータを解釈しませんが、クライアント・アプリケーションはこれを独自の目的のために使用できます(たとえば、ロックがかけられた時刻をユーザー・データが示す場合、クライアント・アプリケーションは後でこのデータを使用してそのアクションを制御できます)。

単純なロック・モデルでは、lock_read_onlyにより、パス名に対するすべての明示的な変更ができなく(ただし暗黙的変更および親/子パス名の変更は可能)なります。lock_write_onlyにより、パス名に対するすべての明示的な読取りができなくなりますが、暗黙的読取りおよび親/子パス名の読取りは可能になります。lock_read_writeでは、両方が可能です。

すべてのロックは、ロック操作を実行するプリンシパルに関連付けられます。ロックをサポートするストアではこの情報を保持し、読取り/書込みロック・チェックの実行に使用する必要があります(opt_lockerを参照)。

関連項目:

ロック・タイプおよび定数の詳細は、Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンスを参照してください

23.3.8 標準プロパティ

標準プロパティは、すべてのストアが(DBFSコンテンツAPIに説明されている方法で)サポートする必要のあるすべてのコンテンツ・パス名と関連付けられている、明確に定義された必須プロパティです。固定スキーマのある表に対して作成されたストアでは、これらのプロパティの必要なだけ多くに対して適切なデフォルトを選択することなどが可能です。

すべての標準プロパティでは、非公式に、std:ネームスペースが使用されます。クライアントおよびストアで、将来競合が発生するのを阻止するために、独自のプロパティの定義にこのネームスペースを使用することは避ける必要があります。

関連項目:

標準プロパティおよび定数の詳細は、Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンスを参照してください

23.3.9 オプション・プロパティ

オプション・プロパティは、正しく定義されているが、すべてのストアで自由に(しかしDBFSコンテンツAPIで記述されている方法でのみ)サポートされるすべてのコンテンツ・パス名に関連付けられた必須ではないプロパティです。

オプション・プロパティをまったくサポートしないストアに対応できるように、クライアントを準備する必要があります。

すべてのオプション・プロパティでは、非公式に、opt:ネームスペースが使用されます。クライアントおよびストアで、将来競合が発生するのを阻止するために、独自のプロパティの定義にこのネームスペースを使用することは避ける必要があります。

関連項目:

オプション・プロパティおよび定数の詳細は、Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンスを参照してください

23.3.10 ユーザー定義プロパティ

アプリケーションで使用するために独自のプロパティを定義できます。

ネームスペースの接頭辞が互いに、またはDBFSの標準またはオプション・プロパティと競合しないようにしてください。

23.3.11 プロパティ・アクセス・フラグ

プロパティを取得および設定するDBFSコンテンツAPIメソッドでは、プロパティ・アクセス・フラグを組み合せて使用して、単一APIコール内の異なるネームスペースからプロパティをフェッチできます。

関連項目:

プロパティ・アクセス・フラグおよび定数の詳細は、Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンスを参照してください

23.3.12 例外

DBFSコンテンツAPI操作では、いずれかのトップレベルの例外が発生します。

クライアントでは、基礎となるエラー・シグナリング・コードの特定のストア実装を気にすることなく、エラー・ハンドラでこれらの特定の例外に対するプログラミングが可能です。

ストア・サービス・プロバイダは、必要に応じて内部例外を例外タイプのいずれかにトラップおよびラップすることを試行する必要があります。

関連項目:

例外の詳細は、Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンスを参照してください

23.3.13 プロパティ・バンドル

プロパティ・バンドルは、property_tレコード・タイプおよびproperties_tと呼ばれます。

property_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間の変換に便利なユーティリティ・ファンクションが提供されます。

ファンクションDBMS_DBFS_CONTENT.PROPERTIEST2HはDBMS_DBFS_CONTENT_PROPERTIES_T値を同等のproperties_t値に変換し、ファンクションDBMS_DBFS_CONTENT.PROPERTIESH2Tはproperties_t値を同等のDBMS_DBFS_CONTENT_PROPERTIES_T値に変換します。

関連項目:

PROPERTY_Tレコード・タイプの詳細は、Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンスを参照してください

23.3.14 ストア記述子

ストア記述子は、store_tおよびmount_tレコードとして扱われます。

store_tは、DBFSコンテンツAPIに登録されて管理されるストアを記述するレコードです。
mount_tは、ストア・マウント・ポイントおよびそのプロパティを説明するレコードです。

クライアントは、使用可能なストアのリストをDBFSコンテンツAPIに問合せ、指定のパス名へのアクセスを処理するストアを判別し、ストアの機能セットを判別できます。

関連項目:

管理および問合せAPI
STORE_Tレコード・タイプの詳細は、Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンスを参照してください

23.4 管理および問合せAPI

管理クライアントおよびコンテンツ・プロバイダは、コンテンツ・ストアをDBFSコンテンツAPIに登録する必要があります。また、管理クライアントは、選択したトップレベルのネームスペースにストアをマウントする必要があります。

同じストアを複数回、別々のマウント・ポイントにマウントすることが可能であるため(これはクライアント制御下で行われる)、ストアの登録および登録解除は、ストアのマウントおよびアンマウントとは分離されます。

関連項目:

DBMS_DBFS_CONTENTパッケージ・メソッドの概要は、Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンスを参照してください

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

23.4.1 コンテンツ・ストアの登録

ストア・サービス・プロバイダとしてprovider_packageプロシージャを使用するプロバイダによって支えられた新しいストアを登録できます。登録の方法は、DBMS_DBFS_CONTENT_SPIパッケージ・シグネチャに準拠しています。

REGISTERSTORE()プロシージャを使用します。

このメソッドは、新規ストアの作成後にサービス・プロバイダで使用されるように設計されています。ストア名は、一意にする必要があります。

関連項目:

REGISTERSTORE()メソッドの詳細は、Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンスを参照してください

23.4.2 コンテンツ・ストアの登録解除

以前に登録したストアの登録を解除できます。これにより、このストアに関連付けられているすべてのマウント・ポイントが無効になります。ストアの登録を解除すると、ストア(およびそのマウント・ポイント)へのすべてのアクセスの動作は保証されなくなります(読取り一貫性により一時的にアクセスが継続する場合があります)。

UNREGISTERSTORE()プロシージャを使用します。

ignore_unknown引数がtrueの場合、不明なストアを登録解除しようとしても例外は発生しません。

関連項目:

UNREGISTERSTOREメソッドの詳細は、Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンスを参照してください

23.4.3 登録されたストアのマウント

登録済ストアをマウントし、マウント・ポイントにバインドできます。

MOUNTSTORE()プロシージャを使用します。

ストアをマウントした後、/store_mount/xyzの形式のパス名へのアクセスは、store_nameおよびそのコンテンツ・プロバイダにリダイレクトされます。

ストア・マウント・ポイントは一意であり、構文的に有効なパス名コンポーネントである必要があります(つまり/が埋め込まれていないname_t)。

マウント・ポイントを指定しないため、マウント・ポイントがnullである場合、DBFSコンテンツAPIでは、ストア名自体をマウント・ポイント名として使用します(一意性および構文的な制約の対象)。

空の特別なマウント・ポイントは単一ストアで使用可能です。つまり、DBFSコンテンツAPIが単一バックエンド・ストアを管理するシナリオです。そのような場合、これらのアクセスのリダイレクト方法は明確であるため、クライアントは/xyzの形式の完全パス名を直接処理できます。

同一のストアを別々のマウント・ポイントで複数回マウントできます。

マウント・プロパティを使用して、DBFSコンテンツAPI実行環境、つまり特定のマウント・ポイントのプリンシパル、所有者、ACLおよびasofのデフォルト値を指定できます。また、マウント・プロパティを使用して、読取り専用ストアも指定できます。

関連項目:

MOUNTSTORE()メソッドの詳細は、Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンスを参照してください

23.4.4 以前にマウントされたストアのアンマウント

名前またはマウント・ポイントのいずれかで以前にマウントされたストアをアンマウントできます。単一のストアは、マウント・ポイントがないため、ストア名によってのみアンマウントできます。名前によりストアをアンマウントしようとすると、そのストアに関連付けられているすべてのマウント・ポイントがアンマウントされます。

UNMOUNTSTORE()プロシージャを使用します。

アンマウントすると、ストア(またはマウント・ポイント)へのアクセスの動作は保証されなくなります(読取り一貫性により一時的にアクセスが継続する場合があります)。ignore_unknown引数がtrueの場合、不明なストア/マウントを登録解除しても例外は発生しません。

関連項目:

UNMOUNTSTOREメソッドの詳細は、Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンスを参照してください

23.4.5 使用可能なすべてのストアおよびその機能のリスト

使用可能なストアをすべてリストできます。マウント・ポイントがストア自体から分離されているため、戻されたレコードのstore_mountフィールドは、nullに設定されます。

LISTSTORES()ファンクションを使用します。

関連項目:

LISTSTORES関数の詳細は、Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンスを参照してください

23.4.6 使用可能なすべてのマウント・ポイントのリスト

すべての使用可能なマウント・ポイント、それを支えるデータストアおよびストア機能をリストできます。単一マウントの結果、store_mountフィールドがnullに設定された単一行が戻されます。

LISTMOUNTS()ファンクションを使用します。

関連項目:

LISTMOUNTS()メソッドの詳細は、Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンスを参照してください

23.4.7 固有のストアおよびその機能の検索

ストアのパス名、ストア名またはマウント・ポイントを検索できます。

GETSTOREBYXXX()またはGETFEATUREBYXXX()ファンクションを使用します。

関連項目:

DBMS_DBFS_CONTENTメソッドの詳細は、Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンスを参照してください

23.5 DBFSコンテンツAPIの領域使用量の問合せ

ファイル・システム領域使用統計情報を問い合せることができます。

プロバイダは、ストアに対して次のメソッドをサポートし、特にストアが複数の表、索引、LOBなどで構成される場合は、領域使用量をできるかぎり特定する必要があります。

SPACEUSAGE()メソッドの使用

説明:

blksizeは、ストアを保持する通常の表領域ブロック・サイズであり、ブロック・サイズが異なる複数の表領域が使用されている場合、任意の有効なブロック・サイズが許容されます。
tbytesは、ストアの合計サイズ(バイト単位)であり、fbytesはストアの空き/未使用サイズ(バイト単位)です。これらの値は、ストアを構成するすべてのセグメントから計算されます。
nfile、ndir、nlinkおよびnrefにより、ストア内で現在使用可能なファイル、ディレクトリ、リンクおよび参照の数がカウントされます。

データベース・オブジェクトは動的に増加するため、空き領域と使用済領域の区分を測定するのは容易ではありません。

トップレベルのルート・ディレクトリで領域使用量を問い合せると、その下にある使用可能なすべての個別のストアの領域使用量を合計したサマリーが戻されます。同じストアが複数回マウントされていても、1回としてカウントされます。

関連項目:

SPACEUSAGE()メソッドの詳細は、Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンスを参照してください

23.6 DBFSコンテンツAPIのセッション・デフォルト

DBFSコンテンツAPIへの通常のクライアント・アクセスは、特定のオブジェクトで構成される暗黙的コンテキストで実行されます。

現在の操作を呼び出すprincipal。
現在の操作により(暗黙的または明示的に)作成されたすべての新規要素のowner。
現在の操作により(暗黙的または明示的に)作成されたすべての新規要素のACL。
基礎となる読取り専用操作(またはその読取り専用サブコンポーネント)が実行された時点のASOFタイムスタンプ。

このすべての情報は、引数によって各種のDBFSコンテンツAPIメソッド・コールに明示的に渡され、クライアントによって個別の操作のファイングレイン制御が可能になります。

また、DBFSコンテンツAPIによりクライアントは、デフォルトが明示的にオーバーライドされないすべての操作で自動的に継承されるコンテキストで、セッション期間のデフォルトを設定できます。

コンテキストのすべてのデフォルトはnullとして開始され、これらをnullに設定することでクリアできます。

関連項目:

DBMS_DBFS_CONTENTメソッドの詳細は、Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンスを参照してください

23.7 DBFSコンテンツAPIのインタフェース・バージョニング

DBFSコンテンツAPI自体の進化を可能にするために、パブリックAPIが変更されるたびに内部的な数値APIバージョンが大きくなります。

関連項目:

GETVERSION()メソッドの詳細は、Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンスを参照してください

23.8 DBFSコンテンツAPIのパス名のノート

DBFSコンテンツAPIのクライアントでは、絶対パス名を介してストア・アイテムが参照されます。

絶対パス名は次のようにすることができます。

完全修飾(/mount_point/pathname形式の単一の文字列)
ストア修飾(store_name、pathname)、この形式ではパス名はストアのネームスペースをルートとします

クライアントはネーミング・スキームのいずれかを使用し、プログラム内では両方のネーミング・メソッドを使用できます。

DBFSコンテンツAPIコールによってパス名が戻されると、戻される正確な値は、クライアントがコールで使用するネーミング・スキームに依存します。たとえば、完全修飾ディレクトリ名に対するリストまたは検索の場合、完全修飾パス名でアイテムが戻され、ストア修飾ディレクトリ名のリストまたは検索の場合は、ストア固有の(つまりストア修飾を意味する)パス名でアイテムが戻されます。

DBFSコンテンツAPIの実装では、これらの2つのネーミング・スキームの間の正規化および内部変換が内部的に管理されます。

23.9 DBFSコンテンツAPIの作成操作

プロバイダSPIは、クライアントがDBFSコンテンツAPIを起動したときにディレクトリ、ファイル、リンクおよび参照要素(ストア機能のサポート対象)をSPIが作成できるように実装する必要があります。

すべての作成メソッドでは、有効なパス名が必要であり、パス名が作成されるときにプロパティがパス名と関連付けられるようオプションとして指定できます。std_creation_timeなど、自動的に生成されたプロパティがただちにクライアントに使用可能になるように、作成完了後にクライアントが項目のプロパティをフェッチ・バックすることも可能です。フェッチ・バックされる正確なプロパティのセットは、prop_flagsにある様々なprop_xxxビット・マスクによって制御されます。

リンクおよび参照には、プライマリ・パス名に関連付けられた追加パス名が必要です。ファイル・パス名では、オプションでBLOB値を指定して、基礎となるファイルのコンテンツを最初に移入できます(指定されるBLOBは、一時LOBまたは永続LOBの任意の有効なLOBです)。prop_flagsでprop_dataが指定されている場合は、作成時に基礎となるLOBがクライアントに戻されます。

ディレクトリ以外のパス名では、親ディレクトリを最初に作成する必要があります。ディレクトリ・パス名自体を再帰的に作成できます。つまり、ディレクトリまでつながるパス名階層を1回のコールで作成できます。

存在するパスの作成を試行するとエラーが発生します。例外はソフト削除されたパス名です。この場合、ソフト削除されたアイテムは暗黙的にパージされ、新しいアイテムの作成が試行されます。

コンテンツIDベースのアクセスをサポートするストアおよびそのプロバイダは、明示的なストア名およびNULLパスを受け入れて新しいコンテンツ要素を作成します。この要素用に生成されるコンテンツIDは、OPT_CONTENT_IDプロパティを介して使用できます。prop_flagsパラメータのPROP_OPTプロパティは、自動的にコンテンツIDベースの作成の意味になります。

FEATURE_LAZY_PATHプロパティがサポートされていない場合、新しく作成された要素には内部生成されたパス名が存在することもあり、このパスはSTD_CANONICAL_PATHプロパティを介して使用できます。

ファイル要素のみがコンテンツIDベースのアクセスの候補です。

関連項目:

DBMS_DBFS_CONTENT()メソッド、DBMS_DBFS_CONTENT()の定数のオプションのプロパティ、およびDBMS_DBFS_CONTENTの定数-標準プロパティの詳細は、Oracle Database PL/SQLパッケージおよびタイプ・リファレンスを参照してください

23.10 DBFSコンテンツAPIの削除操作

プロバイダSPIは、クライアントがDBFSコンテンツAPIを起動したときにディレクトリ、ファイル、リンクおよび参照要素(ストア機能のサポート対象)をSPIが削除できるように実装する必要があります。

デフォルトでは、削除は永続的で、トランザクション・コミットで正常に削除されたアイテムを削除します。ただし、リポジトリではソフト削除の機能もサポートされます。クライアントのリクエストがあれば、ソフト削除されたアイテムはストアで保持されます。ただし、通常のリストや検索では表示されません。ソフト削除されたアイテムは、リストアまたは明示的なパージが可能です。

ディレクトリ・パス名は再帰的に削除できます(つまり、ディレクトリの下のパス名階層を1回のコールで削除できます)。再帰的でない削除は、空のディレクトリでのみ実行できます。再帰的なソフト削除では、削除されるすべてのアイテムにソフト削除が適用されます。

個別のパス名(またはディレクトリ下のソフト削除されたすべてのパス名)は、RESTOREXXX()メソッドおよびPURGEXXX()メソッドを使用してリストアまたはパージできます。

フィルタリングをサポートするプロバイダでは、プロバイダ・フィルタを使用して削除するアイテムのサブセットを識別できます。これにより、deleteDirectory()、RESTOREALL()、PURGEALL()などの一括操作が可能になりますが、削除に関連するすべての操作でフィルタ引数を受け入れることになります。

コンテンツIDベースのアクセスをサポートするストアおよびそのプロバイダは、コンテンツIDを指定することによりファイル項目の削除も許可します。

関連項目:

DBMS_DBFS_CONTENT()メソッドの詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください

23.11 DBFSコンテンツAPIパスのgetおよびput操作

簡単な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パッケージ・プロシージャおよびタイプ・リファレンスを参照してください

23.12 DBFSコンテンツAPIの名前変更および移動操作

パス名は、ディレクトリ階層およびマウント・ポイントを超えて名前変更または移動が可能ですが、同一のストア内のみで行うことができます。

前にoldPathを介してアクセス可能だったディレクトリ以外のパス名は、newPathが存在しないと想定して、引き続きnewPathを介してアクセス可能な単一アイテムとして名前変更できます。

newPathが存在し、ディレクトリではない場合、名前変更によって、oldPathの名前が変更される前に、暗黙的に既存のアイテムが削除されます。newPathが存在しディレクトリである場合は、oldPathはターゲット・ディレクトリに移動されます。

前にoldPathを介してアクセス可能だったディレクトリ・パス名は、ディレクトリとそのすべての子をnewPathに移動(存在しない場合)することで、またはnewPathの子として移動(存在する場合)することで、名前を変更できます。

存在しないか存在するか、ディレクトリ・ターゲットでないかディレクトリ・ターゲットであるかに関する名前変更と移動操作のセマンティクスは複雑なため、クライアントは、より単純な移動やコピーのシーケンスとして、複雑な名前変更および移動操作を実装することを選択できます。

コンテンツIDベースのアクセスおよびレイジー・パス名バインドをサポートするストアおよびそのプロバイダは、既存のコンテンツIDを新しいパスと関連付けるOracle Database PL/SQLパッケージおよびタイプ・リファレンスのSETPATHプロシージャもサポートします。

関連項目:

DBMS_DBFS_CONTENT.RENAMEPATH()メソッドの詳細は、Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンスを参照してください

23.13 ディレクトリ・リスト

ディレクトリのリストは複数の異なる方法で処理されます。

list_item_tはパス名、コンポーネント名、タイプのタプルで、ディレクトリ・リスト内の単一の要素を表します。
path_item_tは、コンテンツ・ストア内の(ストア、マウント)修飾パスを説明するタプルで、すべての標準およびオプション・プロパティがこれに関連付けられます。
prop_item_tは、コンテンツ・ストア内のストア、マウント修飾パスを説明するタプルで、すべてのユーザー定義プロパティがこれに関連付けられ、個別の名前、値、タイプのタプルに拡張されます。

関連項目:

データ構造の詳細は、Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンスを参照してください

23.14 DBFSコンテンツAPIのディレクトリ・ナビゲーションおよび検索

DBFSコンテンツAPIのクライアントでは、次のオプション・モードを使用してディレクトリ・パス名のコンテンツをリストまたは検索できます。

オプションのモード:

サブディレクトリ内を再帰的検索
ソフト削除されたアイテムの表示
指定されたタイムスタンプのフラッシュバックasofの使用
リストまたは検索述語に基づくストア内のアイテムのフィルタ・インとフィルタ・アウト。

DBFSコンテンツAPIでは、現在、リスト・アイテムのみが戻されます。クライアントはgetPath()メソッドのいずれかを明示的に使用して、アイテムに関連付けられたプロパティまたはコンテンツに適切にアクセスします。

関連項目:

DBMS_DBFS_CONTENTメソッドの詳細は、Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンスを参照してください

23.15 DBFSコンテンツAPIのロック操作

DBFSコンテンツAPIクライアントは、特定の基準に応じてユーザー・レベルのリンクを適用できます。

DBFSコンテンツAPIのクライアントでは、ユーザー・レベルのロックを任意の有効なパス名に適用し(ストア機能のサポート対象)、ロックをユーザー・データに関連付けて、後でこれらのパス名のロックを解除できます。ロックされたアイテムのステータスは、各種オプション・プロパティを介して使用可能です。

ストアがユーザー定義のロック・チェックをサポートしている場合、ロックおよびロック解除操作を整合性のある方法で実行することは、ストアの責任です。

関連項目:

DBMS_DBFS_CONTENTメソッドの詳細は、Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンスを参照してください

23.16 DBFSコンテンツAPIのアクセス・チェック

DBFSコンテンツAPIは、操作による特定のパス名へのアクセスをチェックします。

ファンクションCHECKACCESS()は、「DBFSコンテンツAPIのロック操作」で説明するように、指定のパス名(path、pathtype、store_name)が、principalによる操作(各種op_xxx opcodeなど)で操作可能かどうかをチェックします

これはクライアントにとって便利な関数です。アクセス制御をサポートするストアであっても、これらのチェックが内部的に実行されて、セキュリティが保証されます。

関連項目:

DBMS_DBFS_CONTENTメソッドの詳細は、Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンスを参照してください

23.17 DBFSコンテンツAPIの抽象化操作

DBFSコンテンツAPIのすべての操作は、抽象opcodesとして表されます。

クライアントでは、opcodesを使用して、直接および明示的にCHECKACCESS()メソッドを呼び出し、特定の操作を特定のパス名に対する指定のプリンシパルによって起動できるかどうかを確認します。

op_acl()は、std_aclプロパティを指定するop_create()コールまたはop_put()コールの際に起動される暗黙的操作です。の操作では、プリンシパルでストア・アイテムのACLを設定または変更可能かどうかがテストされます。

ソフト削除、パージおよびリストア操作はop_delete()で表されます。

名前変更または移動操作のソースおよび宛先となる操作は分離されますが、ストアではこれらのopcodeを自由に統合できます。また、名前の変更を、削除と作成の組合せとして処理することもできます。

op_storeは、その他の操作APIのいずれにもあてはまらない様々なストア操作のcatch-allカテゴリです。

関連項目:

DBFSコンテンツAPIのアクセス・チェック
DBMS_DBFS_CONTENTの定数-操作コードの詳細は、Oracle Database PL/SQLパッケージおよびタイプ・リファレンスを参照してください。

23.18 DBFSコンテンツAPIのパスの正規化

APIのパスの正規化を実行するためのプロセスが用意されています。

関数NORMALIZEPATH()では、次のステップを実行します。

パス名が/で始まる絶対パスであることを確認します。
複数の連続する/を1つの/に縮小します。
末尾の/を外します。
ストア固有の正規化されたパス名を、親パス名と末尾のコンポーネント名の2つのコンポーネントに分割します。
正規化された完全修飾パス名を、ストア名、親パス名、末尾のコンポーネント名の3つのコンポーネントに分割します。

ルート・パス/は特殊です。その親のパス名も/であり、そのコンポーネント名はnullです。完全修飾モードでは、名前に正しいストア名が戻される単一マウントが作成されていないかぎり、ストア名はnullです。

戻り値は、常に完全に正規化されたストア固有のパス名であるか、完全修飾のパス名です。

関連項目:

DBMS_DBFS_CONTENT.RENAMEPATH()メソッドの詳細は、Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンスを参照してください

23.19 DBFSコンテンツAPIの統計サポート

DBFSは、DBFSコンテンツAPIの統計の収集にかかるコストの削減をサポートします。

DBFSコンテンツAPI統計は、永続的な収集および維持にコストがかかります。DBFSでは、メモリー内のバッファ統計が最大flush_timeのセンチ秒、または最大flush_countの操作(先に到達したいずれかの制限)だけサポートされ、その時点でバッファは暗黙的にディスクにフラッシュされます。

クライアントは、flushStatsを使用して明示的にフラッシュを起動することもできます。暗黙的フラッシュは、統計収集が無効の場合にも発生します。

setStatsを使用すると、統計の収集を有効および無効にでき、クライアントはオプションで、時間およびカウント・パラメータにnull以外の値を指定して、フラッシュ設定を制御できます。

関連項目:

DBMS_DBFS_CONTENTメソッドの詳細は、Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンスを参照してください

23.20 DBFSコンテンツAPIのトレース・サポート

任意のDBFSコンテンツAPIユーザー(クライアントおよびプロバイダの両方)が、汎用トレース機能であるDBFSコンテンツAPIトレースを使用できます。

DBFSコンテンツAPIディスパッチャ自体で、トレース機能が使用されます。

トレース情報は、トレース・レベル/引数で指定された様々な詳細レベルで、フォアグラウンド・トレース・ファイルに書き込まれます。グローバル・トレース・レベルには、severityおよびdetailの2つのコンポーネントがあります。これらは付加ビット・マスクと考えることができます。

severityコンポーネントでは、他のコンポーネントの低レベルのトレースと比較して、高レベルを分離することが可能で、トレースの量を必要に応じて増やすことができます。個々のレベルに関連付けられたセマンティクスはないため、ユーザーは任意の重大度を選択してトレース・レベルを設定できますが、一般的には、高レベルのAPI入出力トレースでは重大度1を使用し、内部操作では重大度2を、非常に低レベルのトレースでは重大度3以上を使用します。

detailコンポーネントにより、それぞれのトレース・レコードとともにトレースでレポートされるタイムスタンプ、ショートスタックなどの追加情報の量が制御されます。

関連項目:

DBFSコンテンツAPIを使用してトレースを有効にする方法の詳細は、例23-1を参照してください。
DBMS_DBFS_CONTENTメソッドの詳細は、Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンスを参照してください

例23-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 '');

23.21 リソースおよびプロパティ・ビュー

コンテンツAPIの構造およびプロパティの説明は特定のビューに表示できます。

特定のビューで、コンテンツAPIの構造およびプロパティについて説明します。

関連項目:

DBFS_CONTENTビューの詳細は、Oracle Databaseリファレンスを参照してください
DBFS_CONTENT_PROPERTIESビューの詳細は、Oracle Databaseリファレンスを参照してください