Object Store Concepts

The IBM FileNet® P8 domain can have one or more object stores. An object store represents a location within an IBM FileNet P8 domain on the Content Engine server in which objects are stored, accessed, and managed. An object store is used to store a related set of data, which can be grouped by type. For example, one object store could contain email messages, and another could contain home loan information. The important distinction is that different object stores can contain data for different applications, with different metadata. In our example, the object store for email could have an "email" class of documents that contains "subject", "from", and "to" properties. The object store for home loans could have a "loan" class of documents that has "total amount" and "interest rate" properties. Another alternative is to use object stores to group data chronologically. For example, a new email object store could be created every year. Then to delete emails older than seven years, entire object stores older than seven years could be deleted. The benefit of chronological grouping is that deleting an entire object store is much faster than deleting all of the individual objects in an object store.

Typically, a system administrator creates object stores on the Content Engine server using FileNet Enterprise Manager, the built-in Content Engine administrative tool. (FileNet Enterprise Manager is installed as part of a typical Content Engine installation and the first object store is created during installation of FileNet P8 Platform software. For more information, see Administrative tools and About Enterprise Manager in the Content Engine Administration help and the IBM FileNet P8 Platform Installation and Upgrade Guide.) Each object store is represented in the Content Engine API as an instance of an ObjectStore class.

A set of ObjectStore objects is represented by an ObjectStoreSet collection object. The main use of an ObjectStoreSet collection is for displaying a list of available object stores to a user, or for getting a reference to an object store within the collection. Generally, you'll work with a single object store. An exception is when you execute searches, which can be directed to search across multiple object stores. (For more information, see Query Concepts.)

ObjectStore Object

An ObjectStore object provides access to metadata and to collections of objects (such as documents, folders, and class descriptions) that are saved in the object store. As with most other types of objects, you can use static methods on the Factory inner classes to create instances of ObjectStore, although as mentioned above, the most common way of creating an object store is to use the Create Object Store wizard in the FileNet Enterprise Manager administrative tool. For information on programmatically instantiating an ObjectStore object or an ObjectStoreSet collection, refer to the reference help for the Factory.ObjectStore class, the Domain interface, and the RepositoryObject subclass and to the Working with Object Stores section of this guide.

In most cases when using Factory methods such as createInstance and fetchInstance to create or retrieve instances of known object types that reside in an object store, you must specify the object store as a parameter to the method. Calling the save method on the returned object saves it in the specified object store. If you don't have prior knowledge of the object type, you can use the methods on the InstantiatingScope interface to create or retrieve objects. See the Scoping topic and the reference help for InstantiatingScope for more information.

Properties

You can call the getProperties method to access the set of properties (a Properties collection) currently held by the ObjectStore reference. You can also call methods to retrieve the values of individual properties. In some cases, you can retrieve objects via method calls that retrieve the values of object-valued properties, such as get_Site.

To update the Properties collection of an ObjectStore object, set the property values you wish to update, then call save on the ObjectStore object. For more information about properties, see the Property interface reference help, and the Property Concepts and Working with Properties topics in this guide.

Retrieving Information from the Object Store

You can call methods on the ObjectStore interface to retrieve information about the object store. Methods are available to provide the following configuration information about the object store:

The above list represents only some of the information available to you on the ObjectStore interface. For more information, see the reference help for the interface.

Security

Security on the object store itself is distinguished from security on objects that are stored in the object store. Applying security on the object store occurs when the system administrator creates the object store using the IBM FileNet Enterprise Manager. At creation time, you specify the users and groups who will be object store administrators and those who will have non-administrative (end user) access rights. By default, administrators receive full control access rights on the object store and all securable objects contained within it; non-administrative users receive access rights to the object store that allow them to browse directories and read documents. (See Object Store access rights in the Enterprise-wide Administration help for more information.) The access rights specified at creation time are used to set the permissions for all of the class definitions that get created. It is highly recommended that, rather than specifying individual users when setting security at object store creation time, you add at least one group for administrators (for example, "CEAdmins") and one group for users during object store creation. You can then easily grant or remove access to an object store by modifying the group (such as adding or removing members) without having to modify individual class definitions.

You can programmatically retrieve and set access rights for the objects contained within an object store. A collection of access rights (represented within the Content Engine API as an AccessPermissionList) control a user's ability to store an object, delete an object, and so on. For more information, refer to Security Concepts and Working with Security. You can also refer to the IBM FileNet P8 Security help for more information about security features.

In addition to the typical access rights you might grant to administrators and to users working with objects, you can assign special object store access rights to a select user or group of users who run certain types of system-level applications, such as import/export tools, migration utilities, and federation tools. A user or group granted this “Privileged Write” access is allowed to set the following system-level properties: Creator, DateCreated, LastModifier, and DateLastModified. System-level tools such as those mentioned above might need to modify these properties, so the users who run the tools must accordingly be granted an elevated level of permission. Note that the Creator and DateCreated properties can only be set at object creation time and then only by users who have been granted privileged write access. For additional information about the privileged write access right and affected properties, see "Settable System Properties" under Property Concepts. For a code sample, see Setting Privileged Write Access on an Object Store.

Important:  Do not grant the AccessRight.PRIVILEGED_WRITE permission to ordinary users and groups or even to most administrators. You must explicitly grant this access right; and you should grant it only to those users or groups who need this special kind of access. For this reason, this access right is not included in the full control level of object store access (AccessLevel.FULL_CONTROL_OBJECT_STORE).

For additional information about the privileged write access right and affected properties, see "Settable System Properties" under the Property Concepts section.

In addition to privileged write permissions, another type of privileged access is AccessRight.WRITE_ANY_OWNER. Granting a user WRITE_ANY_OWNER permission implicitly gives that user WRITE_OWNER permission on all objects in the object store. That user can read all objects and set the owner to himself, thus also obtaining the ability to read and write ACLs.

Important:  AccessLevel.FULL_CONTROL_OBJECT_STORE includes AccessRight.WRITE_ANY_OWNER. Just as you would restrict the users to whom you grant privileged write access, you should not grant AccessRight.WRITE_ANY_OWNER, either through direct assignment or implicit assignment (via AccessLevel.FULL_CONTROL_OBJECT_STORE) to general users or groups.