Content Java API

This topic describes changes necessary to your 3.5.x Content Java API applications so that they can run in a 4.5 environment. If you have already modified your 3.5.x applications to run in a 4.0.x environment, there are no additional modifications needed to run your applications in a 4.5 environment.

Overview - Upgrading from 3.5.x to 4.5

Beginning in the 4.0 release, a Content Java API Compatibility Layer is available. The compatibility layer is a client-side API that allows you to upgrade and maintain applications written using the 3.5.x Content Java API. The compatibility layer is designed to maximize support for the 3.5.x Content Java API in a 4.x environment. However, in a few cases platform technologies diverged too greatly for an interface to be supported.

The compatibility layer is provided only to support existing applications, and can be installed during Content Engine installation. Documentation for the compatibility layer is only available as part of a zip file (named FileNet P8 Compatibility Layers for Content Engine APIs Help) on the IBM Information Management support page on www.ibm.com. To download this zip file from the IBM support page, see Accessing IBM FileNet documentation. The documentation consists of reference help (javadocs) updated to reflect the compatibility layer as well as the existing 3.5.x Developer's Guide (not updated for 4.x).

JDK

The JDK 1.3.x development environment is no longer supported; JDK 1.4.x is the supported development environment. Refer to IBM FileNet P8 Hardware and Software Requirements for complete information. To download this guide from the IBM support page, see Accessing IBM FileNet documentation.

Removed from the API

The following API members, which were previously deprecated, have been removed from the API.

Fields

Methods

Deprecated

This section summarizes what has been deprecated in the 4.0 release; sections below provide more information on these deprecations.

Properties

The following properties (and their associated Property constants) were deprecated in the 4.0 release. These properties are retained in the API for binary compatibility, but if used have no effect.

NOTES

Methods

In releases prior to 4.0, requests from the application server to the Content Engine server traveled over an HTTP connection, and the Content Java API included Session methods that allowed you to supply additional HTTP header information. Due to differences in transport architectures between Content Engine 3.x and 4.x, the following Session methods have been deprecated:

These methods are retained in the API for binary compatibility, but if used have no effect.

Error Reporting

Beginning in release 4.0, the Content Engine introduced a new error handling framework designed for the J2EE environment. A single, unchecked exception class is used, with an associated class identifying the exception more specifically. The Content Java API Compatibility Layer maps 4.x Content Engine API exceptions to appropriate 3.5.x Content Java API exceptions. In most cases, the same exception classes are thrown under the same circumstances in 4.x. There will be cosmetic differences in exception message text and in stack traces.

Security

Configurable JAAS Login Label

The Content Java API Compatibility Layer performs a JAAS login to accomplish authentication. Beginning in the 4.0 release, the default JAAS login label is "FileNetP8" and is case-sensitive. If appropriate, and as shown in the example below, the usual JAAS fallback label of "other" can also be used if there is no "FileNetP8" in your JAAS configuration:

other {
   weblogic.security.auth.login.UsernamePasswordLoginModule

      required debug=false;
};

The JAAS login label is configurable. To use a name other than the default "FileNetP8", you can edit the WcmApiConfig.properties configuration file with a text editor, setting or changing the value of the optional, case-insensitive JAASConfigurationName keyword. (Note also that the format of the remote server URLs has changed beginning in IBM FileNet P8 4.0, as shown in the example below.) This keyword=value pair is shown in the contents of the WcmApiConfig.properties file below:

RemoteServerUrl=cemp:iiop://CEserver:2809/FileNet/Engine
RemoteServerUploadUrl=cemp:iiop://CEserver:2809/FileNet/Engine
RemoteServerDownloadUrl=cemp:iiop://CEserver:2809/FileNet/Engine
jaasconfigurationName=MyLoginLabel
CredentialsProtection=Clear
CredentialsProtection/UserToken=Symmetric
CryptoKeyFile/UserToken=C:\\Program Files\FileNet\\Authentication\\
UTCryptoKeyFile.properties


Specifying the single value of "!" for the JAASConfigurationName keyword indicates that a JAAS login context is already in effect. Using "!" means that the Java compatibility layer will not perform the login step.

Extensible Authentication Framework

