Getting Started

Developer Requirements

To begin your development, you must have certain versions of the framework software that support your development environment and language. See the following topics for the steps you need to take for setting up various development environments:

• Setting Up a Thick Client Development Environment for setting up a development environment when your client machine is running outside of the application server environment. All of the supported application servers and transport protocols are addressed.
• Setting Up a Thin Client Application Development Environment Using EJB Transport
• Setting Up a Thin Client Application Development Environment Using CEWS Transport

The Sample IDE Setups topic contains samples that show you how to set up integrated development environment (IDE) projects for client FileNet P8 application development. Samples are provided for the Eclipse IDE and the Microsoft Visual Studio IDE and address development environments on all of the supported application servers.

Content Engine API Compatibility with Server Versions

Client applications that use version N of the Content Engine APIs are supported against Content Platform Engine server version N and version N+1. This API support policy does not extend to server versions N+2 or higher. An application that uses a newer API version is not supported against an older server version.

To ensure compatibility with new Content Platform Engine server versions, it is recommended that client applications use the Content Engine Client Download Service. The Content Engine Client Download Service enables you to build version-compatibility checks and automatic updates into client applications. For more information, see Content Engine Client Download Service.

Starting with the 5.2.1 version of the Content Platform Engine server, the Content Engine Java API includes the Cross-Release Class Loading (CRCL) feature, allowing a single instance of a Java application to connect to multiple Content Platform Engine server releases simultaneously, including server versions that are older than the application's Content Engine API. For more information, see Developing a Cross-Release Application.

Finding Required Files

You can get the development-support files by running the Content Platform Engine Client Installer, which is included with the Content Platform Engine. To install the Content Engine Client files that you need for application development, select the Other Applications option from the installer's Select FileNet P8 Applications window.

Required Java and .NET Versions

The Content Engine APIs require certain minimum levels of the Java 2 Standard Edition (J2SE) and Microsoft .NET Framework environments. For information on these requirements, see IBM® FileNet P8 Hardware and Software Requirements.

Required Java Archive (JAR) Files

The Content Engine Java API requires several other JAR files (including third-party JAR files) during run time. The required JAR files are installed with the Application Engine software. The supplied versions of these JAR files are required; do not substitute other copies of JAR files with the same names. (For specific installation instructions for your environment, see Installing or upgrading IBM FileNet P8 .) If you are writing a stand-alone Java application that uses the Content Engine Java API, the required JAR files must be in your class path. A missing JAR file can lead to errors and "class not found" exceptions. The following table lists the required JAR files according to your transport option, Content Engine Web Service (CEWS) or Enterprise JavaBeans (EJB).

Required .NET Components

The Content Engine .NET API supports Microsoft Windows Communication Foundation (WCF) and maintains compatibility with earlier versions of Microsoft Web Services Extensions (WSE) 3.0. However, WSE support is deprecated and support will be discontinued in a future release. For this reason, continued use of WSE is discouraged.

If you have applications that were developed for a .NET Framework with WSE that you want to run in a .NET Framework 3.0 with WCF, you must update their authentication mechanisms. For more information, see Upgrading Custom Applications.

To begin development with the Content Engine .NET API, you install the Microsoft .NET Framework 3.0 or later (WCF is built in to this framework). This environment allows you to create your own custom applications.

To develop applications that use the Microsoft Visual Studio .NET API, you must first add a reference in your project to the .NET API. In the Visual Studio Add Reference dialog, select the Browse tab and navigate to <drive>:\Program Files\FileNet\Content Engine\. From this folder, select the entry FileNet.Api.dll and click OK. You can now use the Content Engine .NET API from your project.

Java Packages and .NET Namespaces

Usually, public Java packages and .NET namespaces map to one another in functionality. However, where the functionality of a Java package has no equivalent in the .NET environment, or vice versa, the column is marked as N/A (not applicable). The following table lists the Java packages and .NET namespaces, with brief descriptions.

Transport Protocols

The Content Platform Engine supports three basic transport protocols: Enterprise Java Beans (EJB), Web Service for Content Engine and for Process Engine, and HTTP for Process Engine. The following diagram shows the interaction of these protocols with the Content Platform Engine.

The following section focuses on the transport protocols that are used by the Content Engine. For information about the Process Engine, see Process Java Developer's Guide, Process Engine Web Service, and Process Engine REST Service.

EJB

The Content Platform Engine implements its functionality through the EJB container layer of the Java Platform, Enterprise Edition application server. The EJB protocol (often RMI-IIOP based) passes serialized Java objects across the network for requests/responses to/from the Content Platform Engine server. The Content Engine Java API configured to run over the EJB transport is often the fastest interface available in FileNet P8 , but relative performance is use case dependent.

The EJB Listener provides a private EJB interface (not available to API callers) to the Content Engine, and provides both local and remote interfaces. The local interface is used by Java Platform, Enterprise Edition components that are bundled with the Content Engine EAR file (deployed to the application server). The remote interface is used by a remote Java API. The EJB interface is leveraged by the Content Engine Java API. It leverages the application server provided protocols for communicating between server nodes and for providing automatic propagation of security and transaction contexts.

Content Engine Web Service

The Content Engine Web Service (CEWS) transport is based on the SOAP protocol. The CEWS transport is the only means by which the .NET API can access the Content Engine. In addition to the EJB transport, the Java API can also access the Content Engine by using the CEWS transport. Content Engine objects are represented in XML, which are serialized and passed across the network over HTTP from the client application to the Content Engine.

