The Content Engine APIs are platform-independent APIs for building applications that access and manipulate objects stored on a FileNet® Content Engine server. There are three main application types that are supported by the Content Engine APIs: runtime, administration, and metadata authoring. Runtime applications interact with object stores and documents, administration applications perform configuration tasks, and metadata authoring applications create class definitions and properties. The APIs expose all of the operations that are supported by the Content Engine server. Using the Content Engine APIs, you can create applications that address all of these application types.
This "Getting Started" section introduces you to requirements for setting up your system to use the APIs and the core objects of the Content Engine APIs. Brief descriptions are provided for how to create, retrieve, and persist objects using the APIs. (For more information on a particular API, refer to the online help provided with each interface or class and other documentation referenced in the sections below.)
Important In the development of your applications, use only the public classes and interfaces that are documented in the Content Engine Java and .NET API reference help, with the exception of those marked in the reference help as internal use only. Do not use the internal, non-public classes and interfaces, that is, those not documented in the API reference help, and do not use any public classes and interfaces that are marked as internal use only.
To begin your development, you must have certain versions of the framework software that support your development environment and language. This section provides references to that information.
In addition, see the following topics for the steps you need to take for setting up various development environments:
The Content Engine APIs require certain minimum levels of the Java™ 2 Standard Edition (J2SE) and Microsoft® .NET Framework environments. Refer to the IBM FileNet P8 Hardware and Software Requirements document for this release. To download this document from the IBM support page, see Accessing IBM FileNet Documentation.
The Content Engine Java API requires several other JAR files (including third-party JAR files) during runtime. The required JAR files are installed with the Application Engine software. The supplied versions of these JAR files are required and you should not substitute other copies of JAR files with the same names. (For specific installation instructions for your environment, refer to the IBM FileNet P8 Platform Installation and Upgrade Guide. To download this document from the IBM support page, see Accessing IBM FileNet Documentation.) If you are writing a standalone Java application that uses the Content Engine Java API, the required JAR files must be in your classpath. 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 Java Beans (EJB).
.jar File |
Description |
Required for a Content Engine Java API CEWS transport client |
|
Jace.jar | The core FileNet JAR file for the Content Engine Java API; includes the common JAR and transport JAR. Important Do not use the internal, non-public classes and interfaces, that is, those not documented in the API reference help, and do not use any public classes and interfaces that are marked as internal use only. |
log4j-<version>.jar | The LOG4J framework for Content Engine Java API logging, where <version> is the supported version installed with the FileNet P8 Platform software. Example: log4j-1.2.14.jar. |
wasp.jar | Systinet web service interface transport classes. Required only when running the Java API over the CEWS protocol. The wasp.jar file is supplied by the Content Engine installation package. The following required files are among those JAR files referenced (directly or indirectly) by the CLASSPATH directive in wasp.jar's manifest file and used by Systinet WASP:
Notes:
|
activation.jar | The Java™Bean Activation Framework standard extension. |
builtin_serialization.jar | Systinet WASP built-in serializers and deserializers. |
Required for a Content Engine Java API EJB transport client |
|
Jace.jar | The core FileNet JAR file for the Content Engine Java API; includes the common JAR and transport JAR. |
log4j-<version>.jar |
The LOG4J framework for Content Engine Java API logging, where <version> is the supported version installed with the FileNet P8 Platform software. Example: log4j-1.2.14.jar. |
An application server-specific .jar file | If already in an application server, this JAR file is not required. Required only if in a standalone JVM. |
Required for a Content Java API Compatibility Layer client |
|
javaapi.jar | The class implementation files for the Content Java API compatibility layer. |
p8cjares.jar | The localizable resource strings for Content Engine Java API compatibility layer classes. |
listener.jar | P8 System Manager listener API. Required only if you are developing a System Manager logging client or if you want the compatibility layer API to do System Manager performance monitoring. The compatibility layer will use the file if present; otherwise, it is ignored. (For information about System Manager logging, see FileNet System Manager Help for Developers.) |
All .jar files for a Content Engine Java API client of the applicable transport. | See the sections above for your transport. |
To begin development with the Content Engine .NET API, you must have installed at least the .NET 2.0 Framework and the Microsoft Web Services Extensions (WSE) 3.0. This environment allows you to create your own custom applications. (Note that this same environment is also required to use the FileNet P8 Enterprise Manager.)
To develop applications against the .NET API from Microsoft Visual Studio®, you must first add a reference in your project to the .NET API and WSE 3.0. 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 file named FileNet.Api.dll and click the OK button. Then add a reference to the Microsoft.Web.Services3 (WSE3). You can add this reference in the same Add Reference dialog, but using the ".NET" tab instead. Select the entry for Microsoft.Web.Services3, and then click the OK button. You can now use the Content Engine .NET API from your project.
For Content Engine Web Service applications developed using the 3.5.2 or earlier version of the Content Engine WSDL, only the .NET 1.1 Framework, with Microsoft Web Services Extensions 2.0, is supported.
For the most part, 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, no equivalent .NET namespace exists. The following table lists the Java packages and .NET namespaces, with brief descriptions.
Java Package |
.NET Namespace |
Notes |
com.filenet.api.action | FileNet.Api.Action | Classes related to making changes to objects. |
com.filenet.api.admin | FileNet.Api.Admin | Classes and interfaces used in the administration of a FileNet P8 Content Engine server. |
com.filenet.api.collection | FileNet.Api.Collection | Type-safe interfaces related to collections of objects. |
com.filenet.api.constants | FileNet.Api.Constants | Classes defining collections of related, type-safe constant values. |
com.filenet.api.core | FileNet.Api.Core | Classes and interfaces that are related to the core business objects of the API. |
com.filenet.api.engine | N/A | Classes and interfaces used when writing code that runs within the Content Engine server (for example, an event action). |
com.filenet.api.events | FileNet.Api.Events | Event-handling framework for the Content Engine. |
com.filenet.api.exception | FileNet.Api.Exception | Exception-reporting framework for the Content Engine. |
com.filenet.api.jdbc | N/A | Classes related to using the Java™ Database Connectivity (JDBC) provider for the Content Engine database. |
com.filenet.api.meta | FileNet.Api.Meta | Classes and interfaces related to Content Engine object property metadata. |
com.filenet.api.property | FileNet.Api.Property | Classes and interfaces related to Content Engine object properties. |
com.filenet.api.publishing | FileNet.Api.Publishing | Interfaces related to publishing. |
com.filenet.api.query | FileNet.Api.Query | Classes related to constructing and performing Content Engine searches. |
com.filenet.api.security | FileNet.Api.Security | Interfaces related to authentication, authorization, and user- and group-specific data. |
com.filenet.api.util | FileNet.Api.Utility | Utility classes and interfaces. |
The Content Engine supports two basic transport protocols: EJB and CEWS. The following diagram shows the interaction of these protocols with the Content Engine. Another source of information is the Architecture section of Content Engine Administration online help.
The Content Engine exposes its functionality through the EJB Container layer of the Java 2 Enterprise Edition (J2EE) application server. The EJB protocol (typically RM-IIOP based) is language-independent and passes serialized Java objects across the network for requests/responses to/from the Content Engine server. The Content Engine Java API configured to run over the EJB transport is the fastest interface available in FileNet P8.
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 J2EE components 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.
The CEWS transport to the Content Engine server is based on the SOAP protocol. Both the .NET and Java APIs can operate across CEWS. The .NET API uses the CEWS transport to access the Content Engine. The CEWS transport passes XML over HTTP. Content Engine objects are represented in XML, which is serialized and passed across the network from the client to the Content Engine server.
When developing client applications using the CEWS transport protocol, the URI endpoints you specify differ depending on whether you are creating a .NET client application or a Java client application. For a .NET client application, you must specify FNCEWS40MTOM as the URI endpoint. When developing a Java application, specify FNCEWS40DIME.
The Web Service Listener is implemented as a servlet running in the Web Container layer of the J2EE application server. With the exception of transaction propagation, the Web Container layer exposes the same Content Engine functionality to web service clients as the EJB layer exposes to Java clients. It leverages the Systinet toolkit to provide a pure web services based interface to the Content Engine server. The CEWS Listener forwards .NET calls to the EJB layer to access the Content Engine.
You can specify either EJB or CEWS transport when establishing 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 required to establish a connection to the Content Engine
server, such as the transport protocol, host, and port used for server
communication.
A Content Engine Java API based client determines which transport to use to communicate with the server based on the URI parameter used when creating a Connection
object through Factory.Connection.getConnection()
.
See Getting a Connection for examples.
There are differences to note when using one transport protocol versus the other.
Connection
object. These are only two examples of configuration differences that may affect you based on your choice of transport. Refer to Client Configuration for more information about configuration files.ConfigurationParameter.CONNECTION_PARTICIPATES_IN_TRANSACTION
to true
to indicate that your connection participates in a transaction will cause a runtime exception. (To set up transaction support for your Java client application, see CONNECTION_PARTICIPATES_IN_TRANSACTION
in the Java API reference help.)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 specified in the configuration file. (See the Configuration
class and ConfigurationParameter
in the reference help.)
For Java applications, you are assumed to have a Java™ Runtime Environment (JRE)-configured JAAS login context in place. The Content Engine Java API depends on JAAS for authentication.
There are many configuration files that you have access to for configuring your client environment. Most of them apply to the Java environment. The first topic below describes the .NET configuration files. The remainder of the topics in this section describe the configuration files for Java.
The app.config file (or web.config for ASP.NET applications) is an application-specific configuration file containing 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 will be 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 this 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. With the exception of the Systinet-related enumerations, which are not applicable in the .NET environment, the keys you use to set the values map to ConfigurationParameter
enumerations.
Below is an example of an app.config file illustrating the "filenet.api" section:
<?xml version="1.0" encoding="utf-8" ?> <configuration> <configSections> <section name="filenet.api" type="FileNet.ApilUtil.FileNetConfigHandler, FileNet.Api, Version=4.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 (or web.config for ASP .NET applications). If you choose to do this, you must split the two sections (<section name="filenet.api"> and<filenet.api>) and merge them into different parts of the machine.config file. As you'll note above, the app.config file has a <configSections> with one entry, followed immediately by the <filenet.api> section. A machine.config file will already have an existing <configSections> section that already has many entries. To add this information into the machine.config file, you must insert <section name="filenet.api> into the existing <configSections> area, and place the <filenet.api> section at an appropriate point, separated from the <configSections>. Note that it does not have to be at the end of the file, but is typically placed there. See your .NET developer documentation for more information about the machine.config file. Here's an example (note the highlighted sections):
<configuration>
<configSections>
<section name=... />
<section name=... />
...
<sectionGroup name=...>
<section name=... />
<section name=... />
</sectionGroup>
<section name=... /> <section name="filenet.api" type="FileNet.ApilUtil.FileNetConfigHandler, FileNet.Api, Version=4.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>
This file, which is optional, contains entries for setting configuration values (see the types of configuration items in the ConfigurationParameter
class). The following 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 shown below:
user.dir
)user.home
)java.home
)If the file is not found in one of those directories, the API tries to find it on the classpath.
The Content Engine Java API assumes that a JAAS context has been established prior to any requests being issued. There is no legacy support for the username/password model via the UserContext
class. Even when using that legacy support, the client environment must include a proper JAAS configuration (the API does an internal JAAS login for the legacy support).
The FileNet P8 Content Engine installation process provides samples of the JAAS configuration file for each supported application server environment: jaas.weblogic.config, jaas.websphere.config, jaas.jboss.config, and jaas.wsi.config. These files are not intended to be used as-is. Rather, you can 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 using the EJB transport, the application server's normal JAAS configuration (or a site's customization of it) will be sufficient. When 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 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 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". Of course, the normal overall JAAS fallback of "other" will also be used if "FileNetP8" is not present. You can also integrate the above login module with existing JAAS configuration stanzas.
Once you have configured JAAS correctly, you can perform a JAAS login. For a code sample, see Obtaining a LoginContext.
A number of Systinet configuration files are required, but only those listed below must be present in the \wasp.location\conf folder when running the Java API over the CEWS protocol. There is no need for client applications to make any changes to these configuration files:
The jndi.properties file, which is not used when running over the web service transport, and is optional when running over 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 through the use of the java.naming.factory.initial and java.naming.provider.url system parameters.
Client API logging is controlled by an optional log4j configuration file, which may 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 prior to use). Entries from that file can also be merged with an established site configuration file for log4j.
The FileNet P8 domain represents a logical grouping of physical resources (such as object stores) as well as the Content Engine servers that provide access to those resources. It is also associated with one or more security realms for authenticating 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 one and 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 Domain Concepts in the Content Engine Administration help.
The Global Configuration Data (GCD) database 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, executing outside of an application server, to create a new FileNet P8 domain or join an existing P8 domain. The GCD, which may 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.
Note: If you are using distributed transactions, do not update GCD-based objects in a user-initiated transaction. Doing so is likely to cause a wait state in all threads, across all servers, until the transaction completes.
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
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 or not content retrievals and uploads are processed through a content cache, and whether the request will be forwarded to a server in another site perhaps 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, etc.) 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 desired.
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
actually 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 J2EE application server's clustering implementation, or it could be an external hardware or software load-balancing product. In either case, an administrator, 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 via specific system properties. See the Content Engine reference help for information on retrieving a persisted VirtualServer
object.
ServerInstance
objects are created dynamically during system initialization and startup based on the configured topology of the application server or via specific system properties.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 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 defining various configuration options for a particular subsystem area (such as content cache, server caching, trace logging, and so on). 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 will remain in effect.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. IsolatedRegion
instance). This information is persisted in the GCD. Multiple PEConnectionPoint
instances can reference the same isolated region. The set of connection points defined is reflected in the Domain.PEConnectionPoints
property.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 execute 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 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 classpath, 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.
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 will be inherited.
An EngineObject
is any object known to the Content Engine, including objects outside of repositories. Examples of objects residing 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 will 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
.
An IndependentObject
represents an EngineObject
that has its own independent identity. Contrast this with a DependentObject
, which is an EngineObject
that can only exist 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 only be fetched via a property of another object.
A DependentObject
represents an EngineObject
that can only exist 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 only be fetched from the server as a property of an IndependentObject
and can only be saved to the server when attached as a child of an IndependentObject
. An example of this dependency is ContentElement
; content elements must be attached to a particular Document
or Annotation
object before being persisted. Other examples are Permissions
, PropertyDefinitions
, and Choices
. See the API reference help for a complete list of DependentObject
s.
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
s and DependentObjectList
s are not reusable. That is, a DependentObject
or DependentObjectList
taken from a fetched object should not be reassigned to another object. Once they have been assigned to one parent object, they must not be assigned to a second parent object. For example, you should 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 may 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
to another parent object causes a warning message to be written to the client trace log.
Note: While this type of operation might succeed with the current 4.x Content Engine API, the behavior is unreliable and future releases of the Content Engine API will prohibit reuse by throwing a runtime exception.
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.
A RepositoryObject
represents any object 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 known to the Content Engine, including objects outside of repositories (such as Domain
and ObjectStore
).
You will not normally work directly with a RepositoryObject
, but rather with an instance of one of its subclasses.
A Subscribable
object serves as the target of an event subscription, represented by a Subscription
-based object. 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 via the SubscriptionTarget
property of the Subscription
-based object.
A Containable
object represents the base class for all objects that can be contained. With the exception of 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).
Note: The use of referentially contained folders is discouraged since many applications will not expect them.
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 via its associated VersionSeries
object or from the collection returned by its Versions property.
"Core" objects are objects related to the core business objects of the API, such as Document, Folder, and so on. The interfaces and classes 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 below. For information about any others, refer to the reference help.
A Connection object holds the information 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.)
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, etc., 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.
A folder provides access to filed objects by emulating familiar filesystem 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 using the ReferentialContainmentRelationship
or DynamicReferentialContainmentRelationship
classes.
Other important folder behavior is:
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.
A Document
object represents a single version of a document stored in a Content Engine object store. Fundamentally, a document can be thought of as two things:
Document
object's content element.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 provides support for 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.
An Annotation
object represents incidental information that can be attached to an object (its parent) for the purpose of 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.
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.
A workflow definition is an XML document, authored using the Process Designer application, that electronically represents the sequence of steps required to accomplish a business process. It acts as a processing template that the Process Engine uses each time the workflow runs. The steps represent each specific activity or task in the business process. Step specification includes: who will process the work for the step, which launch step processor application the participant will use, 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.
Once 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 launched, either manually or by an event.
You work with a WorkflowDefinition
object in the same ways you work with a Document
object. Any actions 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.
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 Collection Concepts.
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 identifying the checkin type as a major version or a minor version, respectively.
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 J2EE 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 have the ability to integrate a wide range of authentication options with FileNet P8.
Each potential Content Engine user is expected to be a security principal 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.
Once a user has been authenticated within the system, the user's identity (its JAAS Subject) must accompany each request 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 has to create, view, or manipulate objects within the system.
For information on how to obtain a JAAS Subject
that will be 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.
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.
The Content Engine server accepts incoming requests over two transport protocols: an EJB transport and a web service transport. Authentication over the EJB transport is extensible through JAAS. The J2EE 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, as well as the Kerberos profile. Support for other WS-Security compliant approaches can be added through the FileNet P8 Content Engine Web Service Extensible Authentication Framework (WS-EAF). WS-EAF is a pluggable authentication mechanism for the web services transport. It accepts credentials based on the WS-Security OASIS standard and implemented with the JAAS standard. Developers can create custom login modules that will handle binary security tokens as defined in WS-Security standards.
For information on creating custom login modules, see the IBM FileNet P8 Content Engine Web Service Extensible Authentication Framework Developer's Guide.
Once authentication has occurred, 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 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 the Security Guide in the Enterprise Administration documentation.
Because the Content Engine Java and .NET APIs are defined in terms of interfaces, you generally cannot instantiate new objects using the standard "new" construct. You must instead use a factory class method, defined on a Content Engine API Factory
class, to instantiate type-appropriate objects. This section describes the use of factory methods. It also includes some information about how objects are scoped to other objects
The Content Engine APIs provide a Factory
class along with static inner classes with names paralleling 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 desired type, and you can catch programming errors on the returned type at compile time instead of runtime.
To create or retrieve instances of known object types, use the static methods 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 will have 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 may want to do this when calling delete()
or checkout()
on an object.
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 will only serve passively, perhaps as the target value for an object-valued property.
An object 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
, thereby skipping the server-side check for updates and allowing the object to be saved regardless of any intervening updates made to the object on the server after the client instantiated its copy of the object.
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 generally characterized by where the instance objects reside. Some objects reside within an ObjectStore
; other objects reside "above" an ObjectStore
, that is, at a higher-level in the object model. The ClassDescription
describes objects that reside somewhere. So, a ClassDescription
is scoped to a particular location, and the object 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:
Scope Object | Types of scoped objects |
---|---|
EntireNetwork | EntireNetwork, Domain, Realm |
Realm | User, Group |
Domain | ObjectStore, MarkingSet, Site, VirtualServer, ServerInstance |
ObjectStore | independent RepositoryObject types, ClassDescription |
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 described by that ClassDescription
. For example, if a CustomObject
object is scoped by an ObjectStore
instance "OS1", then the custom object's ClassDescription
will also be scoped by "OS1".
Most often, you will create or retrieve instances of objects for which you have type-specific knowledge. However, occasionally you may not have this knowledge and for those times, you can instantiate objects 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 desired type.
In the APIs, actions on an object are combined in one call to the server. The combined calls are executed when the object is saved (or committed when using batch processing). The actions that accumulate on the object before the save operation are called pending actions.
Because of the way 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 involved in the call will 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 such failures during save as the one described above:
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 being processed. (For more information on how prior failures in a transaction can cause delete to fail, see the example in Saving Objects.)
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.
Connection
object contains the URI for connecting to the Content Engine server. It is possible that network topology issues will make a particular URI unusable at the point where the object is deserialized. Application and system designers should take this possibility into account.Subject
, either via some ambient JAAS configuration or via the use of the Content Engine API's UserContext
object. Since neither of those things is part of the serialized state of a Content Engine object, application and system designers are cautioned to insure 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.Transactions are supported over the EJB transport via Java API calls. (The web service transport and the .NET API do not support client-initiated transactions.) Transaction processing is implemented using standard J2EE transaction mechanisms through the Java Transaction API (JTA). Your application can perform multiple operations within a transaction. Should the transaction fail (for example, one of the operations fails), the JTA would handle the roll back of the entire transaction. To set up transaction support for your Java client application, use the standard J2EE 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
.