The Extensible Authentication Framework was introduced in IBM FileNet P8 3.5 to facilitate integration with Single-Sign-On (SSO) solutions that would not allow the transmission of a username and password to the IBM FileNet system. The IBM FileNet P8 4.0 release introduced a standards-based methodology for authentication using the J2EE Java Authentication and Authorization (JAAS) framework.

If you have implemented the Extensible Authentication Framework in your 3.5 application, you have two approaches you can take for the 4.x release: implement a JAAS-based solution or write a JAAS LoginModule using WS-EAF.

Implement a JAAS-based solution

This is the preferred approach for Java environments (assuming your solution is in an SSO environment using an industry-standard solution, such as IBM Tivoli Access Manager (TAM) or CA/Netegrity SiteMinder). This approach has the advantage of leveraging commodity SSO vendor components for all authentication infrastructure. However, this approach has the following considerations:

If you use this approach, you must:

  1. Install the SSO vendor's LoginModules on the Content Engine server.
  2. Install the SSO vendor's policy server in your environment (unless it is already in place).
  3. Install the SSO vendor's LoginModules on all client machines.
  4. Modify all applications to remove the legacy 3.5.2 Extensible Authentication logic that put custom credentials in the username and password fields.
  5. Modify all applications so that they run over the EJB transport, and they perform a JAAS login using the SSO LoginModules, prior to calling the server.

Write a JAAS LoginModule using the IBM FileNet Web Service Extensible Authentication Framework

This is the preferred approach if a non-standard SSO environment is in place (or if web services transport is needed). This approach has the following considerations:

If you use this approach, you must write a custom JAAS LoginModule on the server, conforming to IBM FileNet's 4.x Web Service Extensible Authentication Framework (WS-EAF). This custom LoginModule must extract the username and password values from the UsernameToken in the incoming WS-Security header, and must get the same custom values that were used in the 3.5.2 Extensible Authentication solution. It must then invoke whatever custom logic is required to authenticate based on those parameters. For more information, see the Web Service Extensible Authentication Framework Developer’s Guide.

Setting a Marking Property

In 3.5.x, if you attempted to set a property on a Marking object to which you did not have Add rights (Permission.RIGHT_ADD_MARKING), the Content Java API would throw a BadPropertyValueException. Beginning in release 4.0, an InsufficientPermissionException is thrown.

Directory Service Lookups

In IBM FileNet P8 3.5.x, LDAP directory lookups could be done using a system configured account, or the user context. Beginning in release 4.0, directory service lookups based on the user context are no longer supported. If you have an existing application that enumerates users, more results might be returned in the 4.x release (since lookups done using the user context would have returned only those users and groups to which the user had access).

Pre-Windows 2000 Login Format

In 3.5.x, the Content Engine server supported a pre-Windows 2000 login format (domain\loginname) through Microsoft-specific authentication APIs. Beginning in release 4.0, the functionality is no longer directly available through the J2EE application server-based authentication modules. You are limited to what the application server supports (or the independent authentication provider that it uses) in terms of authentication login-name formats.

SecurityParent and SecurityFolder Properties

As of release 4.0, the SecurityParent property (on the Document and CustomObject classes) has been deprecated. If the SecurityParent property is set (by an existing application, for example), the new SecurityFolder property is assigned the value of the SecurityParent property. When upgrading to this release:

Changed Handling for UpdateSecurityEvent

If an object is subscribed to the UpdateSecurityEvent event and the security for an object changes, the system generates an UpdateSecurityEvent event. In releases prior to 4.0, modifying the security of a folder could also modify the security of the documents contained in that folder. The applicable access control entry would be physically copied, as inherited, from the parent folder to the child document. Because this modified a document's security descriptor, an UpdateSecurityEvent event was generated for each child document.

Beginning in release 4.0, the new dynamic security inheritance model does not copy the access control entries. Therefore, the system no longer generates the UpdateSecurityEvent for each affected (inheriting) object. In the case of a parent folder and multiple child documents, only a single UpdateSecurityEvent event is generated for the security modification performed on the folder.

An update to any object-valued property designated as "inheritable" in the metadata also generates an UpdateSecurityEvent event.

Transactions

Using the Content Java API Compatibility Layer, a Content Engine 3.5.x release caller can request transactional behavior only for batch processing. All methods of the batch are performed atomically within a new transaction context.