The CEWS Listener is implemented as a servlet that runs in the Web container layer of the Java Platform, Enterprise Edition application server. Except for transaction propagation and differences in available authentication methods, the CEWS layer exposes the same Content Engine functionality to Web service clients as the EJB layer exposes to Java clients by providing a pure Web services-based interface to the Content Engine server. The CEWS Listener forwards Web services calls to the EJB layer to access the Content Engine.

Transport Selection

You can specify either the EJB or CEWS transport when you establish a connection to the Content Engine server. A Connection object represents a logical connection to a FileNet P8 domain and holds the Universal Resource Identity (URI) for the connection. The URI carries the information that is required to establish a connection to the Content Engine server, such as the transport protocol, host, and port that is used for server communication.

A Content Engine Java API-based client determines which transport to use to communicate with the server. It selects the transport based on the URI parameter when it creates a Connection object.

See Getting a Connection for examples.

Transport Differences

There are differences to note when you are using one transport protocol versus the other:

• For Java clients, the EJB protocol requires different JAR files than the SOAP protocol. For more information, see the list of required JAR files in Required Java Archive (JAR) Files.
• Different configurations might be required. If the default authentication behavior is not sufficient, it might be necessary to use a different stanza in a JAAS configuration file. A Content Engine Java API-based client determines which transport to use to communicate with the server, and which endpoint to communicate with, based on the URI specified in the Connection object. These examples are only two examples of configuration differences that might affect you based on your choice of transport. For more information about configuration files, see Client Configuration for more information about configuration files.
• The EJB transport supports JAAS security propagation; the CEWS transport does not.
• The EJB transport supports client-initiated transactions through calls from the Java API only; the CEWS transport does not support client-initiated transactions. There is no mature industry standard for propagating a transaction context in a web service request. For this reason, if you are using the CEWS transport, setting the value of ConfigurationParameter.CONNECTION_PARTICIPATES_IN_TRANSACTION to true to indicate that your connection participates in a transaction causes a runtime exception. (To set up transaction support for your Java client application, see CONNECTION_PARTICIPATES_IN_TRANSACTION in the Java API reference help.)

Client Configuration

Several client-side configuration-related files are installed by the Content Engine installation process. These files have default values that you can modify with a text editor for your environment. You can programmatically change some of the values within certain files, and those changes override the value that is specified in the configuration file. For more information, see the Configuration class and the ConfigurationParameter class.

For Java applications, you are assumed to have a JAAS login context that is configured with Java Runtime Environment (JRE) in place. The Content Engine Java API depends on JAAS for authentication.

Configuration Files

Depending on whether you have a Java or a .NET client environment, you have access to specific files for configuring your client environment.

.NET configuration files

The app.config file (or web.config for ASP.NET applications) is an application-specific configuration file that contains XML statements that specify the parameters to be used for your application. (Note that the use of this file for a .NET application is optional. If this file is not present, the recommended defaults are used.) You must rename this file to match the .NET application to which it applies. For information about the app.config file, refer to the "Application Configuration Files Explained" article in the Microsoft MSDN documentation.

A section named "filenet.api" is available in which to set configuration parameters for your FileNet P8 application. The contents of the following section represent the settings for such things as the number of concurrent upload threads, block size of the content chunks to use for uploading content, trace logging options, metadata caching parameters, and so on. The keys that you use to set the values map to ConfigurationParameter enumerations. For example, the key cmc enabled maps to the ConfigurationParameter.CMC_ENABLED constant.

The following app.config file example illustrates the "filenet.api" section:

 
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
     <section name="filenet.api" type="FileNet.Api.Util.FileNetConfigHandler, FileNet.Api, 
         Version=5.0.0.0, Culture=neutral, PublicKeyToken=63fc2fb3fdeef4f1" />
  </configSections>
  <filenet.api>
     <cmc enabled="true" timetolive="3000" />
     <connection fullwsspecheaders="true" />
     <content maxuploadthreads="4" putblocksizekb="1024" getblocksizekb="32" />
  </filenet.api>
</configuration>

You can also apply these settings globally by placing them into a system-wide machine.config file (or web.config file for ASP .NET applications). If you choose to do so, you must split the two sections (<section name="filenet.api"> and <filenet.api>) and merge them into different parts of the machine.config file. The app.config file has a <configSections> section with one entry, followed immediately by the <filenet.api> section. A machine.config file already has an existing <configSections> section that has many entries. To add this information to the machine.config file, you must insert the <section name="filenet.api"> section into the existing <configSections> area, and place the <filenet.api> section at an appropriate point that is separate from the <configSections> section. Although it does not need to be at the end of the file, it is typically placed there. For more information about the machine.config file, see your .NET developer documentation. In the following example, the <section name="filenet.api"> and <filenet.api> sections are inserted in separate locations):

<configuration>
   <configSections>
      <section name=... />
      <section name=... />
      ...
      <sectionGroup name=...>
         <section name=... /> 
         <section name=... />
      </sectionGroup>
      <section name=... /> 
       <section name="filenet.api" type=FileNet.Api.Util.FileNetConfigHandler, FileNet.Api, Version=5.0.0.0, 
         Culture=neutral, PublicKeyToken=63fc2fb3fdeef4f1" />
   </configSections>
   <configProtectedData ... >
      <providers>
      ...
      </providers>
   </configProtectedData>
   <runtime />
   <connectionStrings>
      ...
   </connectionStrings>
   <system.data>
      ...
   </system.data>
   <system.web>
      ...
   </system.web>
   <filenet.api>
   </filenet.api> 
