プロパティー
プロパティーは、Content Engine オブジェクトが状態を開示したり操作を許可する主要な手段です。プロパティーは特定の Content Engine クラス内で、そのスーパークラスの継承により定義されます。
クラスの詳細については、『クラス (Classes)』を参照してください。
Content Engine プロパティーは、8 つのタイプのデータを保持できます。さらに、プロパティーのカーディナリティーにより、指定したデータ型が単一値を表す (単一値プロパティー) か、指定したデータ型が複数のインスタンスを表す (複数値プロパティー) かが決まります。
プロパティーには、以下の 3 つのタイプのカーディナリティーのいずれかを指定できます。
- SINGLE: 単一の値を返すプロパティー。
- ENUM: 読み取り専用で、データ型が OBJECT である固有のアイテムの列挙コレクションを返すプロパティー。列挙コレクション内のアイテムには順次的にのみアクセス可能であり、コレクション内のアイテムの数、順序、および値は、コレクションへの参照が一定のままである場合でも変更されることがあります。
- LIST: アイテムのリスト・コレクションを返すプロパティー。リスト・コレクションは変更可能 (アイテムの挿入、置換、または削除が可能) な場合も読み取り専用の場合もあります。リスト・コレクション内のアイテムにはランダムな順序でアクセス可能であり、コレクション内のアイテムの数、順序、および値は、コレクションへの参照が維持されている間は一定のままです。データ型が OBJECT 以外である複数値プロパティーは、カーディナリティーが LIST でなければなりません。
プロパティーが保持できるデータ型は以下のとおりです。
- BINARY:
- カーディナリティーが SINGLE であるプロパティーは、バイナリー値向けのバイト (8 ビットの符号なし整数) 配列を返します。
- カーディナリティーが LIST であるプロパティーは、BinaryList オブジェクトを返します。
- BOOLEAN:
- カーディナリティーが SINGLE であるプロパティーは、値 true または false を返します。
- カーディナリティーが LIST であるプロパティーは、BooleanList オブジェクトを返します。
- DATE:
- カーディナリティーが SINGLE であるプロパティーは、Java™ コードでは java.util.Date 値、C# および Visual Basic コードでは DateTime 値を返します。
- カーディナリティーが LIST であるプロパティーは、DateTimeList オブジェクトを返します。
- DOUBLE:
- カーディナリティーが SINGLE であるプロパティーは、64 ビットの浮動小数点値を返します。
- カーディナリティーが LIST であるプロパティーは、Float64List オブジェクトを返します。
- GUID:
- カーディナリティーが SINGLE であるプロパティーは、GUID 文字列値を返します。
- カーディナリティーが LIST であるプロパティーは、IdList オブジェクトを返します。
- LONG:
- カーディナリティーが SINGLE であるプロパティーは、32 ビットの符号付き整数値を返します。
- カーディナリティーが LIST であるプロパティーは、Integer32List オブジェクトを返します。
- OBJECT:
- カーディナリティーが SINGLE であるプロパティーは、EngineObject 値を返します。この値は、EngineObject サブクラスのインスタンスである単一の Content Engine オブジェクトへのアクセスを許可します。
- カーディナリティーが ENUM であるプロパティーは、IndependentObjectSet オブジェクトを返します。このオブジェクトには、IndependentObject オブジェクトのコレクションが含まれます。
- カーディナリティーが LIST であるプロパティーは、DependentObjectList オブジェクトを返します。このオブジェクトには、DependentObject オブジェクトのコレクションが含まれます。
- STRING:
- 単一値プロパティーは、16 ビットの Unicode 文字のシーケンスを返します。
- カーディナリティーが LIST であるプロパティーは、StringList オブジェクトを返します。
プロパティーは 1 つ以上の GUID で識別されます。最初の識別子は、ユーザーがプロパティーを作成するときにサーバーから自動的に割り当てられます。別名 ID という追加の識別子をプロパティーに割り当てて、複数のオブジェクト・ストアから検索できるようにすることができます。
Java アプリケーションでは、オブジェクト値を適切な getter メソッドから読み取り、適切な setter メソッドで設定することができます (プロパティーに読み取り/書き込みアクセス権がある場合)。C# または Visual Basic アプリケーションでは、ドット表記を使用してオブジェクト・プロパティーを読み取ったり設定したりできます。
プロパティー・メタデータ
メタデータとは、他のデータに関する情報を表すデータのことです。Content Engine ではクラスとプロパティーのメタデータのセットを 2 つ別々に管理しているため、クライアント・アプリケーションはオブジェクトの状態の一貫性を保ちながらクラスとプロパティーのメタデータを変更できます。クラスとプロパティーのメタデータには、不変 (固定) メタデータと可変メタデータがあり、それぞれ 2 つのオブジェクトのセット (クラス記述とプロパティー説明オブジェクトのセット、およびクラス定義とプロパティー定義オブジェクトのセット) で表されます。
クラス記述とプロパティー説明のオブジェクトは、読み取り専用プロパティーを使用して、アプリケーションでは変更できない Content Engine のクラスとプロパティーのメタデータを記述 します。これらのオブジェクトは、オブジェクトの関係および階層が変更されたときに、メタデータが不安定な状態にならないようにするために、メタデータのうち固定部分の「スナップショット」を維持する必要があります。このため、クラスおよびプロパティーのメタデータを変更できるようにするために、並行するオブジェクトのセット (クラス定義とプロパティー定義のオブジェクト) が存在します。これらのオブジェクトは、読み取り/書き込みプロパティーを使用して、クライアント・アプリケーションで変更できる Content Engine のクラスとプロパティーのメタデータを定義 します。 アプリケーションでサブクラス化または変更ができるクラスおよびプロパティーにのみ、クラス定義またはプロパティー定義があり、そのプロパティーを変更できます。特定のクラスまたはプロパティーのメタデータが変更され、そのクラス定義およびプロパティー定義オブジェクト内で永続化されて、その継続的なメタデータ状態が Content Engine サーバーによって取得されると、サーバーはオブジェクト・ストア内の対応するクラス説明およびプロパティー説明オブジェクトをそのメタデータの新規状態で更新します。 クラス記述について詳しくは、「クラス記述」を参照してください。クラス定義について詳しくは、「クラス定義」を参照してください。
各クラス内で、記述はクラスのプロパティー説明をすべて保持する PropertyDescriptions プロパティーによって参照される順序付きリストです。各プロパティー説明は、特定のプロパティーの固定の不変メタデータを記述する PropertyDescription オブジェクトによって表されます。すなわち、クラスがオブジェクトにインスタンス化されるときに、プロパティー説明メタデータはそのオブジェクトのプロパティーの基準として使用されます。クラスがインスタンス化された後で、オブジェクトのメタデータには、ClassDescription オブジェクト値プロパティーによって返される ClassDescription オブジェクトからアクセスできます。ClassDescription オブジェクトのすべてのプロパティー (PropertyDescriptions プロパティーにより返されるすべての PropertyDescription オブジェクトを含む) は読み取り専用です。プロパティー説明について詳しくは、「プロパティー説明」を参照してください。
各クラス内で、定義はクラスのプロパティー定義をすべて保持する PropertyDefinitions プロパティーによって参照される番号付きのリストです。各プロパティー定義は、アプリケーションが変更可能な特定のプロパティーの可変メタデータを定義する、PropertyDefinition オブジェクトによって表されます。クラスまたはプロパティーのメタデータを変更するには、それに関連付けられた ClassDefinition および PropertyDefinition オブジェクトのプロパティーを変更する必要があります。プロパティー定義について詳しくは、「プロパティー定義」を参照してください。
プロパティー説明
各プロパティー説明は、特定のクラス・インスタンスに関連付けられた単一プロパティーの説明に使用する不変 (読み取り専用) メタデータ・プロパティーを保持し、クラスの ClassDescription オブジェクトの PropertyDescriptions プロパティーに参照される番号付きのリストに含まれます。
プロパティー説明は、記述対象プロパティーのデータ型に従って分類されます。プロパティー説明クラスは以下の 8 つであり、すべて抽象スーパークラス PropertyDescription からサブクラス化されています。これらはすべてのプロパティー説明タイプに共通のプロパティーを定義します。
- PropertyDescriptionBinary: BINARY 値を持つプロパティーを記述します。
- PropertyDescriptionBoolean: BOOLEAN 値を持つプロパティーを記述します。
- PropertyDescriptionDateTime: DATE 値を持つプロパティーを記述します。
- PropertyDescriptionFloat64: DOUBLE 値を持つプロパティーを記述します。
- PropertyDescriptionId: GUID 値を持つプロパティーを記述します。
- PropertyDescriptionInteger32: LONG 値を持つプロパティーを記述します。
- PropertyDescriptionObject: OBJECT 値を持つプロパティーを記述します。
- PropertyDescriptionString: STRING 値を持つプロパティーを記述します。
すべてのプロパティー説明オブジェクトは、以下の読み取り専用メタデータ・プロパティーを保持します。
- DataType: プロパティーが保持できる値のデータ型を指定します。
- Cardinality: プロパティーが単一値 (単一カーディナリティー) または複数値 (リストまたは列挙カーディナリティー) のどちらを保持できるかを指定します。
- IsValueRequired: プロパティーが値を保持する必要があるかどうかを指定します。
- Settability: プロパティー値の設定可能度を示す PropertySettability 定数を指定します。
- IsReadOnly: プロパティー値を変更できるかどうかを指定します。
- IsSystemGenerated: プロパティー値を Content Engine によって自動的に設定するかどうかを指定します。
- IsSystemOwned: プロパティーがユーザー作成ではなく、初めに Content Engine によって作成されたかどうかを指定します。
- IsHidden: プロパティーを管理者以外のユーザーに非表示にするかどうかを指定します。
- IsOrderable、IsSearchable、IsSelectable: プロパティーの照会操作での表示方法を指定します。
- RequiresUniqueElements: 複数値プロパティーの値を固有にする必要があるかどうかを指定します。
- PersistentType: プロパティーを永続的にできる (すなわち、状態をデータベースに保管する) かどうかを指定します。
- PrivilegedSettability: アプリケーションが特権書き込みアクセス権を付与された場合にプロパティーが設定可能かどうかを指定します。
また、すべてのプロパティー説明オブジェクトは、形式がタイプ固有の以下のプロパティーを保持します。
- プロパティーのデフォルト値を必要に応じて指定するプロパティー。例えば PropertyDescriptionString オブジェクトの場合、このプロパティーは PropertyDefaultString です。
- プロパティーに割り当て可能な値のリストを必要に応じて指定するプロパティー。例えば PropertyDescriptionObject オブジェクトの場合、このプロパティーは PropertySelectionsObject です。
- PropertyDescriptionId と PropertyDescriptionObject を除くすべてのプロパティー説明オブジェクトで、プロパティーに許可される最大値を指定するプロパティー。例えば PropertyDescriptionString オブジェクトの場合、このプロパティーは MaximumLengthString です。
- PropertyDescriptionDateTime、PropertyDescriptionFloat64、および PropertyDescriptionInteger32 オブジェクトで、許可される最小値を指定するプロパティー。例えば PropertyDescriptionInteger32 オブジェクトの場合、このプロパティーは PropertyMinimumInteger32 です。
PropertyDescriptionObject オブジェクトには、以下の追加プロパティーが含まれます。
- AllowsForeignObject: オブジェクト値プロパティーが別のオブジェクト・ストア内のオブジェクトを参照できるかどうかを指定します。
- DeletionAction: 特定のオブジェクト値プロパティーを持つオブジェクトを削除しようとしたときに、そのプロパティーに対して実行するアクションを指定します。
- ReflectivePropertyId: オブジェクト値プロパティーに対する反射プロパティーの ID プロパティーを指定します。反射プロパティーとは、あるクラスの特定のオブジェクトを返すために、別のクラスでの複数値のオブジェクト値プロパティーを制限する目的で作成できるプロパティーのことです。
- RequiredClass: オブジェクトがインスタンスまたはサブクラスでなければならないクラスのクラス記述を指定します。
システム・プロパティーとカスタム・プロパティー
システム・プロパティーは、Content Engine オブジェクトに不可欠なプロパティーであり、クラス定義に追加することもクラス定義から削除することもできません。読み取り/書き込みアクセス権を持つ (また、ユーザーが適切な権限を持つ) システム・プロパティーの値を変更することはできますが、通常、そのメタデータを変更することはできません。(例外は、特定のシステム・プロパティーのプロパティー定義の PropertyDefaultXXX プロパティーです。)カスタム・プロパティーとは異なり、システム・プロパティーには関連付けられたプロパティー・テンプレートがないため、プロパティー定義の PropertyTemplate プロパティーは null です。
カスタム・プロパティーは、ユーザーがクラスに割り当てることができるユーザー定義プロパティーです。システム・メタデータを拡張する手段として、カスタム・プロパティーを定義します。また、カスタム・プロパティーの特定のメタデータ・プロパティーは、作成後であっても変更できます。各カスタム・プロパティーは、プロパティー定義の PropertyTemplate プロパティーで指定されるプロパティー・テンプレートに基づきます。
オブジェクト値カスタム・プロパティーの場合、プロパティーが保持できるオブジェクトのタイプは、プロパティー定義の RequiredClassId プロパティーによって決定されます。オブジェクト値カスタム・プロパティーの値は、以下のいずれかのタイプのオブジェクトになります。
- RepositoryObject サブクラスのインスタンス。
- SecurityPrincipal サブクラスのインスタンス (User および Group オブジェクトを含む)。
- 単独で取得可能な GCD オブジェクト。GCD オブジェクト EntireNetwork および Domain は使用できません。
クラスにカスタム・プロパティーを追加するには、まず新規プロパティー定義の作成の基礎として使用するプロパティー・テンプレートを作成 (または既存のものを選択) する必要があります。プロパティー・テンプレートを作成した後で、それを使用して、ユーザー定義のプロパティー定義を作成し、クラス定義に追加することができます。システム・プロパティーはクラス定義を介してクラスに割り当てることはできません。割り当てることができるのはカスタム・プロパティーのみです。
カスタム・プロパティーをクラスに追加するには、以下の手順を実行します。
- サブクラス化するクラスに属するクラス定義へのオブジェクト参照を取得します (Factory.ClassDefinition.fetchInstance メソッドを使用)。 クラス定義の AllowsPropertyAdditions プロパティーの値が true である必要があります。これは、クラスがユーザー拡張可能であることを示します。
- 既存のプロパティー・テンプレートを新規カスタム・プロパティーの基として使用しない場合は、プロパティー・テンプレート・オブジェクトを作成して必要なプロパティーを設定し、それを保存します。
- プロパティー・テンプレートの createClassProperty メソッドを呼び出し、それが返す新規プロパティー定義への参照を設定します。
- クラス定義の PropertyDefinitions プロパティーへのオブジェクト参照を取得し、新規プロパティー定義をパラメーターとして、PropertyDefinitionList コレクション・オブジェクトの add メソッドを呼び出します。
- クラス定義の save メソッドを呼び出して、新しいプロパティーをオブジェクト・ストアに保存します。
シンボル名
プロパティーのシンボル名は、クラス・ファミリー内でのみ固有である必要があります。クラス・ファミリーは、1 つのルート・クラス (Document、Folder、CustomObject など) とそのすべての子孫によって定義されます。
4.5.1 リリース以降、IBM® FileNet® P8 Content Engine に対して、プロパティーおよびクラスのシンボル名のメタデータ接頭部命名規則が定義されています。 このリリース以降に (独自の Content Engine 機能アドオンを生成する IBM FileNet P8 製品によって、または Content Engine サーバー内の新規システム・プロパティーによって) 導入されたすべての新規プロパティーおよびクラスは、この命名規則を順守する必要があります。この命名規則は、プロパティーおよびクラスのシンボル名の値にのみ適用されることに注意してください。表示名として選択する値に対する制約はありません。
接頭部命名規則の詳細を以下に示します。
- 「Cm」接頭部は、このリリース内で導入されたユーザー拡張可能クラスの新規 Content Engine クラスまたはシステム・プロパティーのシンボル名で使用されます。例えば、「CmNewProperty」です。
- すべての新規システム・クラスは、ユーザー拡張可能かどうかとは無関係に、命名規則に従います。
- 「Cm」接頭部は、Content Engine 機能アドオン内で導入された新規プロパティーまたはクラスでも使用されます。ただし、DITA 機能アドオンでは、「Cm」接頭部ではなく「Dita」接頭部が引き続き使用されます。
4.5.1 リリース以降、独自の機能アドオンを生成するすべての IBM FileNet P8 製品も、接頭部命名規則に適合します。 これらの機能アドオンは「Cm???」接頭部を使用します (「???」は、製品名を短縮した省略語を表します)。ただし、このリリースより前に独自の接頭部命名規則が既に設定されているすべての IBM ECM 製品では、その命名規則が引き続き使用されます。
予約されているアドオン・メタデータ接頭部のリストを以下に示します。
- 「Cm」: IBM FileNet P8 Content Engine で使用するために予約済み
- 「Dita」: DITA アドオン用に IBM FileNet P8 Content Engine で使用するために予約済み
- 「RM」: IBM Enterprise Records で使用するために予約済み
- 「EDM」: IBM eDiscovery Manager で使用するために予約済み
- 「EDISC_」: IBM eDiscovery Manager で使用するために予約済み
- 「ICC」: IBM Content Collector で使用するために予約済み
新規のカスタム・プロパティーまたはクラスを作成する場合、そのシンボル名には、これらの予約済み接頭部のいずれかで開始される値を割り当てないでください。この規則を順守している限り、このリリースまたは将来のアップグレードにおいて、名前の衝突が発生することはありません。
設定可能なシステム・プロパティー
4 つのシステム・プロパティー (Creator、DateCreated、Modifier、LastModifier) を設定する機能は、オブジェクト・ストアに対する AccessRight.PRIVILEGED_WRITE アクセス権によって得られます。これらのプロパティーは、標準のユーザーに対しては読み取り専用のままです。PRIVILEGED_WRITE アクセス権へのアクセスが付与されたユーザーの場合、Creator および DateCreated プロパティーの設定可能性は SETTABLE_ONLY_ON_CREATE であり、LastModifier および DateLastModified プロパティーの設定可能性は READ_WRITE です。
プロパティー・テンプレート
プロパティー・テンプレートは、1 つ以上のカスタム・プロパティーをグローバルに定義するために使用する、可変メタデータ・プロパティーのコレクションです。システム・プロパティーにはプロパティー・テンプレートがないことに留意してください。プロパティー・テンプレートによりクラス・プロパティーの作成の基となる標準テンプレートが提供されることで、オブジェクト・ストア内および複数のオブジェクト・ストア間でプロパティーの再利用が促進されます。また、プロパティー・テンプレートにより、プロパティーのロケール固有の表示名および記述テキストの変更を行うための単一点と多文化サポートが実現します。特定のプロパティー定義の基礎を成すプロパティー・テンプレートには、DisplayName プロパティーおよび DescriptiveText プロパティーのプロパティー定義のロケール固有の文字列が含まれます。プロパティー・テンプレートからプロパティー定義が作成された後で、そのプロパティー・テンプレートとの関連は永続的に保持されます。プロパティー・テンプレートはどのクラスにも関連付けられていません。すなわち、各プロパティー・テンプレートは独立して永続可能であり、独立して保護することができます。各プロパティー・テンプレートは 1 つのオブジェクト・ストア内で固有でなければならず、複数のオブジェクト・ストアにおいてグローバルに固有であるように別名を割り当てることもできます。
プロパティー・テンプレートは、定義対象プロパティーのデータ型に従って分類されます。プロパティー・テンプレート・クラスは以下の 8 つであり、すべて抽象スーパークラス PropertyTemplate からサブクラス化されています。これらはすべてのプロパティー・テンプレート・タイプに共通のプロパティーを定義します。
- PropertyTemplateBinary: BINARY 値を持つプロパティーのテンプレートを記述します。
- PropertyTemplateBoolean: BOOLEAN 値を持つプロパティーのテンプレートを記述します。
- PropertyTemplateDateTime: DATE 値を持つプロパティーのテンプレートを記述します。
- PropertyTemplateFloat64: DOUBLE 値を持つプロパティーのテンプレートを記述します。
- PropertyTemplateId: GUID 値を持つプロパティーのテンプレートを記述します。
- PropertyTemplateInteger32: LONG 値を持つプロパティーのテンプレートを記述します。
- PropertyTemplateObject: OBJECT 値を持つプロパティーのテンプレートを記述します。
- PropertyTemplateString: STRING 値を持つプロパティーのテンプレートを記述します。
各プロパティー・テンプレート・オブジェクトには、プロパティー・メタデータをグローバルに制御するために以下の読み取り/書き込みプロパティーがあります。プロパティー・テンプレートで設定したプロパティーの値は、その関連付けられているプロパティー定義に継承されます。
- AliasIds: プロパティーのオプションの別名 ID のリストが含まれる IdList オブジェクトを指定します。
- Cardinality: プロパティーが単一値、リスト、列挙のいずれを表すかを指定します。このプロパティーを設定できるのは、プロパティー・テンプレートの作成時のみです。すなわち、プロパティー・テンプレートを保存すると、そのプロパティー・テンプレート (およびそのプロパティー・テンプレートから作成されるすべてのプロパティー定義) での Cardinality プロパティーの設定可能性は読み取り専用になります。
- ChoiceList: プロパティーが保持できる値の別個のセットを表す ChoiceList オブジェクトを指定します。
- DescriptiveTexts: LocalizedString オブジェクト・コレクションを含む LocalizedStringList オブジェクトを指定します。含まれる個々のオブジェクトは、プロパティーのロケール固有のユーザー読み取り可能な記述を表します。オブジェクト・ストアのデフォルト・ロケールに対する LocalizedString オブジェクトの LocalizedText プロパティー値は、プロパティー定義の DescriptiveText プロパティーの読み取り専用値になります。
- DisplayNames: LocalizedString オブジェクト・コレクションを含む LocalizedStringList オブジェクトを指定します。含まれる個々のオブジェクトは、プロパティーのロケール固有のユーザー読み取り可能な表示名を表します。 オブジェクト・ストアのデフォルト・ロケールに対する LocalizedString オブジェクトの LocalizedText プロパティー値は、プロパティー定義の DisplayName プロパティーの読み取り専用値になります。
- IsHidden: プロパティーを管理者以外のユーザーに非表示にするかどうかを指定します。
- IsNameProperty: プロパティー値が、それが属するクラスのオブジェクト・インスタンス名を示すかどうかを指定します。
- IsValueRequired: プロパティーが値を保持する必要があるかどうかを指定します。
- ModificationAccessRequired: プロパティーの発生対象であるオブジェクト・インスタンスのプロパティー値の変更に必要なアクセス権を指定します。
- PersistenceType: プロパティーを永続化できる (すなわち、プロパティーの状態をデータベースに保管できる) かどうかを示す PropertyPersistence 定数を指定します。
- RequiresUniqueElements: 複数値プロパティーの値を固有にする必要があるかどうかを指定します。このプロパティーを設定できるのは、プロパティー・テンプレートの作成時のみです。すなわち、プロパティー・テンプレートを保存すると、そのプロパティー・テンプレート (およびそのプロパティー・テンプレートから作成されるすべてのプロパティー定義) での RequiresUniqueElements プロパティーの設定可能性は読み取り専用になります。
- Settability: プロパティー値の設定可能度を示す PropertySettability 定数を指定します。
また、すべてのプロパティー・テンプレート・オブジェクトは、形式がタイプ固有の以下のプロパティーを保持します。
- プロパティーのデフォルト値を必要に応じて指定するプロパティー。例えば PropertyTemplateString オブジェクトの場合、このプロパティーは PropertyDefaultString です。
- PropertyTemplateId と PropertyTemplateObject を除くすべてのプロパティー・テンプレート・オブジェクトで、プロパティーに許可される最大値を指定するプロパティー。例えば PropertyTemplateString オブジェクトの場合、このプロパティーは MaximumLengthString です。
- PropertyTemplateDateTime、PropertyTemplateFloat64、および PropertyTemplateInteger32 オブジェクトで、許可される最小値を指定するプロパティー。例えば PropertyTemplateInteger32 オブジェクトの場合、このプロパティーは PropertyMinimumInteger32 です。
PropertyTemplateObject オブジェクトには、以下の追加プロパティーが含まれます。
- AllowsForeignObject: オブジェクト値プロパティーが別のオブジェクト・ストア内のオブジェクトを参照できるかどうかを指定します。
プロパティー定義
プロパティー定義は、プロパティー・テンプレートから生成された可変メタデータのコレクションです。各プロパティー定義は特定のクラス定義に関連付けられ、クラスのオブジェクト・インスタンスに属するプロパティーを表します。プロパティー定義は独立して永続可能であり、独立して保護することができます。プロパティー定義のプロパティー値を変更することにより、プロパティー・テンプレートで定義されたユーザー定義プロパティーのメタデータを変更できます。通常、システム・プロパティーのプロパティー定義は変更できません。(例外は、特定のシステム・プロパティーのプロパティー定義の PropertyDefaultXXX プロパティーです。)
プロパティー定義は、記述対象プロパティーのデータ型に従って分類されます。プロパティー定義クラスは以下の 8 つであり、すべて抽象スーパークラス PropertyDefinition からサブクラス化されています。これらはすべてのプロパティー定義タイプに共通のプロパティーを定義します。
- PropertyDefinitionBinary: BINARY 値を持つプロパティーを定義します。
- PropertyDefinitionBoolean: BOOLEAN 値を持つプロパティーを定義します。
- PropertyDefinitionDateTime: DATE 値を持つプロパティーを定義します。
- PropertyDefinitionFloat64: DOUBLE 値を持つプロパティーを定義します。
- PropertyDefinitionId: GUID 値を持つプロパティーを定義します。
- PropertyDefinitionInteger32: LONG 値を持つプロパティーを定義します。
- PropertyDefinitionObject: OBJECT 値を持つプロパティーを定義します。
- PropertyDefinitionString: STRING 値を持つプロパティーを定義します。
各プロパティー定義オブジェクトには、プロパティーのメタデータを変更可能にする、以下の読み取り/書き込みプロパティーがあります。
- AliasIds: プロパティーのオプションの別名 ID のリストが含まれる IdList オブジェクトを指定します。
- ChoiceList: プロパティーが保持できる値の別個のセットを表す ChoiceList オブジェクトを指定します。
- CopyToReservation: ドキュメントのチェックアウト時に、ドキュメントに属するプロパティー値をソース・ドキュメントから新規作成された予約オブジェクトにコピーするかどうかを指定します。
- IsHidden: プロパティーを管理者以外のユーザーに非表示にするかどうかを指定します。
- IsNameProperty: プロパティー値が、それが属するクラスのオブジェクト・インスタンス名を示すかどうかを指定します。
- IsValueRequired: プロパティーが値を保持する必要があるかどうかを指定します。
- ModificationAccessRequired: プロパティーの発生対象であるオブジェクト・インスタンスのプロパティー値の変更に必要なアクセス権を指定します。
- Settability: プロパティー値の設定可能度を示す PropertySettability 定数を指定します。
また、すべてのプロパティー定義オブジェクトは、形式がタイプ固有の以下のプロパティーを保持します。
- プロパティーのデフォルト値を必要に応じて指定するプロパティー。例えば PropertyDefinitionString オブジェクトの場合、このプロパティーは PropertyDefaultString です。
- PropertyDefinitionId と PropertyDefinitionObject を除くすべてのプロパティー定義オブジェクトで、プロパティーに許可される最大値を指定するプロパティー。例えば PropertyDefinitionString オブジェクトの場合、このプロパティーは MaximumLengthString です。
- PropertyDefinitionDateTime、PropertyDefinitionFloat64、および PropertyDefinitionInteger32 オブジェクトで、許可される最小値を指定するプロパティー。例えば PropertyDDefinitionInteger32 オブジェクトの場合、このプロパティーは PropertyMinimumInteger32 です。
PropertyDefinitionObject オブジェクトには、以下の追加プロパティーが含まれます。
- AllowsForeignObject: オブジェクト値プロパティーが別のオブジェクト・ストア内のオブジェクトを参照できるかどうかを指定します。
- DeletionAction: 特定のオブジェクト値プロパティーを持つオブジェクトを削除しようとしたときに、そのプロパティーに対して実行するアクションを指定します。
- ReflectivePropertyId: オブジェクト値プロパティーに対する反射プロパティーの ID プロパティーを指定します。反射プロパティーとは、あるクラスの特定のオブジェクトを返すために、別のクラスでの複数値のオブジェクト値プロパティーを制限する目的で作成できるプロパティーのことです。
- RequiredClassId: オブジェクトがインスタンスまたはサブクラスでなければならないクラスのクラス記述の ID を指定します。
カスタム・メタプロパティーの変更
カスタムのプロパティー定義は、プロパティー・テンプレートから生成されます。プロパティー・テンプレートからプロパティー定義を作成すると、プロパティー・テンプレートの多くのメタプロパティーがプロパティー定義にコピーされます。カスタムのプロパティー定義には、生成元のプロパティー・テンプレートと同じメタプロパティーが多く含まれるため、プロパティー定義でメタプロパティーを変更する選択肢が複数用意されています。
ほとんどのメタプロパティーはクラスごとに変更できます。つまり、クラス内のプロパティー定義で直接メタプロパティーを変更できます。プロパティー定義でのメタプロパティーの変更は、サブクラスに伝搬される場合もされない場合もあります。
一部のメタプロパティーは、クラス・ベースで変更できません。それらは、生成元のプロパティー・テンプレートで変更する必要があります。この場合、プロパティー・テンプレートでのメタプロパティーの変更が、そのプロパティー定義を参照するすべてのクラスに反映されます。
プロパティー・テンプレートおよびプロパティー定義クラスでメタプロパティーを変更したときの影響の要約を次の表に示します。以下が示されています。
- PropertyTemplate および PropertyDefinition のクラスとサブクラスに設定可能なすべてのメタプロパティー。
- メタプロパティーがプロパティー・テンプレート、プロパティー定義、その両方のいずれで変更可能であるか。原則的に、プロパティー定義でも変更可能なメタプロパティーをプロパティー・テンプレートで変更した場合、その変更はプロパティー定義には反映されません。
- プロパティー定義でのメタプロパティーの変更がサブクラスに自動的に伝搬されるかどうか。
メタプロパティー | プロパティー・テンプレートで変更可能であるか | プロパティー定義で変更可能であるか | プロパティー・テンプレートでの変更がプロパティー定義に反映されるか | プロパティー定義での変更がサブクラスに自動的に伝搬されるか |
---|---|---|---|---|
AliasIds | はい | はい | いいえ | はい |
AllowsForeignObject | はい | はい | いいえ | いいえ |
AuditAs | はい | はい | いいえ | はい |
Cardinality | いいえ、作成時にのみ設定可能 | いいえ | 適用外 | 適用外 |
ChoiceList | はい | はい | いいえ | はい 1 |
CopytoReservation | 適用外 | はい | 適用外 | いいえ |
Creator | いいえ、AccessRight.PRIVILEGED_WRITE の変更が必要 | 適用外 | 適用外 | 適用外 |
DateCreated | いいえ、AccessRight.PRIVILEGED_WRITE の変更が必要 | 適用外 | 適用外 | 適用外 |
DateLastModified | いいえ、AccessRight.PRIVILEGED_WRITE の変更が必要 | 適用外 | 適用外 | 適用外 |
DescriptiveTexts | はい | 適用外 | はい (ProperteryDefinition.DescriptiveText を使用) | 適用外 |
DisplayNames | はい | 適用外 | はい (ProperteryDefinition.DisplayName を使用) | 適用外 |
ExternalAliases | 適用外 | はい | 適用外 | はい 1 |
IsHidden | はい | はい | いいえ | いいえ |
IsNameProperty | はい | はい | いいえ | いいえ |
IsValueRequired | はい | はい | いいえ | いいえ |
LastModifier | いいえ、AccessRight.PRIVILEGED_WRITE の変更が必要 | 適用外 | 適用外 | 適用外 |
MaximumLengthBinary | はい | はい | いいえ | はい、ただし小さくする場合のみ |
MaximumLengthString | はい | はい | いいえ | はい、ただし小さくする場合のみ |
ModificationAccessRequired | はい | はい | いいえ | いいえ |
Owner | はい | 適用外 | 適用外 | 適用外 |
権限 | はい | 適用外 | 適用外 | 適用外 |
PersistenceType | いいえ、作成時にのみ設定可能 | いいえ | 適用外 | 適用外 |
PropertyDefaultBoolean | はい | はい | いいえ | いいえ |
PropertyDefaultBinary | はい | はい | いいえ | いいえ |
PropertyDefaultDateTime | はい | はい | いいえ | いいえ |
PropertyDefaultFloat64 | はい | はい | いいえ | いいえ |
PropertyDefaultId | はい | はい | いいえ | いいえ |
PropertyDefaultInteger32 | はい | はい | いいえ | いいえ |
PropertyDefaultString | はい | はい | いいえ | いいえ |
PropertyDisplayCategory | はい | 適用外 | 適用外 | 適用外 |
PropertyMaximumDateTime | はい | はい | いいえ | はい、ただし小さくする場合のみ |
PropertyMaximumFloat64 | はい | はい | いいえ | はい、ただし小さくする場合のみ |
PropertyMaximumInteger32 | はい | はい | いいえ | はい、ただし小さくする場合のみ |
PropertyMinimumDateTime | はい | はい | いいえ | はい、ただし大きくする場合のみ |
PropertyMinimumFloat64 | はい | はい | いいえ | はい、ただし大きくする場合のみ |
PropertyMinimumInteger32 | はい | はい | いいえ | はい、ただし大きくする場合のみ |
RequiresUniqueElements | いいえ、作成時にのみ設定可能 | いいえ | 適用外 | 適用外 |
SecurityProxyType | はい | はい | いいえ | はい |
Settability | はい | はい | いいえ | はい、ただし厳しくする場合のみ |
SymbolicName | はい | いいえ | はい | いいえ |
1 複数値プロパティー。リスト値の更新は、暗黙的に伝搬されます。ただし、プロパティー定義へのメタプロパティーの追加は、自動的には伝搬されません。
プロパティー値
オブジェクトのプロパティーは、保持するデータ型に応じて、Property クラスの以下のサブクラスのいずれかに属するオブジェクトによって表されます。
単一値プロパティー
- PropertyBinary: バイナリー値向けのバイト (8 ビットの符号付き整数) 配列を持つプロパティーを表します。
- PropertyBoolean: ブール値を持つプロパティーを表します。
- PropertyContent: ファイル・ソースからコンテンツ・データのバイトを読み取るための InputStream オブジェクトを持つプロパティーを表します。
- PropertyDateTime: 日時を指定する Date オブジェクトを持つプロパティーを表します。
- PropertyFloat64: 倍精度 (64 ビットの浮動小数点) 値を持つプロパティーを表します。
- PropertyId: Id (GUID 文字列) 値を持つプロパティーを表します。
- PropertyInteger32: 整数 (32 ビットの符号付き整数) 値を持つプロパティーを表します。
- PropertyString: 文字列値を持つプロパティーを表します。
- PropertyEngineObject: 単一の Content Engine オブジェクト (EngineObject サブクラスのインスタンス) を持つプロパティーを表します。
複数値プロパティー
- PropertyBinaryList: Binary 値のコレクションが含まれる BinaryList オブジェクトを持つプロパティーを表します。
- PropertyBooleanList: Boolean 値のコレクションが含まれる BooleanList オブジェクトを持つプロパティーを表します。
- PropertyDateTimeList: Date 値のコレクションが含まれる DateTimeList オブジェクトを持つプロパティーを表します。
- PropertyFloat64List: Double 値のコレクションが含まれる Float64List オブジェクトを持つプロパティーを表します。
- PropertyIdList: GUID String 値のコレクションが含まれる IdList オブジェクトを持つプロパティーを表します。
- PropertyInteger32List: Integer 値のコレクションが含まれる Integer32List オブジェクトを持つプロパティーを表します。
- PropertyStringList: String 値のコレクションが含まれる StringList オブジェクトを持つプロパティーを表します。
- PropertyIndependentObjectSet: IndependentObject オブジェクト値のコレクションが含まれる IndependentObjectSet オブジェクトを持つプロパティーを表します。
- PropertyDependentObjectList: DependentObject オブジェクト値のコレクションが含まれる DependentObjectList オブジェクトを持つプロパティーを表します。
プロパティー値の読み取り
プロパティー値の読み取りまたは設定、または特定のオブジェクト・プロパティーを表す Property オブジェクトの取得を行うには、まずオブジェクトの Properties オブジェクトを取得する必要があります。Properties オブジェクトは、特定の Content Engine オブジェクトに属するすべてのプロパティーのコレクションです。オブジェクトの Properties オブジェクトを取得するには、オブジェクトの getProperties メソッドを呼び出します。オブジェクトの Properties コレクション・オブジェクトを取得すると、以下の手順のいずれかを使用して特定のプロパティーの値を読み取ることができます。Properties オブジェクト・コレクション内の個々のプロパティーは、カーディナリティーに応じて単一値または複数値を持つことに留意してください。
- 取得するプロパティーのデータ型に対応する、適切な Properties オブジェクトの getXXXValue メソッド (getBinaryValue、getBinaryListValue、getBooleanValue など) を呼び出し、プロパティー名をパラメーターとして指定します。
- Properties オブジェクトの get メソッドを使用し、プロパティー名をパラメーターとして使用して、特定のプロパティーを取得します。選択したプロパティーから、プロパティーのデータ型に対応する適切な getXXXValue メソッドを呼び出します。
Properties オブジェクト・コレクション内の特定の Property オブジェクトを取得するには、以下のいずれかの方法を実行します。
- Properties オブジェクトの get メソッドを使用し、取得するプロパティー名を指定します。
- Java アプリケーションでは、iterator() メソッドを使用して、Properties オブジェクト・コレクション内の各 Property オブジェクトを反復処理することができます。
- C# アプリケーションでは、ForEach コマンドを使用して、Properties オブジェクト・コレクション内の各 Property オブジェクトを反復処理することができます。
プロパティー値の設定
Property オブジェクトの isSettable プロパティーの値が true である場合、アプリケーションは以下のいずれかの方法でプロパティー値を設定できます。
- Properties オブジェクト・コレクション内の特定のプロパティーの値を設定するには、プロパティーのデータ型に対応する適切な putValue メソッド (putValue(java.lang.String propertyName, BinaryList value)、putValue(java.lang.String propertyName, boolean value) など) を使用します。
- Property オブジェクトで表されるプロパティーの値を設定するには、そのプロパティーの setValue メソッドを呼び出し、パラメーターを新規のプロパティー値に設定します。
- Property オブジェクトで表されるプロパティーの値を設定するには、そのプロパティーの setObjectValue メソッドを呼び出し、パラメーターを新規のプロパティー値に設定します。
特殊な状況
プロパティーの読み取り時または設定時には、以下のことに注意してください。
- サーバーから読み取り専用プロパティーをフェッチし、クライアント・アプリケーションによってそのプロパティーの値を変更しようとすると、クライアントで即時に (保存する前に) 例外が発生します。ただし、新規プロパティー (当初は取得から除外されていたプロパティー) をプロパティー・キャッシュに追加する場合、そのプロパティーが設定可能かどうかの情報 (プロパティーの isSettable メソッドから取得可能) はプロパティー・キャッシュに存在しません。したがって、新規プロパティーは読み取り専用かどうかに関係なく、プロパティーが属するオブジェクトが保存されない限り、クライアントによる変更が許可され、生成されたエラーは返されません。
- データベースで永続化 (保存) できないデフォルト値を持つカスタム・プロパティーを定義する場合で、そのプロパティーの追加先クラスからインスタンス化されたオブジェクトを後でフェッチする場合、プロパティーのデフォルト値しか取得できません。プロパティーがデータベースで永続化されていないため、その他の値は取得できません。特定のカスタム・プロパティーを永続化できるかどうかは、それに関連付けられているプロパティー・テンプレートの PersistenceType プロパティーに指定された値によって決まります。
- アプリケーションが PropertyTemplateString オブジェクトの PropertyDefaultString プロパティーを 4000 文字を超えない長い文字列に設定しようとすると、BAD_VALUE 例外ではなく DB_ERROR 例外が発生する場合があります。この例外が発生するのは、データベースの最大行サイズを超えたが、プロパティー値に許可された最大長は超えていない場合です。
- ユーザー開始トランザクション時に 1 つ以上の読み取り専用プロパティーの更新が試行されたことが原因で E_READ_ONLY 例外が発生した場合、トランザクションはサーバーによって自動的にロールバックされません。すなわち、クライアント・アプリケーションによって明示的にデータをロールバックまたはコミットする必要があります。
プロパティー・キャッシュの概念
システム・リソースを保存するため、各 Content Engine オブジェクトはオブジェクトのプロパティーの 1 つ以上 (使用可能な場合) を取得可能なローカル (クライアント側) プロパティー・キャッシュを維持します。オブジェクトの更新またはプロパティーのフェッチ時にサーバーからプロパティーが取得されるたびに、プロパティー・キャッシュにデータが追加されます。プロパティー・キャッシュに必要なプロパティーを入れておくようにすることで、クライアント・アプリケーションからサーバーへのラウンド・トリップを最小限に抑えることができ、パフォーマンスが向上します。
オブジェクトのインスタンス化には 3 つの方法があり、それぞれローカル・プロパティー・キャッシュの初期状態に対する効果が異なります。
- フェッチなしインスタンス化: 指定したクラスのローカル・インスタンスを作成するには、ファクトリーの getInstance メソッドを呼び出します。このメソッドでは、サーバー上に要求されたオブジェクトがあるかどうかは検証しません。すなわち、サーバーへのラウンド・トリップを行わずにローカル参照を返します。オブジェクトに対してサーバーへのラウンド・トリップを引き起こす関数 (プロパティー値のフェッチなど) を実行するまでは、ローカル参照はサーバー・オブジェクトに関与しないため、それまでプロパティー・キャッシュには setter アクセサー・メソッドの呼び出しで追加されたプロパティー以外何も含まれないままです。オブジェクトが受動的にのみ機能する場合 (オブジェクト値プロパティーのターゲット値となる場合など)、パフォーマンス上の理由から、フェッチせずにこの方法でオブジェクトをインスタンス化するのが有用です。
- フェッチによるインスタンス化: 指定したサーバー・オブジェクトを取得するには、ファクトリーの fetchInstance メソッドを呼び出します。このメソッドでは、サーバーへのラウンド・トリップを行い、オブジェクトのプロパティー値をフェッチすることでオブジェクトをインスタンス化します。クライアント・アプリケーションはプロパティー・フィルターを使用して、どのプロパティーをローカル・プロパティー・キャッシュにフェッチするかを制御します。インスタンス化されたローカルのオブジェクトには、フェッチ時点での現行の更新シーケンス番号の値が含まれています。ただし、サーバー・オブジェクトは長期にわたると変更される場合があります。ローカル・オブジェクトを最新の状態に保つには、refresh メソッドを呼び出します。
- インスタンス化の作成: 新規サーバー・オブジェクトを参照するローカル・オブジェクトをインスタンス化するには、ファクトリー createInstance メソッドを呼び出します。ローカル・オブジェクトのインスタンス化の時点で、サーバーへのラウンド・トリップは行われず、オブジェクトはリポジトリー内で永続化されません。代わりに、ローカル・インスタンスには Create 保留アクションが関連付けられます。新規オブジェクトをオブジェクト・ストアに対して永続化するには、その save メソッドを明示的に呼び出すか、バッチ操作を使用してオブジェクトをコミットする必要があります。どちらの方法でも、サーバーへのラウンド・トリップが行われます。オブジェクトが保存されて更新されるまで、プロパティー・キャッシュには setter アクセサー・メソッドの呼び出しにより追加されたプロパティーのみが含まれます。
サーバー・オブジェクト・プロパティーをローカル・プロパティー・キャッシュに追加する方法は、以下の 2 つです。
- オブジェクトの更新: サーバーからプロパティーの新規セットを追加するには、既存のオブジェクトの refresh メソッドを呼び出します。同じオブジェクトのプロパティー・キャッシュに既にプロパティー・セットがある場合、そのセット全体が破棄されます。
- プロパティーのフェッチ: サーバーへのラウンド・トリップを行い、プロパティー・キャッシュに新規プロパティーを追加するか、または既存のプロパティーを再フェッチするには、オブジェクトの fetchProperty メソッドまたは
fetchProperties メソッドを呼び出します。オブジェクトのプロパティー・キャッシュに既存のプロパティーがある場合はマージされます。すなわち、新規プロパティーは追加され、既存のプロパティーは置き換えられます。このオブジェクトが、最後の取得以降にサーバーで変更された (サーバー・オブジェクトとローカル・オブジェクトの更新シーケンス番号が異なる) 場合、まず refresh メソッドを呼び出してください。そうしないとエラーが発生します。プロパティーのフェッチ時には、以下のルールが適用されます。
- ダーティー・プロパティー (以下を参照) をフェッチ済みプロパティーで置き換えようとしても、例外は発生せず、フェッチ済みプロパティーが自動的にダーティー・プロパティーと置き換わります。
- 返されたオブジェクトが現在のオブジェクトより新しい場合、例外が発生します。
- 特殊なケースとしては、フェッチを行わずにインスタンス化された現在のオブジェクトは、返されるすべてのオブジェクトにそれ自体を一致させます。その後、現在のオブジェクトは返されたオブジェクトの更新シーケンス番号を使用するため、フェッチを行わずにインスタンス化されたオブジェクトとは見なされなくなります。
プロパティー・キャッシュから特定のオブジェクト・プロパティーを削除するには、Properties.removeFromCache メソッドのいずれかを使用します。指定したプロパティーがプロパティー・キャッシュにない場合、例外は発生しません。キャッシュから削除されたプロパティーの値に対する後続の要求では、例外が発生します。
getter アクセサー・メソッドを使用してプロパティーにアクセスする場合、プロパティー・キャッシュからのプロパティーの読み取りが試行されます。プロパティー・キャッシュ内にそのプロパティーが見つからない場合、API_PROPERTY_NOT_IN_CACHE 例外が発生します。ただし、未評価オブジェクトを返すプロパティーが、明示的な値を持たずにキャッシュ内に存在する場合があります。未評価オブジェクトの値をフェッチすると、サーバーへのラウンド・トリップが自動的に行われて値が取得されるため、例外は生成されません。
setter アクセサー・メソッドを使用してプロパティーの値を設定すると、キャッシュ値 (存在する場合) が更新されるか新規キャッシュ項目が追加されますが、そのプロパティー値がすぐに永続的ストアに保持されません。代わりに、変更されたプロパティーはすべて、明示的に保存される (save メソッド呼び出しを使用) か他の操作の副次作用として暗黙的に保存されるまで、内部に累積されます。プロパティー・キャッシュ内のプロパティーは、変更されても保持されていない場合、サーバーによって「ダーティー」とマークされます。これにより、サーバーは永続的ストア内でどのプロパティーが状態を更新する必要があるかを追跡できます。キャッシュ内のプロパティー値を変更した後、それを元の値に戻す唯一の方法は、サーバーから値を再フェッチすることです。クライアントとサーバー間の更新で伝送されるのはダーティー・プロパティーのみです。IsDirty メソッドで true が返されるプロパティーは、サーバーで状態が更新され、ダーティー状態ではないとマークされます。
プロパティー・フィルターの概念
プロパティー・フィルターを使用すると、どの Content Engine オブジェクト・プロパティー (および詳細レベル) をオブジェクトの取得またはオブジェクトの更新時にサーバーから返すかを制御できます。オブジェクトによってはプロパティーの数とサイズが大きい場合があるため、プロパティー・フィルターを使用して使用可能なプロパティーのサブセットを取得すると、サーバーから取得されるデータの量が削減され、パフォーマンスが向上します。
オブジェクトからどのプロパティーを返すかを制御する方法の例として、Document および Folder オブジェクト・タイプを取り上げます。以下の表に、Document および Folder オブジェクト・タイプから選択されたプロパティー、保持されるデータ型、およびカーディナリティーを示します。
Document オブジェクト
プロパティー名 | 返されるデータ型 | Cardinality |
---|---|---|
Creator | 文字列 | Single |
DateCreated | DateTime | Single |
Reservation | Document オブジェクト | Single |
FoldersFiledIn | Folder オブジェクト | Enum |
Folder オブジェクト
プロパティー名 | 返されるデータ型 | Cardinality |
---|---|---|
Creator | 文字列 | Single |
DateCreated | DateTime | Single |
ContainedDocuments | Document オブジェクト | Single |
SubFolders | Folder オブジェクト | Enum |
プロパティー・フィルターを使用すると、ドキュメントとそのドキュメントを格納するすべてのフォルダーを 1 度のサーバー呼び出しでフェッチできます。同様に、フォルダーと、そのフォルダーに含まれるすべてのドキュメントおよびサブフォルダーを、1 度のサーバー呼び出しで取得できます (使用可能なメモリーに制約されます)。また、どのオブジェクト・プロパティーをフェッチするかを明示的に指定することもできます。例えば、Creator プロパティーはフェッチするが DateCreated プロパティーはフェッチしないことを指定できます。
クライアント・アプリケーションを使用してサーバーからプロパティー・データをフェッチする場合、以下の 3 つの目標を考慮してください。
- 必要なすべてのデータのフェッチに必要なサーバーへのラウンド・トリップ回数と、サーバーとクライアントが各フェッチを処理するために必要なリソースの数とのバランスを取ること。
- 不要なデータのフェッチによってパフォーマンスの効率が低下するのを防ぐこと。
- フェッチするデータの不足による API_PROPERTY_NOT_IN_CACHE 例外の発生を防ぐこと。
最も効率的であるとは限りませんが、これらの目標を達成する最も簡単な方法は、プロパティー・フィルターをまったく使用しないことです。これは、プロパティー・フィルターが API メソッド・パラメーターとして指定されている場合には常に、null を渡すことで実現します。fetch メソッドの呼び出し時にプロパティー・フィルターを省略すると、クライアント・アプリケーションはオブジェクトのすべてのスカラー (非オブジェクト) プロパティーと、すべてのオブジェクト値プロパティーのプレースホルダーをフェッチします。したがって、その後に試行されるオブジェクト値プロパティーの読み取りでは、オブジェクト値をフェッチする自動リモート呼び出しが行われることになります。すべてのスカラー・プロパティーがローカル・プロパティー・キャッシュに既に存在するため、API_PROPERTY_NOT_IN_CACHE エラーは発生しません。ローカル・プロパティー・キャッシュにないオブジェクト値プロパティーの要求は、Content Engine によって自動的に処理され、サーバーからオブジェクト値がフェッチされます。プロパティー・フィルターを使用しないと、最終的にすべてのプロパティー値が取得され、1 つのオブジェクトから次のオブジェクトへのナビゲーションが可能になりますが、サーバーへのリモート呼び出しが増加するため、パフォーマンスに影響する可能性があります。したがって、効率とクライアント・アプリケーションの処理速度を最大限にする場合は、オブジェクト・プロパティーのフェッチ時にプロパティー・フィルターを使用してください。プロパティー・フィルターにより、パフォーマンスを最適化するのに役立つ緻密な制御が可能になりフィードバックが得られます。
fetchProperty または refresh メソッドを使用してサーバーからオブジェクト値プロパティーをフェッチする (またはフェッチしない) 方法は、以下の 3 つです。
- プロパティーをプロパティー・フィルターに指定します。プロパティーのオブジェクト値がサーバーからフェッチされ、ローカル・プロパティー・キャッシュにロードされます。プロパティーを読み取るための getter アクセサー・メソッド呼び出しにより、ローカル・プロパティー・キャッシュからオブジェクト値が取得されます。
- プロパティー・フィルターを使用しません。プロパティーのオブジェクト値はフェッチされませんが、後でフェッチするよう設定されます。すなわち、値は参照オブジェクトまたは未評価オブジェクトとしてプロパティー・キャッシュに保管されます。プロパティーを読み取るための getter アクセサー・メソッド呼び出しにより、自動的にサーバーへのラウンド・トリップが発生してオブジェクト値がフェッチされ、それが呼び出し側に返されます。プロパティーを読み取るための後続の getter アクセサー・メソッド呼び出しにより、プロパティー・キャッシュから値が直接取得されます。詳細については、PropertyState 定数クラスを参照してください。
- プロパティー・フィルターを使用しますが、プロパティーを含むように指定しないか、除外するように指定します。プロパティーのオブジェクト値はフェッチされず、後でフェッチされるようにも設定しません。プロパティーを読み取るための getter アクセサー・メソッド呼び出しにより、API_PROPERTY_NOT_IN_CACHE 例外が発生します。
例えば、クライアント・アプリケーションで Document.get_Reservation を呼び出して Reservation プロパティーの予約オブジェクト値を読み取る場合、前のセクションで説明したように、結果はプロパティーがどのようにフェッチされたか (またはフェッチされなかったか) によって決まります。
- ローカル・プロパティー・キャッシュから予約オブジェクトが取得されます。
- ローカル・プロパティー・キャッシュに予約オブジェクトは存在しませんが、サーバーへのラウンド・トリップが自動的に行われて予約オブジェクトがフェッチされ、それが返されます。後続の Document.get_Reservation への呼び出しでは、サーバーからではなく、ローカル・プロパティー・キャッシュから直接予約オブジェクトが取得されることに留意してください。
- ローカル・プロパティー・キャッシュに予約オブジェクトが存在しません。すなわち、サーバー・アクセスは試行されず、API_PROPERTY_NOT_IN_CACHE 例外が返されます。
サーバーへのラウンド・トリップを最小限に抑えたい、パフォーマンスに依存するアプリケーションでは、特にオブジェクト参照 (すなわち、クラスまたはオブジェクト ID) のみが必要な場合に、オブジェクト値プロパティーに別の方法でアクセスすることが望まれる場合があります。通常、アプリケーションがプロパティー・フィルターを使用しない場合、オブジェクト値プロパティーの参照はプロパティー・キャッシュに入れられ、その参照は (サーバーへのラウンド・トリップにより) オブジェクト全体を取得するために使用されます。この追加のラウンド・トリップは、プロパティーのオブジェクト参照のみにアクセスすることで実行せずに済みます。 次に例を示します。
PropertyEngineObject peo =
(PropertyEngineObject)Document.getProperties().get(PropertyNames.RESERVATION); ObjectReference
reservationRef = peo.getObjectReference();
プロパティー・フィルターの構造
プロパティー・フィルターは PropertyFilter オブジェクトと 1 つ以上のフィルター・エレメントから構成されます。各フィルター・エレメントは FilterElement オブジェクトによって表されます。各フィルター・エレメントは、プロパティー・フィルターに (識別子またはタイプのいずれかで) プロパティーを追加する仕様を表します。フィルター・エレメントを作成して識別子でプロパティーを指定するには、PropertyFilter.addIncludeProperty メソッドを呼び出します。フィルター・エレメントを作成してタイプでプロパティーを指定するには、PropertyFilter.addIncludeType メソッドを呼び出します。特定の addIncludeProperty または addIncludeType メソッドのどちらを呼び出すかに応じて、FilterElement オブジェクトを作成してそれをパラメーターとして指定するか、メソッドのパラメーターに指定する情報に基づいてサーバーに FilterElement オブジェクトを作成させるかを選択できます。さらに、PropertyFilter.addExcludeProperty メソッドを呼び出すことにより、1 つ以上のプロパティーを除外するよう明示的に指定することができます。
PropertyFilter オブジェクト
PropertyFilter オブジェクトには以下のコンポーネントがあります。
- ゼロまたは複数の IncludeProperty 仕様。それぞれ、サーバーから取得する 1 つ以上のプロパティーを識別子で指定します。IncludeProperty 仕様を作成するには、addIncludeProperty メソッドのいずれかを呼び出します。各 IncludeProperty 仕様は FilterElement オブジェクトにパッケージ化され、取得するプロパティーを指定し、オプションで maxSize、maxRecursion、levelDependents、および pageSize 属性を指定します。また、該当する PropertyFilter メソッドを使用して、これらの属性にグローバル・デフォルト値を設定することもできます。
- ゼロまたは複数の IncludeType 仕様。それぞれ、サーバーから取得するプロパティーをタイプで指定します。プロパティー・タイプの仕様は、FilteredPropertyType 定数のいずれかに設定されます (例えば FilteredPropertyType.ANY_SINGLETON。これは単一カーディナリティーのすべてのプロパティーを指定します)。IncludeType 仕様を作成するには、addIncludeType メソッドのいずれかを呼び出します。各 IncludeType 仕様は FilterElement オブジェクトにパッケージ化され、取得するプロパティーのタイプを指定し、オプションで maxSize、maxRecursion、levelDependents、および pageSize 属性を指定します。また、該当する PropertyFilter メソッドを使用して、これらの属性にグローバル・デフォルト値を設定することもできます。
- ゼロまたは複数の ExcludeProperty 仕様。それぞれ、サーバーからの取得で除外する 1 つ以上のプロパティーを識別子で指定します。除外に指定したすべてのプロパティーは、IncludeProperty または IncludeType 仕様に指定されたプロパティーを上書きします。ExcludeProperty 仕様を作成するには、addExcludeProperty メソッドを呼び出し、除外するプロパティーのシンボル名または GUID 文字列識別子のスペース区切りリストを指定します。
通常、アプリケーションのプロパティー・フィルターでは ExcludeProperty 仕様ではなく IncludeProperty または IncludeType 仕様を使用してください。これは、IncludeProperty または IncludeType 仕様の方が、どのプロパティーを返すかをより細かく制御できるためです。ExcludeProperty 仕様ではオブジェクトに後から追加された可能性がある新規プロパティーの取得を防げませんが、IncludeProperty (または IncludeType) 仕様では固定のプロパティー・セットのみが取得されます。オブジェクトに後から追加された新規プロパティーは、取得されるには明示的に IncludeProperty 仕様に追加する必要があります。
PropertyFilter オブジェクトには、プロパティーの取得方法を制御する設定可能な属性があります。これらの属性は、PropertyFilter オブジェクトのグローバル・デフォルト値になります。addIncludeProperty または addIncludeType メソッドを呼び出すときに、個々の FilterElement オブジェクトに対するこれらの各属性を上書きできます。FilterElement オブジェクトに指定されていないすべての属性には、PropertyFilter オブジェクトのグローバル属性値が適用されます。グローバル値が指定されていない場合は、デフォルト値が適用されます。該当する PropertyFilter メソッドを使用して、以下の各属性を設定できます。
- levelDependents: 依存オブジェクトの取得時に使用する再帰レベルが、所属先の独立オブジェクトの再帰レベルと同じ (true) か 1 レベル深い (false) かを指定するブール値。この値は setLevelDependents メソッドを使用して設定します。詳細については、「依存オブジェクト」を参照してください。
- maxRecursion: プロパティーの関係の取得時に使用する、許容される再帰の最大深度を指定する、ゼロを基準とした整数値。この属性は、プロパティーを含める深さを決定します。値を指定しない場合、デフォルトはゼロです。この値は setMaxRecursion メソッドを使用して設定します。詳細については、「プロパティーの再帰」を参照してください。
- maxSize: コンテンツ・データを保持するプロパティーの取得時に返されるコンテンツ・データの最大サイズをバイト単位で指定する長整数値。取得されるプロパティーが保持するコンテンツ・データの量がこのサイズを超える場合、返されるコンテンツ・データはありません。値を指定しない場合、デフォルトで、データ量の多さに関係なくすべてのコンテンツ・データが返されます。この値は setMaxSize メソッドを使用して設定します。
- pageSize: PropertyIndependentObjectSet プロパティーによって返される独立オブジェクト・セットのイテレーター・ページ・サイズを指定する整数値。イテレーター・ページ・サイズは、各フェッチ時に取得される独立オブジェクト・セットのエレメントの数を決定します。ページ・サイズを指定しない場合、デフォルトで、サーバーは ServerCacheConfiguration オブジェクトの QueryPageDefaultSize プロパティーの値を使用します (このプロパティーのデフォルト値は 500)。ページ・サイズが ServerCacheConfiguration オブジェクトの QueryPageMaxSize プロパティーの値 (このプロパティーのデフォルト値は 1000) を超える場合、サーバーは代わりに QueryPageMaxSize プロパティーの値を使用します。この値は setPageSize(int pageSize) または setPageSize(java.lang.Integer pageSize) メソッドを使用して設定します。
パラメーターとして PropertyFilter オブジェクトを使用するすべてのメソッドについては、『Java API Reference』資料の「Use from the header of the PropertyFilter class」のトピックを参照してください。
FilterElement オブジェクト
各 FilterElement オブジェクトでは、1 つ以上のプロパティーを識別子 (シンボル名または GUID 文字列識別子) またはタイプで指定できます。ID でプロパティーを指定する場合、FilterElement オブジェクトを作成するには、該当するコンストラクターの値パラメーターをシンボル名または GUID 文字列識別子の文字列区切りリストに設定します。タイプでプロパティーを指定する場合、FilterElement オブジェクトを作成するには、該当するコンストラクターの値パラメーターをタイプの文字列区切りリストまたは FilteredPropertyType 定数に設定します。
さらに、FilterElement オブジェクトには、プロパティーの取得方法を制御する設定可能な属性があります。これらの属性は、関連する PropertyFilter オブジェクトで指定された可能性があるグローバル属性をすべて上書きし、特定の FilterElement オブジェクトで取得が決定されたプロパティーにのみ適用されます。FilterElement オブジェクト属性が設定されていない場合、代わりに PropertyFilter オブジェクトのグローバル属性値が使用されます。グローバル値が指定されていない場合は、デフォルト値が適用されます。以下の属性は、FilterElement コンストラクターのパラメーターか、PropertyFilter オブジェクトの addIncludeProperty または addIncludeType メソッドのパラメーターで設定します。
- levelDependents: 依存オブジェクトの取得時に使用する再帰レベルが、所属先の独立オブジェクトの再帰レベルと同じ (true) か 1 レベル深い (false) かを指定するブール値。この値は、FilterElement コンストラクターの levelDependents パラメーターか、PropertyFilter オブジェクトの addIncludeProperty または addIncludeType メソッドの levelDependents パラメーターで設定します。値を指定しない場合、PropertyFilter オブジェクトの levelDependents グローバル属性の値が使用されます。PropertyFilter と FilterElement のどちらの属性も指定しない場合、デフォルト値は false です。詳細については、「依存オブジェクト」を参照してください。
- maxRecursion: プロパティーの関係の取得時に使用する、許容される再帰の最大深度を指定する、ゼロを基準とした整数値。この属性は、プロパティーを含める深さを決定します。値を指定しない場合、デフォルトはゼロです。この値は、FilterElement コンストラクターの maxRecursion パラメーターか、PropertyFilter オブジェクトの addIncludeProperty または addIncludeType メソッドの maxRecursion パラメーターで設定します。値を指定しない場合、PropertyFilter オブジェクトの maxRecursion グローバル属性の値が使用されます。PropertyFilter と FilterElement のどちらの属性も指定しない場合、デフォルト値は 0 です。詳細については、「プロパティーの再帰」を参照してください。
- maxSize: コンテンツ・データを保持するプロパティーの取得時に返されるコンテンツ・データの最大サイズをバイト単位で指定する長整数値。取得されるプロパティーが保持するコンテンツ・データの量がこのサイズを超える場合、返されるコンテンツ・データはありません。この値は、FilterElement コンストラクターの maxSize パラメーターか、PropertyFilter オブジェクトの addIncludeProperty または addIncludeType メソッドの maxSize パラメーターで設定します。値を指定しない場合、PropertyFilter オブジェクトの maxSize グローバル属性の値が使用されます。PropertyFilter と FilterElement のどちらの属性も指定しない場合、デフォルトで、データ量の多さに関係なくすべてのコンテンツ・データが返されます。
- pageSize: PropertyIndependentObjectSet プロパティーによって返される独立オブジェクト・セットのイテレーター・ページ・サイズを指定する整数値。イテレーター・ページ・サイズは、各フェッチ時に取得される独立オブジェクト・セットのエレメントの数を決定します。この値は、FilterElement コンストラクターの pageSize パラメーターか、PropertyFilter オブジェクトの addIncludeProperty または addIncludeType メソッドの pageSize パラメーターで設定します。値を指定しない場合、PropertyFilter オブジェクトの pageSize グローバル属性の値が使用されます。PropertyFilter と FilterElement のどちらの属性も指定しない場合、デフォルトで、サーバーは ServerCacheConfiguration オブジェクトの QueryPageDefaultSize プロパティーの値を使用します (このプロパティーのデフォルト値は 500)。ページ・サイズが ServerCacheConfiguration オブジェクトの QueryPageMaxSize プロパティーの値 (このプロパティーのデフォルト値は 1000) を超える場合、サーバーは代わりに QueryPageMaxSize プロパティーの値を使用します。
プロパティーの優先順位ルール
プロパティーが複数の方法で指定された場合に考えられる競合を解決するために、以下のプロパティー・フィルターの優先順位ルールが適用されます。
- ExcludeProperty 仕様に指定されたプロパティーは、IncludeProperty または IncludeType 仕様に指定されたプロパティーをオーバーライドします。すなわち、ExcludeProperty 仕様で除外するよう指定されたプロパティーと IncludeProperty または IncludeType 仕様で包含するよう指定されたプロパティーが同じである場合、そのプロパティーは除外されます。
- プロパティーが IncludeProperty および IncludeType 仕様の両方で指定された場合、IncludeProperty 仕様の属性のみが適用されます。
- 1 つのプロパティーが同じ方法で複数回指定された場合、最初に示されるプロパティーの属性が適用されます。
- 1 つのプロパティー・タイプが複数の方法で指定された場合 (例えば、FilteredPropertyType.SINGLETON_STRING を指定する IncludeType 仕様と、FilteredPropertyType.ANY_SINGLETON を指定する別の IncludeType 仕様を持つ PropertyFilter オブジェクト)、最も具体的な IncludeType 仕様の属性のみが適用されます (前述の例では SINGLETON_STRING 仕様)。
- 2 つのフィルター・エレメントが同じプロパティーと一致する場合、最も具体的なフィルター・エレメントが使用されます。したがって、フェッチされたオブジェクトのプロパティーが、プロパティー名を指定するフィルター・エレメントとプロパティー・タイプを指定する別のフィルター・エレメントの両方に一致する場合、プロパティー名フィルター・エレメントとその属性が使用されます。同様に、プロパティーが 2 つのプロパティー・タイプ・フィルター・エレメントに一致する場合、より具体的なフィルター・エレメントが使用されます。例えば、プロパティー・タイプ「*」ではなく、プロパティー・タイプ「String」が選択されます。
プロパティーの再帰
maxRecursion 属性を使用するには、Content Engine オブジェクトにおけるプロパティーの再帰の概念を理解する必要があります。Content Engine オブジェクト・プロパティーは、他のオブジェクトを参照するプロパティーを持ち、さらにそのプロパティーは独自のプロパティーを持つ、ということが可能です。これは、1 つ以上のオブジェクト値プロパティーを持つ単一の Content Engine オブジェクトをフェッチすると、結果として多数の追加プロパティーが返される場合があることを意味します。フェッチするプロパティーの数を制御するには、プロパティー・フィルターを使用して、プロパティーの関係の再帰深度をクライアントで定義できるようにします。サーバーは、オブジェクトのオブジェクト値プロパティーで形成されたオブジェクト・ツリーを処理するときに、各オブジェクトの現在の再帰レベル を追跡します。現在の再帰レベルは最初にフェッチされたオブジェクトの 0 から始まり、親オブジェクトのオブジェクト値プロパティーから返される子オブジェクトごとに 1 ずつ増えます。
例えば、フォルダー内に格納された予約付きのドキュメントがあるとします。オブジェクト値プロパティーから返されるオブジェクト間の親子関係を表すためにインデントを使用すると、以下のようになります。
Document object #1
Reservation: Returns Document object #2
FoldersFiledIn: Returns a collection of Folder objects
上の例で、Reservation プロパティーが返すのは、元の Document オブジェクトの子オブジェクトである Document オブジェクトであり、FoldersFiledIn プロパティーが返すのは、Reservation オブジェクトの子オブジェクトである Folder オブジェクト のコレクションです。サーバーは、オブジェクト・ツリーをナビゲートするときに、現在の再帰レベルを追跡します。この再帰レベルは最初は 0 であり、処理される子オブジェクトごとに 1 つ増えます (ただし、後述するように levelDependents 属性が true に設定されていない場合)。したがって、この例でオブジェクトが維持する各サーバーの現在の再帰レベル (大括弧で示します) は、以下のようになります。
- Document オブジェクト #1 [0]: 最初にフェッチされたオブジェクト
- Document オブジェクト #2 [1]: Document オブジェクト #1 の子オブジェクト
- Folder オブジェクト [2]: Document オブジェクト #2 の子オブジェクト
サーバーによってフェッチされるプロパティーを IncludeProperty または IncludeType 仕様での一致により選択する場合、サーバーは使用する正しい maxRecursion 属性値を以下のようにして決定します。
- IncludeProperty または IncludeType 仕様内の FilterElement オブジェクトに maxRecursion 値が指定された場合、その値が使用されます。
- 値が指定されていない場合、PropertyFilter オブジェクトの getMaxRecursion メソッドで返される maxRecursion グローバル属性の値が使用されます。
- FilterElement オブジェクトの maxRecursion 属性と PropertyFilter オブジェクトの maxRecursion グローバル属性がどちらも null である場合、デフォルト値は 0 です。
プロパティーのフェッチ時に、プロパティーのプロパティー・タイプと、プロパティーが属するオブジェクトの現在の再帰レベルに基づいて、サーバーによって以下の比較が行われます。
スカラー (非オブジェクト) プロパティー
- 現在の再帰レベルが maxRecursion 属性に指定された再帰レベル以下である場合、スカラー・プロパティーの値が返されます。
- その他の場合、スカラー・プロパティーの値は返されません。フェッチしようとすると、API_PROPERTY_NOT_IN_CACHE エラーが生成されます。
オブジェクト値プロパティー
- 現在の再帰レベルが maxRecursion 属性に指定された再帰レベルより下である場合、オブジェクト値プロパティーで指定されたオブジェクトが返されます。
- 現在の再帰レベルが maxRecursion 属性に指定された再帰レベルと等しい場合、プロパティーのオブジェクト値はフェッチされませんが、後でフェッチされるよう設定されます。すなわち、値は参照オブジェクトまたは未評価オブジェクトとしてプロパティー・キャッシュに保管されます。プロパティーを読み取るための getter アクセサー・メソッド呼び出しにより、自動的にサーバーへのラウンド・トリップが発生してオブジェクト値がフェッチされ、それが呼び出し側に返されます。プロパティーを読み取るための後続の getter アクセサー・メソッド呼び出しにより、プロパティー・キャッシュから値が直接取得されます。
- 現在の再帰レベルが maxRecursion 属性に指定された再帰レベルより上である場合、オブジェクト値プロパティーで指定されたオブジェクト値は返されません (フェッチしようとすると、API_PROPERTY_NOT_IN_CACHE エラーが生成されます)。
maxRecursion 属性の使用方法を示すコード例については、「プロパティーの操作」を参照してください。
依存オブジェクト
依存オブジェクトはその親の独立オブジェクトに属し、その所属先独立オブジェクトが保存される場合にのみ永続化できます。依存オブジェクトは、EngineObject クラスのサブクラスからインスタンス化されるオブジェクトですが、独立オブジェクトとは異なり、IndependentObject クラスのサブクラスではありません。依存オブジェクトは、親オブジェクトからのみ取得できます。依存オブジェクトには独自のセキュリティー属性がないため、その親の独立オブジェクトを検査してアクセス権を確認する必要があります。
levelDependents 属性は、依存オブジェクト・コレクションのエレメントの再帰レベルを明示的に制御します。通常、依存オブジェクト・コレクションのエレメントは現在の再帰レベルで評価されます。この再帰レベルは、エレメントを含むオブジェクトより 1 レベル深くなっています。ただし、levelDependents 属性が true である場合、依存オブジェクト・エレメントは、それが含まれるオブジェクトと同じ再帰レベルで評価されます。
通常、依存オブジェクトは親オブジェクトとともにフェッチされるため、親オブジェクトに属する依存オブジェクトをすべて取得する簡単な方法は、levelDependents 属性を true に設定することです。これにより、サーバーは常に現在の再帰レベルを増やさずに依存オブジェクトを行き来するようになります。
サーバーによってフェッチされるプロパティーを IncludeProperty または IncludeType 仕様での一致により選択する場合、サーバーは使用する正しい levelDependents 属性値を以下のようにして決定します。
- IncludeProperty または IncludeType 仕様内の FilterElement オブジェクトに levelDependents 値が指定された場合、その値が使用されます。
- 値が指定されていない場合、PropertyFilter オブジェクトの getLevelDependents メソッドで返される levelDependents グローバル属性の値が使用されます。
- FilterElement オブジェクト属性と PropertyFilter オブジェクトの levelDependents グローバル属性がどちらも null である場合、デフォルト値は false です。
依存オブジェクトに独立オブジェクトを返すプロパティーが含まれる場合、levelDependents 属性はその独立オブジェクトに適用されません。
levelDependents 属性の使用方法を示すコード例については、「プロパティーの操作」を参照してください。