The caller view of a batch operation consists of the following sequence of actions:

  1. Initiating the batch using Session.startBatch.
  2. Accumulating work items into the batch (using standard method calls).
  3. Executing the batch using Session.executeBatch.

It is the executeBatch method that is performed atomically. Callers declare their intentions about transactional behavior via a boolean parameter on the startBatch call.

In summary, the Content Java API Compatibility Layer calls are executed without propagating transaction context. The single exception is the executeBatch method associated with a startBatch(asTransaction == true) call, which is executed as its own complete transaction.

Limitations

The individual work items of a Content Java API Compatibility Layer batch are performed on the client side (in a JVM other than that used by the Content Engine server). This imposes the following limitations:

Transaction Entries in the WcmApiConfig.properties File

The 3.5.x Content Java API is configured via the WcmApiConfig.properties file. Although the Session interface has methods for setting or accessing some specific configuration values, those related to transaction processing can be set only in the WcmApiConfig.properties file. The transaction-related entries are as follows:

Events and Subscriptions

Event Actions

Content Engine 3.5.x supported scripts and COM objects for event actions. Beginning in the 4.0 release, event actions must be Java-based. Any EventAction objects that your application uses must be modified to use a Java class instead of a script or a COM object. Furthermore, the Java class must be located on the server; it cannot be on a client and streamed to the server for execution as for CE 3.5.x. (For information on how to create a Java-based event action, see Work with event actions in the Help for Content Engine Administration.

In addition, changes in the following EventAction properties might require modifications in your application:

EnableOn* Subscription Properties Removed

The EnableOn* properties of the Subscription class and subclasses were deprecated in a release prior to 4.0. Beginning in the 4.0 release, these properties have been removed and attempting to access them will generate exceptions. If your existing code uses the properties, convert your code to instead use the SubscribedEvents property.

Priority Property Deprecated

In releases prior to 4.0, you could specify a value for the Priority property on a Subscription object. The property value was used to order the firing of subscriptions in response to an event. However, the server did not use this property, and therefore the property is no longer implemented in the 4.x Content Engine release, and its associated Property constant (PRIORITY) has been deprecated in the Content Java API Compatibility Layer.

Workflow Subscription Filter Expressions

In 3.5.x, a Process Engine filter expression could be supplied with a workflow subscription using the Expression property. This type of filter expression was evaluated by the Process Engine after the workflow event was launched. Because the filter expression evaluation occurred well after the original transaction was complete, this capability was inefficient and often inaccurate. In the 3.5.x documentation, we recommended that you use the FilterExpression property instead, as the FilterExpression property is evaluated within the transaction that initiates the event (before an event is queued).

Beginning in 4.0, the Expression property is no longer supported and its Property constant (EXPRESSION) has been deprecated. During the upgrade to Content Engine 4.x, if the Expression property contains a value, then the value will be moved to the FilterExpression property (but only if the FilterExpression property was not populated with a value). If both properties were populated with a value, then the upgrade tool will not move the contents of the Expression property but will produce a report of these cases.

NOTE The Expression property supported certain SQL syntax that is not supported in the FilterExpression property. Specifically, with the exception of the LIKE operator, all other operators requiring a database query (such as the EXISTS operator) are not supported in the FilterExpression property. For a list of unsupported operators, see FilterExpression Property in the Content Engine Java and .NET Developer's Guide.

If your application uses the Expression property, you must modify your code to use the FilterExpression property instead. In addition, if any 3.5.x Expression values included a SQL operator that is not supported in the FilterExpression property, you must resolve these instances by either programmatically setting the value of the FilterExpression property to a string that includes only supported operators or by using Enterprise Manager to correct the value.

IsolatedRegion Property Deprecated

Beginning in the 4.0 release, the IsolatedRegion property on the ClassWorkflowSubscription and InstanceWorkflowSubscription classes has been renamed to IsolatedRegionNumber. The old property (IsolatedRegion) is deprecated, but existing code that accesses this property will continue to work.

Query

Content Based Retrieval

Content Engine 3.5.x integrated the Verity VDK for CBR. Beginning in Content Engine 4.0, Autonomy K2 (the former Verity product) is integrated for CBR. The following changed search behaviors are a result of integrating Autonomy K2 as the CBR engine:

For more information, see the SQL Syntax Reference topic in the Content Engine Java and .NET Developer's Guide.

Query Results

If your application uses the Search or StoredSearch interfaces to perform a query that retrieves all information from a Content Engine 4.x table (using SELECT *), a much larger result set will be returned than in Content Engine releases prior to 4.0. This is because previously, many system properties were marked as not selectable. Beginning in Content Engine 4.0, all properties are selectable. Some of the newly selectable properties can be quite large; in particular, any properties of type ListOfObject (such as Permissions or PropertyDefinitions). This extra data can cause an increase in response times for queries. For any application that traverses all properties in a result set, this can cause a further increase in response time, and could change behavior if new, unexpected data types are encountered. Queries that specify an explicit list of columns in their SELECT clause will not be affected.

Using MAXRECORDS and TOP N

In 3.5.x, you could specify both MAXRECORDS as a query option and TOP N as part of the query. Beginning in the 4.0 release, doing this will result in an invalid SQL statement because the Content Java API Compatibility Layer converts MAXRECORDS into a TOP N.

Query-related ObjectStore Properties

The following query configuration-related properties on an ObjectStore are no longer supported:

Beginning in the 4.0 release, the functionality supplied by these properties has been replaced with properties on the new ServerCacheConfiguration class:

Any existing code that accessed the ObjectStore properties will no longer function. The new properties are not accessible from the Content Java API.

Auditing

In releases prior to 4.0, attempting to modify properties for which the user did not have appropriate access rights was recorded as an audit failure by the Content Engine. However, beginning in the 4.0 release, the Content Java API Compatibility Layer will sometimes throw an exception on the client, and therefore will not record the failed attempt in the audit log. (Only operations executed on the Content Engine server can be audited; failed or successful client operations are not audited by the server.)

Document Lifecycle and Classification Actions

Content Engine 3.5.x supported Microsoft ActiveScript technology for document lifecycle actions and document classification actions. Beginning in the 4.0 release, lifecycle and classification actions must be Java-based. Furthermore, the Java class must be located on the server; it cannot be on a client and streamed to the server for execution as was done in Content Engine 3.5.x. Although any existing Content Engine actions must be rewritten to use Java, there are no code changes needed to existing 3.5.x Content Java API applications. For information on how to create a document classification action, see Understanding automatic document classification in the Help for Content Engine Administration.

Feature AddOns

Content Engine 3.5.x supported Microsoft ActiveScript technology for pre-install/post-install scripts for Feature AddOns. Beginning in Content Engine 4.0, only JavaScript scripting is supported. If your application creates FeatureAddOn objects and uses any pre-import or post-import scripts written in VBScript, you must:

ServerEnvironment Class

The 3.5.x Content Java API includes the ServerEnvironment utility class, which is used to gather information for support personnel for configuration problems with the Application server or Content Engine server. Although this class remains in the Content Java API Compatibility Layer, differences in Content Engine platform technologies from 3.5.x to 4.0 have made this class unsupportable in Content Engine 4.x and in the compatibility layer. Methods called on this class will return exceptions.

MimeType

In releases prior to 4.0, when a Content Java API application did not supply the MimeType for a document's or annotation's ContentTransfer element, the 3.x Content Engine used file extension mappings in the Windows registry along with Microsoft APIs to examine the ContentTransfer element's content. Beginning in the 4.0 release, the Content Engine identifies the MimeType based on a fixed listing of file extensions. Because of this, the resulting (identified) MimeType can be different from that identified by Content Engine 3.5.x. To ensure that a ContentTransfer element's MimeType is identified properly, explicitly specify the MimeType in the passed-in instance of the TransportInputStream when calling setContent on a Document or Annotation object.

VersionSeries Security

In releases prior to 4.0, if a user attempted to retrieve a VersionSeries object for which he did not have access rights to the current version, the VersionSeries object would be returned. In the 4.0 release, if the user does not have access rights to the current version, a null VersionSeries object is returned.

PropertyDescription DateTime Values

In 3.x releases, if you specified a date earlier than 1 Jan 1753 (which was the constraint specified by the PropertyMinimumDateTime property on the PropertyDescriptionDateTime class) for a custom property, the Content Engine server silently changed the date to 1 Jan 1753. Beginning in the 4.0 release, the PropertyDescriptionDateTime class has been updated to reflect the database-specific limits on date/time values. System and custom property values exceeding the database constraints will generate an exception. If your 3.5.x application relied on the above-mentioned PropertyMinimumDateTime behavior, you should modify your application to either pre-validate the date/time values, or to catch the BadPropertyValueException exception.

Java SecurityManager

Use of java.lang.SecurityManager, which is a class that allows applications to implement a security policy, is not supported for the Content Java API Compatibility Layer (or for the 4.0 or later Content Engine Java API). Access to Java system properties and other resources and capabilities is controlled by the Java SecurityManager, and the IBM FileNet Java APIs might periodically need to read or update those resources.

Exception When Attempting to Modify Root Folder Properties

In releases prior to 4.0, attempting to move a root folder generated a ContentEngineUnsupportedOperationException. Beginning in the 4.0 release, an InsufficientPermissionException is thrown. (Note that the InsufficientPermissionException is also thrown in the 4.x release if you attempt to change a root folder's name or delete a root folder.)

Retrieving an ObjectStore's ClassDescription

In releases prior to 4.0, if you retrieved the ClassDescriptions property for an ObjectStore, the ClassDescription for that ObjectStore would be included in the collection. Beginning in the 4.0 release, this is no longer the case. However, as in 3.5.x, you can continue to retrieve the ClassDescription for an ObjectStore by retrieving the ClassDescription property on the ObjectStore object.

Publishing

Copy publishing

In releases prior to 4.0, copy publishing (that is, publishing without doing a transform, which renders the content to a new format) was a synchronous process. Beginning in the 4.0 release, copy publishing is an asynchronous process. You will need to modify any applications that synchronously wait for the operation to complete. Also, less security will be required to complete the operation (similar to the security required for rendition publishing).

PublishRequests

Beginning in the 4.0 release, the PublishRequest class is a subclass of the new Subscribable class. Because of this, PublishRequest objects no longer inherit properties from the CustomObject class. In addition, some PublishRequest properties have been renamed or removed in the 4.0 release. Although it is unlikely that any PublishRequest code used these properties, you must modify any existing code that attempts to access or manipulate these properties as these attempts will result in an exception being thrown. The following table identifies these properties:

Properties No Longer Available on the PublishRequest Class
AccessMask LockTimeout OIID
ActiveMarkings LockToken Owner
Annotations Name SecurityParent
Containers ObjectStore SecurityPolicy
LockOwner ObjectType WorkflowSubscriptions

In addition, the TargetDocument property is no longer supported. In releases prior to 4.0, this property was used as a placeholder for saving the resultant publication object while it was being created during the copy publishing process (which was a synchronous process). You could retrieve the resultant target document when the publish operation completed. For example:


PublishRequest pr = document.publish(publishTemplate, pubOptions);

Document target = (Document) pr.getPropertyValue(Property.TARGET_DOCUMENT);

However, beginning in the 4.0 release, the publishing process does not require this placeholder as the copy publish process is handled asynchronously. Therefore, any existing code that attempts to access this property must be modified.

The following table identifies PublishRequst properties that have been renamed in this release. You must modify any existing code to use these new names. Note that the Content Java API Compatibility Layer does not include Property constants for these new names. Also, although existing Property constants for the old names have not been deprecated, attempting to use them will throw an exception.

PublishRequest Property New Name for Property in 4.x Release
ErrorCategory (of type Integer) ErrorCode (of type String) (see NOTES)
Options PublishRequestType
PublishingPluginServer DequeueHost
RetryNumber RetryCount
Status PublishingStatus (see NOTES)
StyleTemplate PublishStyleTemplate

NOTES

GCD Changes

In releases prior to 4.0, the GCD (Global Configuration Data) was stored in the local file system. Beginning in the 4.0 release, the GCD is generally stored in a separate database instance, leveraging the RDBMS used by Content Engine.

During the upgrade operation from IBM FileNet P8 3.5.x, the DateCreated and Creator properties for the following objects are replaced with the date of the upgrade and the name of the user performing the upgrade, respectively:

The DateCreated and Creator properties are not changed by the upgrade operation for objects that reside within an object store (such as Documents, Folders, and CustomObjects).