</configuration> 

FileNet.properties file

This file, which is optional, contains entries for setting configuration values (see the types of configuration items in the ConfigurationParameter class). The following output is an example of two cache-management entries in a FileNet.properties file:

 
 FileNet.CMC.Enabled=true 
 FileNet.CMC.TimeToLive=300000
 

The API attempts to find the FileNet.properties configuration file in the following directories in the order that is shown:

• The current directory (Java system property user.dir)
• The user's home directory (Java system property user.home)
• The Java JVM home directory (Java system property java.home)

If the file is not found in one of those directories, the API tries to find it on the class path.

JAAS configuration files

The Content Engine Java API assumes that a JAAS context has been established prior to any issued requests. There is existing support for the username/password model through the UserContext class. Even when you are using that model, the client environment must include a proper JAAS configuration (the API does an internal JAAS login).

The Content Engine installation process creates a samples directory that contains samples of the JAAS configuration file for each supported application server environment: jaas.conf.WebSphere, jaas.conf.WebLogic, and jaas.conf.WSI. These sample files are not intended to be used as is. Use them as a guide in creating your own JAAS configuration. (Consult your JDK or application server documentation for precise details of creating a JAAS configuration.)

When you are using the EJB transport, the application server's normal JAAS configuration (or a site's customization of it) is sufficient. When you are using the CEWS transport, a FileNet-specific login module must be included in the JAAS configuration, whether you are establishing the JAAS login context outside of the API or you are using the legacy support in UserContext. That login module is of the following form when the CEWS transport is used:

tag {com.filenet.api.util.WSILoginModule REQUIRED;}; 

When you are using the legacy support in UserContext, you can supply a tag to indicate which JAAS stanza to use for the login. If you supply null, the API defaults to "FileNetP8". The normal overall JAAS fallback of "other" is used if "FileNetP8" is not present. You can also integrate the login module with existing JAAS configuration stanzas.

After you configure JAAS correctly, you can perform a JAAS login. For a code sample, see Obtaining a LoginContext.

JNDI configuration files

The jndi.properties file, which is not used with the CEWS transport, and is optional with the EJB transport, specifies the application server-specific JNDI InitialContextFactory class and provider URL. This file is a standard JNDI configuration mechanism and is not FileNet specific. If this file is not present, default values are used for its parameters. The values for the parameters can also be specified by using the java.naming.factory.initial and java.naming.provider.url system parameters.

Logging configuration files

Client API logging is controlled by an optional log4j configuration file, which might be in Java property file format or XML format (log4j.properties or log4j.xml). The installer provides a sample log4j.properties.client file (which must be renamed before use). Entries from that file can also be merged with an established site configuration file for log4j.

FileNet P8 Domain

The FileNet P8 domain represents a logical grouping of physical resources (such as object stores) and the Content Engine servers that provide access to those resources. It is also associated with one or more security realms for authorizing users. The resources of the domain share common attributes, such as marking sets and AddOns. In addition to sharing common attributes, the logical grouping also provides context by which cross-object store searches and updates can be conducted. Each resource, and each Content Engine server, belongs to only one domain. A Content Engine server can access any resource in the domain, but cannot access any resource that lies outside of its associated domain. For more information about the FileNet P8 domain, refer to the FileNet P8 Domains in the Content Engine Administration help.

The Global Configuration Database (GCD) contains definitions of the common set of attributes that control functional characteristics of the collection of resources and services for the FileNet P8 domain it represents. It provides general, hierarchical object storage and contains bootstrapping data and global configuration information for the FileNet P8 domain. The GCD defines domain resources, such as sites (and their related virtual servers and server instances), object store databases, full-text index areas, fixed content storage areas, content cache areas, AddOns, marking sets, and so on.

The Content Engine running inside an application server is the primary user of the GCD to, for example, retrieve the list of object stores or the connection information for a specific object store. The installation program is also a user of the GCD, running outside of an application server, to create a new FileNet P8 domain or join an existing FileNet P8 domain. The GCD, which might contain sensitive information, is secured such that only a specified principal (typically an administrator) or group of principals has read and write access to the data contained within it. Client-side application developers have access to objects that represent objects in the GCD, such as ObjectStore, Marking, MarkingSet, and AddOn objects.

FileNet P8 Domain Structure

From the FileNet P8 domain, you can access its structure by calling methods on the Domain object. The domain's structure consists of the following entities:

• Site - A domain can have one or more configured sites. Each site is identified by a unique name and has associated servers and resources (such as object stores, index areas, storage areas, and content caches). Associated resource objects in the same geographical area have the same Site property.

  When a Content Engine server in a geographically distributed environment processes a user request, it determines what resources it will need to process the request, and makes use of the site information in these resources to determine how best to process the request. The site information determines whether content retrievals and uploads are processed through a content cache, and whether the request is forwarded to a server in another site geographically closer to the resources required to process the request. Note that request forwarding is disabled for a Site by default unless explicitly enabled by setting its CanForwardRequests property. (For more information about request forwarding, see "Request Forwarding Concepts" in the Content Engine Administration documentation.) Note that request forwarding, if appropriate, is handled automatically by the server and requires no special action by the client application. The only influence a client has over this functionality is in the choice of URI with which the Connection is initialized.

  When the Content Engine server is initialized and the GCD created (typically when FileNet P8 is installed), a default instance of the Site class, called "Initial Site," is created and referenced by the Domain.DefaultSite property. As Virtual Servers, Server Instances, and resources (object stores, storage areas, and so on) are added to the domain, they are assigned to the DefaultSite, unless a different site is explicitly specified. A user with system administrator privileges can change the Domain.DefaultSite to a different default site, if wanted.

• VirtualServer represents a logical entity for managing a group of server instances. Multiple server instances can run simultaneously on a single physical machine, or can be deployed on separate machines. The virtual server is composed of multiple server instances logically operating together to provide a service or services. Clients of the Content Engine interact with a VirtualServer, rather than interacting with a specific ServerInstance. If a VirtualServer consists of a single ServerInstance, then the two are functionally equivalent. If a VirtualServer consists of multiple server instances, then client requests are distributed between each individual ServerInstance, providing scalability and high availability. Clients are not aware of which ServerInstance fulfilled their request.

  When multiple server instances are configured to run as a VirtualServer, a third-party (non-FileNet) load-balancing mechanism must exist to distribute incoming requests to the server instances. This might be a Java Platform, Enterprise Edition application server's clustering implementation, or it might be an external hardware or software load-balancing product. In either case, an administrator, by using the third party's load-balancing configuration tools, is responsible for configuring the load balancing for a VirtualServer.

  VirtualServer objects are created dynamically during system initialization and startup based on the configured topology of the application server or through specific system properties. See the Content Engine reference help for information on retrieving a stored VirtualServer object.

• ServerInstance represents a single instance of a Java Virtual Machine (JVM) running in an application server. One or more logically connected server instances that work together constitute a virtual server. One or more virtual servers make up a site within a FileNet P8 domain. ServerInstance objects are created dynamically during system initialization and startup based on the configured topology of the application server or through specific system properties.

  You can retrieve the value of the ServerInstance.HostNames property to get a list of the DNS host names associated with the server instance. Most often, this property is populated with a single host name, but a multi-homed machine might have different DNS names for each IP address. Displaying this list of host names in your application might be useful to help an administrator identify the machine that is hosting a particular server instance.

• SubsystemConfiguration - For each independent level of the server hierarchy (Domain, Site, VirtualServer, and ServerInstance), there are a number of associated configuration objects. All of the configuration objects available at the independent levels are represented as a SubsystemConfigurationList collection of dependent objects of the "host" independent object. Each SubsystemConfiguration element of the collection represents a configuration object that is related to a particular subsystem or functional area that can be configured relative to a server hierarchy. Each of these configuration objects has one or more attributes that define various configuration options for a particular subsystem area (such as content cache, server caching, trace logging). Suitable defaults for all configuration objects are created by the server at the Domain level at Domain creation time. If these defaults are not modified, or overridden at a lower level, then they remain in effect.
• System add-ons are product extensions to the core Content Engine components. These extensions consist of properties and classes to support a specific feature. Add-ons can be non-FileNet products that are compatible with FileNet P8 , or they can be supplied by FileNet to provide extra functionality. Creating an instance of an add-on automatically registers it in the FileNet P8 GCD database.
• Markings represent the definition of values that can be assigned to a marking-controlled property. Markings provide an extra, optional layer of security that is primarily designed for the records management marketplace, but which you can also apply to non-records management applications. Markings allow controlled access to objects based on specific property values. The set of definitions for all possible Marking objects is contained in a MarkingSet. Because Markings and MarkingSets are stored in the GCD, they are available to and consistent across all object stores in the FileNet P8 domain.
• PEConnectionPoints route Process Engine requests to an isolated region (IsolatedRegion instance). This information is persisted in the GCD. Multiple PEConnectionPoint instances can reference the same isolated region. The set of connection points that are defined is reflected in the Domain.PEConnectionPoints property.

Connecting to the FileNet P8 Domain

A domain connection is required to obtain a reference to any object stores within a FileNet P8 domain. A Connection object represents a logical connection to a FileNet P8 domain and contains information, such as configuration options, needed to run an operation on the Content Engine server that runs in the FileNet P8 domain.

A Connection object contains enough information to establish communication with the Content Engine server. This information is carried in a URI and includes the transport protocol (connection type), host name, and port number that are used for server communication. An incorrect configuration, such as an incompatibility between the environment and the information in the Connection object, is the most frequent cause of an exception that is related to a connection failure. For example, if the URI carried by the Connection object specifies the EJB transport protocol but an EJB JAR file is not in the class path, the API throws an exception.

You can create a Connection object by calling one of the static methods on the Factory.Connection class. See Getting a Connection for a code sample that illustrates connecting to a domain.

Multiple Domains

Your organization maintains the physical infrastructure and storage resources on which a domain depends. However, a FileNet P8 installation is not limited to a single domain; logically separate multiple domains can be set up that share physical infrastructure and resources. If your domain is a master domain, as opposed to a standard stand-alone domain, you can set up multiple domains, called tenant domains, that are managed by the master domain.

The type of a domain is indicated by its read-only DomainType property and can be one of three types: Stand-alone, master, and tenant:

• Stand-alone: A stand-alone domain is a standard domain, which does not allow for the creation of tenant domains. If a FileNet P8 installation is installed with a stand-alone domain, additional domains cannot be created.
• Master: A master domain allows for the optional creation of one or more tenant domains, which share its physical infrastructure and resources. The master domain contains the master instances of entities that represent the structure of the master domain and its tenant domains (for example, Site, VirtualServer, and ServerInstance, and SubsystemConfiguration) through which the service provider configures and manages the multiple tenant domains.
• Tenant: A tenant domain shares the physical infrastructure and resources of a master domain, but appears to the API to be a stand-alone domain. Each tenant domain has its own realm and directory configuration and is independent and isolated from every other tenant domain. The entities that represent the structure of the master domain and its tenant domains are available to each tenant domain as a read-only copy.

For more information on multiple domain support, including important information on supported scenarios, see Multiple domain scenario.

Base Classes and Interfaces

Many of the methods available in the Content Engine APIs are exposed through inheritance. A set of base classes and interfaces provide the basic functionality that is inherited.

EngineObject class

An EngineObject object is any object that is known to the Content Engine, including objects that are outside of repositories. Examples of objects that exist outside of repositories are Domain, MarkingSet, ObjectStore, and User objects.

The EngineObject interface represents the top-level interface from which most of the other Content Engine API interfaces derive. You do not normally work directly with an EngineObject, but rather with an instance of one of its subclasses, which are further grouped into independent and dependent objects. This interface provides some base functionality, such as retrieving the Connection object that is used for communication to the Content Engine server and retrieving an object's class information and properties.

The following topics briefly describe some key subclasses of EngineObject.

IndependentObject

An IndependentObject represents an EngineObject that has its own independent identity. Contrast this object with a DependentObject object, which is an EngineObject that can exist only within the scope of another object. An IndependentObject always has an ObjectReference, which provides identity information for the object.

An IndependentObject can be fetched from the server with a call to InstantiatingScope.fetchObject or Factory.<classname>.fetchInstance, whereas a dependent object can be fetched only by using a property of another object.

DependentObject

A DependentObject represents an EngineObject that can exist only within the scope of another object. Unlike an IndependentObject, which has its own independent identity, the identity and security of a dependent object are derived from that of its parent object. A dependent object can be fetched only from the server as a property of an IndependentObject and can be saved only to the server when attached as a child of an IndependentObject. An example of this dependency is ContentElement objects; a content element must be attached to a particular Document or Annotation object before it is persisted. Other examples are Permissions, PropertyDefinitions, and Choices. See the API reference help for a complete list of DependentObjects.

Each of these DependentObject types also has a corresponding list-type collection (for instance, a ContentElementList, PermissionList, and ChoiceList). A DependentObject is assigned to a DependentObjectList, and the DependentObjectList is then assigned to an IndependentObject (for instance, Document has a property, ContentElements, of type ContentElementList and ClassDescription has a property, PropertyDescriptions, of type PropertyDescriptionList).

DependentObject objects and DependentObjectList objects are not reusable. That is, a DependentObject or DependentObjectList object taken from a fetched object must not be reassigned to another object. After they are assigned to one parent object, they must not be assigned to a second parent object. For example, do not fetch the Permission objects for one object and then try to directly use those same Permission objects on another object. If you attempt such reuse, the results are unpredictable. In some cases, there might be no adverse effects. The operation might appear to succeed but give results other than what the caller expects, for example, errors when you try to save the object. In other cases, the attempted operation might fail with symptoms that are difficult to diagnose.

Any attempt to assign an already-assigned DependentObject object to another parent object causes a warning message to be written to the client trace log.

IndependentlyPersistableObject

An IndependentlyPersistableObject represents a persistable IndependentObject that you can directly create, update, and delete. This interface provides some base functionality to its subinterfaces, such as modifying an object's pending actions list, updating the object's sequence number, and retrieving access right (permission) settings.

RepositoryObject

A RepositoryObject represents any object that is known to the Content Engine that resides within an object store repository. A Document object is an example of a RepositoryObject. In contrast, an EngineObject is any object that is known to the Content Engine, including objects outside of repositories (such as Domain and ObjectStore).

You do not normally work directly with a RepositoryObject, but rather with an instance of one of its subclasses.

Subscribable Object

A Subscribable object serves as the target of an event subscription, represented by an objects base on the Subscription class. Subscribable is a base interface of several derived interfaces that can be used as a subscription target. You set a Subscribable object as the target of a subscription through the SubscriptionTarget property of the Subscription object.

Containable Object

A Containable object represents the base class for all objects that can be contained. Except for the Folder object, all Containable subclasses are referentially contained. Folder objects and their subclasses can be directly contained in a Folder object, or referentially contained (see the ReferentialContainmentRelationship or DynamicReferentialContainmentRelationship classes).

Versionable Object

A Versionable object represents the base class for classes whose instances are versionable objects. If versioning is enabled on a Versionable object (its IsVersioningEnabled property is true), it can have multiple associated versions in an object store. A versionable object can be checked out, optionally edited, and checked in as a major or a minor version. A major version is either the current released version (if it is the latest major version) or a previously released version that was superseded. A minor version is either the in-process version (if it is the latest minor version) or a previous in-process version that was superseded. When a versionable object is checked out, a reservation object is created, which you can modify. During the check-in operation, the reservation object becomes the current version of the versionable object. You can access all of a Versionable object's versions through its associated VersionSeries object or from the collection that is returned by its Versions property.

Core Objects

Core objects are objects that are related to the core business objects of the API, such as Document and Folder. The interfaces and classes that are associated with these objects are contained in the Java API core package and the .NET core namespace. Also included in the core functionality are factory classes for instantiating objects. Some of the most important of the core classes and interfaces are described in the following sections.

Connection

A Connection object holds the information that is required for an application to connect to the FileNet P8 domain and its resources. You can establish the connection by calling Factory.Connection.getConnection (Java) or Factory.Connection.GetConnection (.NET). (See Getting Started Procedures.)

ObjectStore

An object store is an independent, domain-scoped object (that is, it is defined in the GCD). It provides access to resources: Content Engine objects such as documents, folders, custom objects, class descriptions, property descriptions, security policies, and their related metadata. It represents a location in which folders, documents, and custom objects are stored, accessed, and managed on the Content Engine server.

Using methods on the ObjectStore interface, you can create and store new objects in the object store, retrieve information about objects, and retrieve the object store's installed feature add-ons.

Folder

A folder provides access to filed objects by emulating familiar file system semantics. A Folder object is a container that can hold other containable objects, but cannot have content data of its own. Although Folder objects and their subclasses can be referentially contained, they are the only Containable subclass that can be directly contained (in a Folder). All other Containable subclasses are referentially contained by using the ReferentialContainmentRelationship or DynamicReferentialContainmentRelationship classes.

Other important folder behavior:

• Folders are not versionable.
• Referentially contained folders cannot participate in hierarchy index searches.

At the top of the container hierarchy is an automatically created root folder. A containing (parent) folder can contain multiple child folders, but a child folder can have only one parent folder. You create a directly contained folder when you call methods on a parent folder that create a subfolder.

Custom objects and documents are always referentially contained. For referentially contained objects, their containment models an N:M, or many-to-many, relationship. A folder can contain arbitrarily many containees, and a containable object can appear in arbitrarily many folders. An object can therefore appear in a folder more than once.

Document

A Document object represents a single version of a document that is stored in a Content Engine object store. Fundamentally, a document can be thought of as two things:

• The document that the user creates. This document (a word-processing file, a graphic, a spreadsheet, an html file) is stored either in the object store's content store or stored externally (for example, a Web page that is referenced by its URL address). In either case, it is known as the Document object's content element.
• The object that describes the user's document. This object, which the Content Engine uses to identify and find that particular version of the user's document, is called a Document object.

A document can have zero or more associated content elements. If a document has content, the content is either stored in a Content Engine content store (referred to as a content transfer element) or stored externally (a content reference element). These elements are represented by ContentTransfer and ContentReference objects, respectively. For content-carrying documents, the Content Engine APIs support creating a document with one or more content transfer elements, one or more content reference elements, or a mix of content transfer and content reference elements.

A document can be versioned. The Content Engine supports three levels of versioning: no versioning enabled, single-level versioning, and two-level versioning. When you version a document (by checking it into a Content Engine object store), a VersionSeries object is associated with it that contains all versions of that document.

Annotation

An Annotation object represents incidental information that can be attached to an object (its parent) for annotating or footnoting that object. An Annotation object allows you to link additional information to a containable object (custom object, document, or folder). You can modify and delete an annotation independently of its parent object. However, you cannot create versions of an annotation separately from its parent object. By design, an annotation is deleted whenever its parent object is deleted.

A document annotation is uniquely associated with a single document version; it is not versioned or carried forward when its associated document version is updated and a new version created.

CustomObject

A CustomObject object is a general object that has no inherent semantics, but is independently securable and can be persisted to an object store. Key aspects of a custom object are that it does not carry content, is not versionable, and does not support lifecycle functionality. It can be filed into a folder and can be annotated.

WorkflowDefinition

A workflow definition is an XML document, which is authored by using the Process Designer application, that electronically represents the sequence of steps that are required to accomplish a business process. It acts as a processing template that the Process Engine uses each time that the workflow runs. The steps represent each specific activity or task in the business process. Step specification includes: who processes the work for the step, which launch step processor application the participant uses, which attachments (documents) are required, what data is necessary, what responses the participant can choose, and other options. The routing logic specifies how work advances from one step to the next.

After the workflow definition is complete, the author typically transfers it to the Process Engine server and then saves it as a WorkflowDefinition object in a Content Engine object store. You can then link the workflow definition to a target object so the workflow can be started, either manually or by an event.

You work with a WorkflowDefinition object in the same ways you work with a Document object. Any actions that you can perform on a document can also be performed on a workflow definition: you can check it out, set its content, check it in, file it into a folder, and delete it. In addition, you can retrieve its associated WorkflowSubscription objects.

Collections

Content Engine collections are groups of related elements and can be one of two types: list or set. The name of a collection identifies its type. For example, a DocumentSet is a collection of Document objects and an IdList is a collection of Id objects. For more information, see Collections.

Constants

The Content Engine APIs provide classes that define groups of related, type-safe constant values. The class name identifies the purpose of the enumeration and the names of individual values identify their uses. For example, the CheckinType class contains MAJOR_VERSION and MINOR_VERSION constants that identify the check-in type as a major version or a minor version, respectively.

Authentication

Authentication is the act of verifying a user's identity based on some credentials that they have presented. Establishing each user's identity is a critical first step in any client/server based system. FileNet P8 offers more options than just passing a username/password combination for authentication. These options are made possible by employing the Java Authentication and Authorization Service (JAAS) standard and the Web Services Security (WS-Security) standard. The JAAS standard forms the framework for security interoperability in the Java Platform, Enterprise Edition environment, whereas the WS-Security standard forms the framework for security interoperability in the heterogeneous world of clients and servers that communicate through Web services interfaces. By employing these standards, you can integrate a wide range of authentication options with FileNet P8 .

Each potential Content Engine user is expected to be a security principal that is defined within an existing enterprise directory service. JAAS authenticates the user. JAAS defines an authenticated identity within a "Subject". In cases where the client of the Content Engine API is code that is already running within an application server, the client will already be authenticated and will already have an associated Subject. In cases where the client is outside of the application server, either the application, the Content Engine API, or the CEWS Listener performs a JAAS authentication with the client's credentials to generate the Subject.

After a user has been authenticated within the system, the user's identity (its JAAS Subject) must accompany each request that the user makes. (The API handles that transparently on behalf of the caller.) When the authenticated user interacts with the Content Engine server, an authorization mechanism determines the level of access (if any) that user must create, view, or manipulate objects within the system.

Obtaining a JAAS Subject

For information on how to obtain a JAAS Subject that is supported and trusted by the targeted application server, see Getting a Connection. Note that for the .NET API, the Microsoft.Web.Services3.Security.Tokens.SecurityToken class is similar to the JAAS Subject. A JAAS Subject represents a user who has been authenticated, while a Microsoft SecurityToken holds credentials that can be used to authenticate a user (by performing a JAAS login) when a CEWS request is processed on the Content Engine server.

Kerberos support

The Content Engine can use Kerberos authentication for single sign-on (SSO) in environments where JAAS is not available. For example, SSO allows an initial Windows logon to securely establish a user's identity such that subsequent logons do not require the user to provide credentials again. For more information about single sign-on and Kerberos support, see the available Kerberos documentation and the Security Guide in the Enterprise Administration help. For information on setting up Kerberos for the Content Engine environment, see Working with Security.

Custom login modules

The Content Engine server accepts incoming requests over two transport protocols: an EJB transport and a CEWS transport. Authentication over the EJB transport is extensible through JAAS. The Java Platform, Enterprise Edition application server authenticates callers before they can access the EJB layer.

The Content Engine web service provides out-of-the-box-support for the Web Service Security (WS-Security) Username Token profile, and the Kerberos profile. Support for other WS-Security-compliant approaches can be added through the Content Engine Web Service Extensible Authentication Framework (WS-EAF). WS-EAF is a pluggable authentication mechanism for the CEWS transport. It accepts credentials based on the WS-Security OASIS standard and implemented with the JAAS standard. Developers can create custom login modules that handle binary security tokens as defined in WS-Security standards.

For information on creating custom login modules, see the IBM FileNet Content Engine Web Service Extensible Authentication Framework Developer's Guide.

Authorization

After authentication occurs, authorization to access persisted objects is verified. With few exceptions, every independently persisted object has its own security settings. For example, where multiple versions of a document exist, each document version has its own security settings. These security settings control a user's (or group's) access to that object. Assets that are managed in the Content Engine are protected and can be seen or modified only according to a user's access rights. For more information about authorization, see Authorization.

Instantiating Objects

Because the Content Engine Java and .NET APIs are defined in terms of interfaces, you generally cannot instantiate new objects by using the standard "new" construct. You must instead use a factory class method, which is defined on a Content Engine API Factory class, to instantiate type-appropriate objects. The following section describes the use of factory methods and includes information about how objects are scoped to other objects

Factory methods

The Content Engine APIs provide a Factory class along with static inner classes with names that parallel the standard Content Engine API types, such as Factory.Document. Factory methods are convenient and provide type safety. They avoid the inconvenience (and potential for error) of specifying the object type, you do not have to cast the Factory method results to a wanted type, and you can catch programming errors on the returned type at compile time instead of at run time.

To create or retrieve instances of known object types, use the static methods that are provided by the Factory class for the specific object type. (If you don't have knowledge ahead of time of the object type, see Scoping.) The Factory methods available are for instantiating objects are createInstance, fetchInstance, and getInstance (for "fetchless instantiation").

The createInstance methods are used to instantiate an object that references a new server object. When the object is instantiated, no round trip to the server is made, and the object will not yet exist in the repository. Instead, the instance has an associated "Create" pending action. The round trip to the server happens at a later commit (save) step.

The fetchInstance methods instantiate an object by first making a round-trip to the Content Engine server and retrieving ("fetching") property values. The instantiated object has within it a value for the UpdateSequenceNumber (USN) that is current as of the fetch. The USN protects the object against concurrent updates. Its value increases with each update to the object. When the object is updated, the USN from the retrieved object is checked against the currently persisted USN value. If the values are different, the operation fails. You can interrogate an object's UpdateSequenceNumber property to determine if the object has been modified since some earlier fetch of the same object. Clients can force updates to be persisted regardless of the USN value by calling setUpdateSequenceNumber(null). A null USN causes the server-side check to be skipped during updates. You might want to do this when you call delete() or checkout() on an object.

Fetchless Instantiation

The getInstance methods are used to instantiate an object that references a server object that is assumed to already exist. The existence of the object is not verified on the Content Engine server, and no round trip to the server is made until you perform a function on the object (for example, fetch a property value) that causes a round trip to the server. This is called "fetchless instantiation" and is useful for performance reasons if the object serves only passively, perhaps as the target value for an object-valued property.

An object that is instantiated with getInstance is unaware of the persisted UpdateSequenceNumber for this object. When you save a fetchlessly instantiated object, the UpdateSequenceNumber property value is set to null, therefore skipping the server-side check for updates and allowing the object to be saved regardless of any intervening updates that are made to the object on the server after the client instantiated its copy of the object.

Scoping

The scope of an object is its "enclosing context". That is, it is the object from which another object originated. As examples, a Domain is the originating scope of a Site or ObjectStore, and an ObjectStore is the originating scope of a Document.

Classes are characterized by where the instance objects are located. Some objects are located within an ObjectStore; other objects are located "above" an ObjectStore, that is, at a higher level in the object model. A ClassDescription is scoped to a particular location and the object that is affiliated with that location is the scope object. Calling ClassDescription.getScope() returns one of the following, depending on what type of class the ClassDescription describes:

• Domain
• ObjectStore
• null (for the cases of Realm and EntireNetwork)

The following table lists scope objects and the objects scoped to them:

EntireNetwork, being the root of the hierarchy, scopes itself, and is also the scope object for Domain and Realm. The scope object for a ClassDescription object is the same as the scope object for an instance that is described by that ClassDescription object. For example, if a CustomObject object is scoped by an ObjectStore instance "OS1", then the custom object's ClassDescription is also scoped by "OS1".

Most often, you create or retrieve instances of objects for which you have type-specific knowledge. However, occasionally you might not have this knowledge and for those times, you can instantiate objects by using InstantiatingScope, which is extended by both ObjectStore and Domain.

The InstantiatingScope interface provides a generic means for instantiating independent objects within a scope. From InstantiatingScope, you can instantiate only those objects within its scope. For example, a Document object is within the scope of an ObjectStore, but is not within the scope of a Domain. This interface provides methods for creating or retrieving objects when you do not have type-specific knowledge of the objects to be instantiated. You can create or retrieve objects by supplying just a class name and (for retrieval) an object identifier or path. You must cast the returned object to the wanted type.

Saving Objects

In the APIs, actions on an object are combined in one call to the server. The combined calls are run when the object is saved (or committed when you are using batch processing). The actions that accumulate on the object before the save operation are called pending actions.

Because of the way that pending actions are handled in the APIs, saving an object can sometimes lead to unexpected failures. A pending action represents an intended change that has not yet been saved (committed) to an object on the server. When you call a method that changes the underlying object, a subclass of PendingAction is created that corresponds to the action. For example, calling Document.checkout creates a Checkout subclass of PendingAction. The pending action is added to the underlying object’s ordered list of pending actions (an automatically generated PendingActions collection). For each subsequent action (such as locking and unlocking, changing the class, freezing, deleting, and so on) taken on the object, an item is added to the pending actions list. When you commit the object, for example, by calling the save method or, in the case of batch operations, by committing the batch, the underlying object (and its collection of pending actions) is sent to the server and changes are written to the repository in the order in which they occur in the object’s pending actions list. Any failure of the set of actions that are involved in the call cause the entire set of actions to fail. The save method always completes all of the work included in a request or none of the work (as an atomic transaction).

You can use any of the following approaches in your application program to prevent failures during a save:

• Call refresh, followed by delete. Then, call save.
• Traverse and remove "dirty" properties before you send the delete to the server with a save call.
• Fetchlessly instantiate the object, call delete, then call save.

Object Deletion

Calling delete on an object adds a delete action to the object's pending actions list. When you call save() on the object, the pending actions list for the object is processed and the object is deleted if no prior failures have occurred in the list that is being processed. For more information about how prior failures in a transaction can cause delete to fail, see the example in Saving Objects.)

Object Serialization

All Content Engine Java API objects implement the java.io.Serializable interface, and all Content Engine .NET API objects are annotated with the SerializableAttribute so that they can be serialized by the formatter. The items below point out some additional information about serialization of specific objects.

• The Connection object contains the URI for connecting to the Content Engine server. It is possible that network topology issues make a particular URI unusable at the point where the object is deserialized. It is recommended that application and system designers take this possibility into account.
• Content Engine Java API RPCs always require an active JAAS Subject, either through some ambient JAAS configuration or by using the Content Engine APIs UserContext object. Because neither of those things is part of the serialized state of a Content Engine object, application and system designers are cautioned to ensure that an appropriate JAAS Subject is available before any subsequent round-trips to the Content Engine server are made from the point where the object is deserialized.

Client-Initiated Transactions

Transactions are supported over the EJB transport through Java API calls. (The CEWS transport and the .NET API do not support client-initiated transactions.) Transaction processing is implemented by using standard Java Platform, Enterprise Edition transaction mechanisms through the Java Transaction API (JTA). Your application can perform multiple operations within a transaction. If the transaction fails (for example, one of the operations fails), the JTA handles the rollback of the entire transaction. To set up transaction support for your Java client application, use the standard Java Platform, Enterprise Edition UserTransaction calls (on the javax.transaction.UserTransaction interface). You must also enable transactions on the Connection object you are using by setting the CONNECTION_PARTICIPATES_IN_TRANSACTION parameter to true. For more information, see the Connection.setParameter method and ConfigurationParameter.CONNECTION_PARTICIPATES_IN_TRANSACTION.