IBM FileNet Content Manager
Java API Programming
(Course code F005G)
Instructor Guide Book 1 of 2
Trademarks
IBM® is a registered trademark of International Business Machines Corporation.
IBM, the IBM logo, and FileNet are trademarks of IBM Corporation in the United States,
other countries or both. All other company or product names are registered trademarks or
trademarks of their respective companies.
Windows is a trademark of Microsoft Corporation in the United States, other countries, or
both.
Other company, product, or service names may be trademarks or service marks of others.
July 2007 edition
The information contained in this document has not been submitted to any formal IBM test and is distributed on an “as is” basis without
any warranty either express or implied. The use of this information or the implementation of any of these techniques is a customer
responsibility and depends on the customer’s ability to evaluate and integrate them into the customer’s operational environment. While
each item may have been reviewed by IBM for accuracy in a specific situation, there is no guarantee that the same or similar results
will Result elsewhere. Customers attempting to adapt these techniques to their own environments do so at their own risk.
©Copyright International Business Machines Corporation 2007. All rights reserved.
This document may not be reproduced in whole or in part without the prior written permission of IBM.
Note to U.S. Government Users — Documentation related to restricted rights — Use, duplication or disclosure is subject to restrictions
Set forth in GSA ADP Schedule Contract with IBM Corp.
TOC
TOC
Contents
Instructor Guide: Book 1
Module 0:
Course Introduction
Module 1:
Content Engine Java API Overview
Module 2:
Communication with the Content Engine
Module 3:
Folders
Module 4:
Custom Objects
Module 5:
Documents
Module 6:
Properties
Module 7:
Searches
Module 8:
Security
Instructor Guide: Book 2
Module 9:
Document Versions
Module 10:
Document Lifecycle
Module 11:
Publishing
Module 12:
Compound Documents
Module 13:
Annotations
Module 14:
Auditing
Module 15:
Events and Subscriptions
Appendix A:
Batches
Rev. 1.0
i
Contents
ii
Rev. 1.0
0
0
Course Introduction
Java API Programmer
IBM FileNet Content Manager
Java API Programming
IBM FileNet Content Manager
Instructor Notes:
None
Rev 1.0
Course Introduction
1
Course Introduction
Rev 1.0
Course Introduction
2
Course Introduction
Course Introduction
IBM FileNet Content Manager Java API Programming
Course Modules and Appendix
0. Course Introduction
9. Document Versions
1. Content Engine Java API
Overview
2. Communication with the
Content Engine
3. Folders
4. Custom Objects
5. Documents
10. Document Lifecycle
6. Properties
Appendix A: Batches
11. Publishing
12. Compound Documents
13. Annotations
14. Auditing
15. Events and Subscriptions
7. Searches
8. Security
3
ADDITIONAL INFORMATION
This course has fifteen modules. Although, the activities of the most modules are relatively independent, they
often rely on concepts presented in the previous modules. For best results, study the course modules in the
sequence presented.
Instructor Notes:
None
Rev 1.0
Course Introduction
3
Course Introduction
Course Introduction
This Course Is for You If…
Your organization has purchased an IBM FileNet P8
solution.
You will write code for a business application:
y That runs on the IBM FileNet P8 Platform.
y That manages content on the P8 Content Engine.
You need to understand the Java API for the
Content Engine.
4
Instructor Notes:
None
Rev 1.0
Course Introduction
4
Course Introduction
Course Introduction
Course Materials
Student System
y An IBM FileNet P8 Content Manager system
Student Guide
y Slides
y Information references (Help, documents)
y Area for notes
Student Workbook
y Lab exercises
5
Instructor Notes:
None
Rev 1.0
Course Introduction
5
Course Introduction
Course Introduction
Course Orientation
Breaks
Lunch
Restrooms
Phones
Emergency information
Class survey
6
Instructor Notes:
None
Rev 1.0
Course Introduction
6
Course Introduction
Course Introduction
Introductions
Your name
Your company
Your job function
Any FileNet product background you have
FileNet ECM project you support
Your goals for attending this course
Your questions or concerns
7
Instructor Notes:
None
Rev 1.0
Course Introduction
7
Course Introduction
Rev 1.0
Course Introduction
8
1
1
Content Engine Java API Overview
Java API Programmer
Content Engine Java API Overview
IBM FileNet Content Manager
Instructor Notes:
None
Rev 1.0
Content Engine Java API Overview
1
Content Engine Java API Overview
Rev 1.0
Content Engine Java API Overview
2
Content Engine Java API Overview
Content Engine Java API Overview
This module consists of the following lessons:
y Content Engine Java API Concepts
y Content Engine Objects
3
Instructor Notes:
None
Rev 1.0
Content Engine Java API Overview
3
Content Engine Java API Overview
Rev 1.0
Content Engine Java API Overview
4
Content Engine Java API Overview
Module: Content Engine Java API Overview
Lesson:
Content Engine Java API Concepts
5
Instructor Notes:
None
Rev 1.0
Content Engine Java API Overview
5
Content Engine Java API Overview
Content Engine Java API Concepts
Scenario
y Your company has purchased a FileNet P8 system and
plans to manage their content using the
FileNet P8 Content Engine. As their programmer, you want
an orientation to the FileNet P8 Content Engine Java API,
which you will use to write a custom application for the
company.
6
Instructor Notes:
None
Rev 1.0
Content Engine Java API Overview
6
Content Engine Java API Overview
Content Engine Java API Concepts
FileNet P8 Architecture
7
Reference
FileNet P8 System Guide
Rationale
This high-level architecture diagram shows where the various engines fit within a FileNet P8 system.
ADDITIONAL INFORMATION
The Application Engine is part of the presentation layer.
Instructor Notes:
None
Rev 1.0
Content Engine Java API Overview
7
Content Engine Java API Overview
Content Engine Java API Concepts
Content Engine and J2EE
IBM FileNet P8 4.0 Content Engine
y Built on the J2EE platform
y Implemented within a J2EE standards-compliant
application server
y Supports a wide variety of
– Operating systems
– Directory service providers
– Application servers
– Database servers
8
ADDITIONAL INFORMATION
The Content Engine can support a wide variety of environments (examples follow) because it is implemented within
a J2EE standards-compliant application server environment:
• Operating systems examples: Microsoft, Sun, IBM, Hewlett Packard, and Red Hat
• Directory service providers examples: Microsoft Active Directory, Novell eDirectory, IBM Tivoli Directory
Server, Sun Java System Directory Server
• J2EE compliant application servers examples: BEA, IBM, and JBoss
• Database servers examples: Microsoft SQL Server, Oracle Database, and IBM DB2
Instructor Notes:
None
Rev 1.0
Content Engine Java API Overview
8
Content Engine Java API Overview
Content Engine Java API Concepts
J2EE Architecture
9
ADDITIONAL INFORMATION
•J2EE (Java 2 Enterprise Edition) includes Java Specification enhancements that allow client-server applications to
work with different clients. The J2EE application server provides execution environments and services, which can be
used by clients (Web Container, EJB Container, and interfaces to resources such as JDBC, JMS, and JCA).
Defined and enhanced by Sun (not Open Source), Java is a programming language developed for using applets in
Web applications. The paradigm is “write once, run everywhere.” The compiler creates machine-independent byte
code (class file) execution required by JVM as runtime environment.
•Java Servlets define an API and framework for basic request and response processing.
•Java Server Pages define a standard for building dynamic Web pages using Java code and custom tag libraries.
•Enterprise JavaBeans describe a distributed-component model with built-in services, such as transaction
management, object pooling, and automated persistence.
•Web Container implements the Web component contract of the J2EE architecture.
•EJB Container is a software that runs on a server and manages the EJBs.
•JNDI (Java Naming and Directory Interface) provides a unified interface to multiple naming and directory services.
•JAAS (Java Authentication and Authorization Service) provides a set of APIs that enables services to authenticate
and enforce access controls on users.
JDBC (Java Database Connectivity) provides a generic API for access to relational databases.
•JMS (Java Message Service) provides generic API for accessing point-to-point and publish and subscribe queues.
•JCA (J2EE Connector Architecture) provides an abstraction layer between application components and Enterprise
Information Systems (EIS).
•JVM (Java Virtual Machine) is the runtime environment for byte code. Sun delivers JVM implementations for many
platforms, while other vendors (such as J2EE) implement custom JVMs (such as JRockit and IBM JVM).
•JRE (Java Runtime Environment) is JVM plus supporting class files.
•JDK/Java SDK (Java Development Kit) is the development environment, with a compiler, packager, and other tools.
•JTS/JTA (Java Transaction Service/Java Transaction API) API offers global transactions spanning multiple
resources.
Instructor Notes:
None
Rev 1.0
Content Engine Java API Overview
9
Content Engine Java API Overview
Content Engine Java API Concepts
Content Engine Supported Transport Protocols
10
The Content Engine supports two transport protocols:
y EJB (This course covers APIs that work on EJB)
y Content Engine Web Service (CEWS)
ADDITIONAL INFORMATION
Content Engine APIs provide common functionality for both Java and .NET application development.
Instructor Notes:
None
Rev 1.0
Content Engine Java API Overview
10
Content Engine Java API Overview
Content Engine Java API Concepts
Content Engine Java APIs
Content Engine Java APIs
y Provide classes for creating, accessing, and manipulating content
and objects
y Are platform neutral
y Are compatible with Enterprise JavaBeans (EJB) 2.0
The Content Engine Java APIs can be installed
y
During Content Engine installation
y Anywhere, including on a non-Content Engine system
11
Instructor Notes:
None
Rev 1.0
Content Engine Java API Overview
11
Content Engine Java API Overview
Content Engine Java API Concepts
Application Types Supported by the CE APIs
Runtime (end user) applications
y Interact with object stores
y Work with objects such as documents and folders
Administration applications
y Perform configuration tasks
y Examples:
– Add-ons - Product extensions to the core FileNet P8 Content Engine
components
– Defining audit-event parameters
Metadata authoring applications
y Create class definitions, properties, and so on
Note: This course includes mainly runtime application-type APIs.
12
ADDITIONAL INFORMATION
For a complete list of classes and interfaces that are used in the administration of the Content Engine Server,
refer to the package com.filenet.api.admin in ecm_help:
FileNet P8 Documentation > Developer Help > Content Engine Development > Java API Reference Java API
Reference
Instructor Notes:
None
Rev 1.0
Content Engine Java API Overview
12
Content Engine Java API Overview
Content Engine Java API Concepts
Required Java Archive (JAR) Files
For a Content Engine Java API EJB Transport Client
JAR File Name
Description
jace.jar
The core FileNet JAR file for the CE Java API;
includes the common JAR and transport JAR
log4j-1.2.13.jar
The LOG4J framework for CE Java API logging
An application
server-specific
JAR file
If already in an application server, this JAR file is
not required, except in a stand-alone JVM
13
HELP PATH
For the complete list of JAR files, refer to ecm_help:
FileNet P8 Documentation > Developer Help > Content Engine Development > Java and .NET Developer’s
Guide Getting Started > Concepts > Required JAR Files
ADDITIONAL INFORMATION
The required JAR files are installed with the Application Engine software. Refer to the online help at
ecm_help/installation/_install_guide.pdf for installing the Application Engine and to the FileNet P8
documentation.
By default, the JAR files are located in the C:\Program Files\FileNet\Workplace\WEB-INF\lib folder.
For the module activities, you will set up the class path for these JAR files in a batch file. You can also set up the
class path in the IDE.
Instructor Notes:
None
Rev 1.0
Content Engine Java API Overview
13
Content Engine Java API Overview
Content Engine Java API Concepts
Required JAR Files for FileNet P8 3.5.x
Compatibility
Required for a Content Java API Compatibility Layer client
(For IBM FileNet P8 3.5.x only)
JAR File Name
Description
javaapi.jar
The class implementation files for the
Content Java API compatibility layer
p8cjares.jar
The localizable resource strings
All JAR files for a
FileNet P8 4.0 CE
Java API client
jace.jar, log4j-1.2.13.jar, and an application
server-specific JAR
This table is informational only. This course deals with IBM
FileNet P8 4.0 Content Engine Java API only.
14
HELP PATH
For the complete list of JAR files, refer to ecm_help:
FileNet P8 Documentation > Developer Help > Content Engine Development > Java and .NET Developer’s
Guide Getting Started > Concepts > Required JAR Files
ADDITIONAL INFORMATION
These JAR files are only for the FileNet P8 3.5.x Java APIs. They are located in the C:\Program
Files\FileNet\Workplace\WEB-INF\lib folder of the IBM FileNet P8 3.5.x system set-up.
The FileNet P8 3.5.x application must be recompiled to run on the FileNet P8 4.0 system.
Instructor Notes:
IBM FileNet P8 3.5.x backward compatibility is included in 4.0 system. However, continued use of 3.5.x APIs is
discouraged, these APIs will be deprecated in near future.
Rev 1.0
Content Engine Java API Overview
14
Content Engine Java API Overview
Content Engine Java API Concepts
Commonly Used Content Engine Java Packages
Package Name
Description
com.filenet.api.core
Classes and interfaces related to the core
objects of the API
com.filenet.api.collection
Type-safe interfaces for collections of objects
com.filenet.api.constants
Classes defining collections of related, type-safe
constant values
com.filenet.api.query
Classes for performing CE searches
com.filenet.api.publishing
Interfaces related to publishing
com.filenet.api.security
Interfaces related to authentication,
authorization, and user- and group-specific data
com.filenet.api.action
Classes for making changes to objects.
com.filenet.api.exception
Exception-reporting framework for the CE
com.filenet.api.util
Utility classes and interfaces
15
Note: This list is not complete.
HELP PATH
For the complete list of Java Packages, refer to ecm_help:
FileNet P8 Documentation > Developer Help > Content Engine Development > Java and .NET Developer’s
Guide Getting Started > Concepts > Java Packages and .NET Namespaces
Note: These Java packages are contained in the jace.jar file.
Instructor Notes:
None
Rev 1.0
Content Engine Java API Overview
15
Content Engine Java API Overview
Content Engine Java API Concepts
Content Engine Authentication
The IBM FileNet P8 authentication process uses two
standards:
1. Java Authentication and Authorization Service (JAAS)
– The framework for security interoperability in a J2EE
environment
2. Web Services Security standard (WS-Security)
– The framework in the heterogeneous environment of
clients and servers that communicate through Web
services interfaces
Note: This course uses JAAS.
16
HELP PATH
FileNet P8 Documentation > FileNet P8 Administration > Enterprise-wide Administration > FileNet P8 Security >
> Authentication
ADDITIONAL INFORMATION
The Content Engine Enterprise JavaBeans (EJB) resides within the J2EE Application Server EJB container.
The CE EJB is therefore accessible only by authenticated callers, those who can pass any authorization checks
that the administrator has placed on the EJB.
Instructor Notes:
None
Rev 1.0
Content Engine Java API Overview
16
Content Engine Java API Overview
Content Engine Java API Concepts
Java Authentication and Authorization Service (JAAS)
JAAS –
Provides a
framework
for securely
determining
who is
invoking a
Java
application.
.
17
HELP PATH
FileNet P8 Documentation > FileNet P8 Administration > Enterprise-wide Administration > FileNet P8 Security >
> Authentication
ADDITIONAL INFORMATION:
JAAS configurations
To use a J2EE-based application, a client must first perform a JAAS log-in by specifying a JAAS configuration
(in a file).
The JAAS configuration specifies the authentication technologies (LoginModules) that will be used to verify the
client's credentials.
A JAAS configuration file lists one entry for each configured application. Within an application entry is a list of
LoginModules for that application. Based on the contents of the configuration file, the JAAS framework
dynamically determines which set of authentication technologies to invoke when a client application attempts to
authenticate.
JAAS LoginContexts
A J2EE client application must specify a JAAS configuration and a mechanism through which credentials can be
obtained from a user at run time. These two items constitute a JAAS LoginContext. J2EE client applications use
the LoginContext to interact with JAAS and to authenticate themselves to a J2EE server.
JAAS LoginModules
JAAS-compliant LoginModules are implemented by authentication technology providers. J2EE application
server vendors, such as BEA, IBM, and JBOSS, typically provide LoginModules for standard types of
credentials, such as username and password
JAAS Subjects
When a JAAS log-in has successfully completed, a JAAS Subject is returned to the caller. The Subject is a key
J2EE class, which is transparently sent between J2EE clients and J2EE servers any time an EJB is invoked.
A JAAS Subject contains the set of JAAS principals (authenticated identities) and JAAS credentials
(authentication data such as cryptographic keys) that result from the log-in process. Each LoginModule that
successfully authenticates the user updates the Subject with information about the user. A J2EE server
application can examine the principals in the Subject to establish the caller's identity.
Instructor Notes:
None
Rev 1.0
Content Engine Java API Overview
17
Content Engine Java API Overview
Content Engine Java API Concepts
JAAS configuration files
Must establish a JAAS context prior to any requests
to the CE Server
The FileNet P8 CE installation provides JAAS
configuration sample files
y Examples:
– jaas.weblogic.config
– jaas.websphere.config
Legacy support
y CE API does an internal JAAS log-in
y The client environment must include a proper JAAS
configuration
y The username and password model using the UserContext
class is not supported
18
HELP PATH
FileNet P8 Documentation > FileNet P8 Administration > Enterprise-wide Administration > FileNet P8 Security >
> Authentication
ADDITIONAL INFORMATION
The client application obtains a JAAS Subject prior to calling the Content Engine Java API. Interactions with the
CE Java API cause the Content Engine EJB to be invoked. The client's JAAS subject is transparently sent to the
J2EE application server with each EJB call. The application server validates the JAAS subject and confirms the
caller's identity before executing any code in the Content Engine EJB.
Instructor Notes:
None
Rev 1.0
Content Engine Java API Overview
18
Content Engine Java API Overview
Content Engine Java API Concepts
Resources
Documentation is installed with the Application Engine
y http://<AEHost>:9080/ecm_help (for WebSphere)
Developers Help for Content Java API
y FileNet P8 Documentation > Developer Help > Content Engine
Development > Java and .NET Developer's Guide
Javadocs for Content API
y FileNet P8 Documentation > Developer Help > Content Engine
Development > Java API Reference
Other sites
y http://java.sun.com
19
Instructor Notes:
None
Rev 1.0
Content Engine Java API Overview
19
Content Engine Java API Overview
Content Engine Java API Concepts
Activities
Explore the Java API Documentation
y Use the links given on the preceding slide to
– Locate the Content Engine developer help
documents
– Locate the Java API Reference that contains java
API classes
20
Java Packages and .NET Namespaces
Instructor Notes:
None
Rev 1.0
Content Engine Java API Overview
20
Content Engine Java API Overview
Module: Content Engine Java API Overview
Lesson:
Content Engine Objects
21
Instructor Notes:
None
Rev 1.0
Content Engine Java API Overview
21
Content Engine Java API Overview
Content Engine Objects
Base Classes and Interfaces on the Content Engine
Many of the methods available in the CE APIs are exposed through
inheritance
Important base classes and interfaces
y EngineObject
– Top-level interface
y
y
y
y
y
y
y
RepositoryObject
IndependentObject and DependentObject
IndependentlyPersistableObject
Subscribable Object
Containable Object
Versionable Object
Core Objects
– Core Business Objects of the CE API
22
Instructor Notes:
None
Rev 1.0
Content Engine Java API Overview
22
Content Engine Java API Overview
Content Engine Objects
Interface Hierarchy
interface java.io.Serializable
EngineObject
Containable
Document
also extends
RepositoryObject
Versionable
Subscribable
IndependentObject
IndependentlyPersistableObject
CustomObject
also extends
RepositoryObject
Subscribable
IndependentObject
IndependentlyPersistableObject
23
HELP PATH
For more details on the interface or class hierarchy, refer to ecm_help:
…\ecm_help\developer_help\content_java_api\javadocs\overview-tree.html
ADDITIONAL INFORMATION
All the interfaces mentioned in the diagram are part of the com.filenet.api.* packages.
Notice that Document and CustomObject interfaces are similar in their hierarchy, except that the Document
interface also extends the VersionableObject interface to manage the content.
CustomObject does not have content.
Instructor Notes:
None
Rev 1.0
Content Engine Java API Overview
23
Content Engine Java API Overview
Content Engine Objects
EngineObject and RepositoryObject
EngineObject
y Represents the top-level interface from which most of the
other CE API interfaces derive
y Is any object known to the CE including objects outside of
repositories
y Examples: Domain, MarkingSet, ObjectStore, and User
objects
RepositoryObject
y Is any object known to the CE that resides within an object
store
y Example: A Document object
24
ADDITIONAL INFORMATION
EngineObject
•Normally an instance of one of the EngineObject’s subclasses Is used.
•Provides base functionalities such as retrieving
- The Connection object that is used for communication to the CE server
- The class information and properties of an object
RepositoryObject
•Normally an instance of one of the RepositoryObject subclasses is used.
Instructor Notes:
None
Rev 1.0
Content Engine Java API Overview
24
Content Engine Java API Overview
Content Engine Objects
IndependentObject and DependentObject
EngineObject
IndependentObject
y Has its own identity and always has an ObjectReference
DependentObject
y Exists within the scope of another object
y Is saved to the server when attached as a child of an
IndependentObject
y Has identity and security that are derived from its parent
object
25
ADDITIONAL INFORMATION
IndependentObject
•Can be fetched from the server with a call to
InstantiatingScope.fetchObject Factory.<classname>.fetchInstance.
• Examples: Document, Folder, and CustomObject
DependentObject
•Is fetched using a property of parent object.
•Is saved to the server when attached as a child of an IndependentObject.
•Has a corresponding list-type collection.
•Examples: ContentElementList, PermissionList, and ChoiceList
•Has identity and security that are derived from its parent object.
•Examples: ContentElement, Permissions, PropertyDefinitions, and Choices
Instructor Notes:
None
Rev 1.0
Content Engine Java API Overview
25
Content Engine Java API Overview
Content Engine Objects
Base Classes and Interfaces
IndependentlyPersistableObject
y Is a persistable IndependentObject that you can create, update, and
delete directly
Subscribable Object
y Serves as the target of an event subscription, represented by a
Subscription-based object
Versionable Object
y Represents the base class for classes whose instances are
versionable objects.
Containable Object
y Represents the base class for all objects that can be contained
26
ADDITIONAL INFORMATION
Versionable Object
•Can have multiple associated versions in an object store.
•Can be checked out, optionally edited, and checked in.
Containable Object
•All Containable subclasses are referentially contained except the Folder object.
•Folder objects and their subclasses can be directly contained in a Folder object.
Instructor Notes:
None
Rev 1.0
Content Engine Java API Overview
26
Content Engine Java API Overview
Content Engine Objects
Core Objects of the API
Object
Description
Connection
Holds the information required for an application to
connect to the FileNet P8 domain resources
ObjectStore
An independent, domain-scoped object that provides
access to resources
Folder
A container that hold other containable objects
Document
A single version of a document in a object store
CustomObject
A general object that has no content
Annotation
Information that can be attached to an object
27
Instructor Notes:
None
Rev 1.0
Content Engine Java API Overview
27
Content Engine Java API Overview
Content Engine Objects
Instantiating Objects – Factory Class
CE Java APIs are defined as interfaces
y Cannot instantiate new objects using the "new" construct
y Must use a Factory class method to instantiate type-appropriate
objects
Factory class has static inner classes
y Names parallel the standard CE API types
– Example: Factory.Document
Factory methods are convenient and provide type safety
y No need to cast the Factory method results to a desired type
y Identify programming errors on the returned type at compile time
instead of at run time
y The following methods are available for instantiating objects:
– createInstance
– fetchInstance
– getInstance
28
Instructor Notes:
None
Rev 1.0
Content Engine Java API Overview
28
Content Engine Java API Overview
Content Engine Objects
Collection Objects
CE collections are
y Groups of related elements
y Strongly typed (contain single type objects)
y Two types: List and Set
List-type collection
y Is a group of dependent objects or a list of primitive data items
y Has a parent object to which it is scoped
y Is instantiated with the createList() method on the type-specific Factory
class
y Can be updated directly using type-safe methods
y Elements of a list are ordered and need not be unique
y Examples: ContentElementList, SecurityTemplateList
Set-type collection
y Is a group of independent objects
y Cannot be updated directly
y Elements of a set are unordered and unique (some exceptions)
y Examples: ObjectStoreSet, DocumentSet, FolderSet
29
Instructor Notes:
None
Rev 1.0
Content Engine Java API Overview
29
Content Engine Java API Overview
Content Engine Objects
Activities
Explore the Java API Documentation
y Use the links provided in the preceding
lesson to
– Locate the Java API Reference that contains java
API classes
30
Instructor Notes:
None
Rev 1.0
Content Engine Java API Overview
30
2
2
Communication with the Content Engine Server
Java API Programmer
Communication with the Content Engine
IBM FileNet Content Manager
Instructor Notes:
None
Rev 1.0
Communication with the Content Engine Server
1
Communication with the Content Engine Server
Rev 1.0
Communication with the Content Engine Server
2
Communication with the Content Engine Server
Communication with the Content Engine
This module consists of these lessons:
y Get a Connection to a FileNet P8 Domain
y Retrieve the Domain and the Object Stores
3
Instructor Notes:
None
Rev 1.0
Communication with the Content Engine Server
3
Communication with the Content Engine Server
Rev 1.0
Communication with the Content Engine Server
4
Communication with the Content Engine Server
Communication with the Content Engine
Lesson:
Get a Connection to a FileNet P8 Domain
5
Instructor Notes:
None
Rev 1.0
Communication with the Content Engine Server
5
Communication with the Content Engine Server
Get a Connection to a FileNet P8 Domain
Scenario
y Your company manages its content using the IBM FileNet
Content Manager. As their programmer, you will write code
to communicate with the Content Engine server by getting
a connection to a FileNet P8 Domain.
6
Instructor Notes:
None
Rev 1.0
Communication with the Content Engine Server
6
Communication with the Content Engine Server
Get a Connection to a FileNet P8 Domain
Lesson Objectives
In this lesson, you will
y Write code to get a connection to a FileNet P8 domain
7
Instructor Notes:
None
Rev 1.0
Communication with the Content Engine Server
7
Communication with the Content Engine Server
Get a Connection to a FileNet P8 Domain
Java API Methods Presented in This Lesson
Factory.Connection.getConnection(…)
UserContext.createSubject(…)
UserContext.get()
userContext.pushSubject(…)
8
Instructor Notes:
None
Rev 1.0
Communication with the Content Engine Server
8
Communication with the Content Engine Server
Get a Connection to a FileNet P8 Domain
Connection Object
The Connection object
y Represents a logical connection to a FileNet P8 domain
y Contains information for configuration options:
– Needed to execute an operation on the CE server
– A URI includes the transport protocol (connection type), host name,
and port number
All engine objects maintain a reference to the
connection instance
y You retrieve it by calling the getConnection method of the
engine object
9
ADDITIONAL INFORMATION
An incorrect configuration is the most frequent cause of an exception related to a connection failure.
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.
Instructor Notes:
None
Rev 1.0
Communication with the Content Engine Server
9
Communication with the Content Engine Server
Get a Connection to a FileNet P8 Domain
Steps to Get a Connection to a FileNet P8 Domain
1. Create a new Connection object
Factory.Connection.getConnection(…)
2. Authenticate with the application server
UserContext.createSubject(…)
3. Get the UserContext object associated with the current thread
UserContext.get()
4. Make the specified JAAS Subject active
userContext.pushSubject(…)
10
Instructor Notes:
None
Rev 1.0
Communication with the Content Engine Server
10
Communication with the Content Engine Server
Get a Connection to a FileNet P8 Domain
Factory.Connection.getConnection(…)
public static Connection getConnection(String uri)
Parameters
y uri - Specify the Universal Resource Identity (URI) for this connection
WebLogic - t3://servername:port/FileNet/Engine
WebSphere - iiop://servername:port/FileNet/Engine
Returns
y A Connection object
Notes:
y A domain connection is required to obtain a reference to any object
y
stored within that domain.
This method uses default configuration parameters.
11
ADDITIONAL INFORMATION
•There is another variation of this method (takes additional parameter for configuration):
public static Connection getConnection(java.lang.String uri,
ConfigurationParameters parameters)
•Configuration parameters represent a group of parameters that defines the behavior of the client API.
•The method discussed in the slide is equivalent to calling getConnection(uri, new ConfigurationParameters()).
Instructor Notes:
None
Rev 1.0
Communication with the Content Engine Server
11
Communication with the Content Engine Server
Get a Connection to a FileNet P8 Domain
UserContext.createSubject(…)
public static javax.security.auth.Subject
createSubject(Connection conn,
String user, String password,
String optionalJAASStanzaName)
Parameters
y
y
y
y
conn - Specify the Connection object for this thread; cannot be null
user - Specify the username to be authenticated
password - Specify the user’s password
optionalJAASStanzaName - Specify the JAAS configuration stanza
name.
– If it is null, the stanza name defaults to “FileNetP8”
Returns
Notes
y JAAS Subject object
y
The client must be properly configured for JAAS.
12
ADDITIONAL INFORMATION
•This method uses standard JAAS calls to authenticate with the application server and return a JAAS Subject
object.
•The calling code can optionally provide a JAAS configuration stanza name.
•The returned Subject has no association to the current user context. The caller must use the Subject with the
UserContext.
Instructor Notes:
None
Rev 1.0
Communication with the Content Engine Server
12
Communication with the Content Engine Server
Get a Connection to a FileNet P8 Domain
UserContext.get()
public static UserContext get()
Parameters
y Nothing
Returns
y A UserContext object associated with the current thread
Notes
y When no user context has been set, a default user context exists
containing the current locale default from the JVM
13
Instructor Notes:
None
Rev 1.0
Communication with the Content Engine Server
13
Communication with the Content Engine Server
Get a Connection to a FileNet P8 Domain
userContext.pushSubject(…)
public void pushSubject
(javax.security.auth.Subject sub)
Parameters
y sub - The JAAS Subject to be associated with the thread
– Cannot be null
Returns
y Nothing
Notes
y This method saves any previously active Subject and makes
the specified Subject active.
14
ADDITIONAL INFORMATION
To restore the previous Subject, call the popSubject() method.
Instructor Notes:
None
Rev 1.0
Communication with the Content Engine Server
14
Communication with the Content Engine Server
Get a Connection to a FileNet P8 Domain
Sample Code to Get a Connection to a FileNet P8
Domain
String uri =
"t3://localhost:7001/FileNet/Engine";
String username = "Administrator";
String password = "filenet";
Connection conn =
Factory.Connection.getConnection(uri);
Subject subject = UserContext.createSubject
(conn, username, password, null);
UserContext uc = UserContext.get();
uc.pushSubject(subject);
15
Instructor Notes:
None
Rev 1.0
Communication with the Content Engine Server
15
Communication with the Content Engine Server
Get a Connection to a FileNet P8 Domain
Activities
In your workbook, see
y Lesson: Get a Connection to a FileNet P8
Domain
Complete this activity
y Get a Connection to a FileNet P8 Domain
16
Instructor Notes:
Students need to copy the \Source\ subfolder from C:\CMJavaAPIProgMaterials to C:\.
We ask them to copy these files so that that the students can type the short folder names without spaces in the DOS
window.
Also make and run bat files assume this folder structure.
Rev 1.0
Communication with the Content Engine Server
16
Communication with the Content Engine Server
Communication with the Content Engine
Lesson:
Retrieve the Domain and the Object Stores
17
Instructor Notes:
None
Rev 1.0
Communication with the Content Engine Server
17
Communication with the Content Engine Server
Retrieve the Domain and the Object Stores
Scenario
y You need to access the Domain object to retrieve other
objects in the domain. As a programmer for the Content
Manager, you will write code to retrieve the Domain and the
ObjectStore objects.
18
Instructor Notes:
None
Rev 1.0
Communication with the Content Engine Server
18
Communication with the Content Engine Server
Retrieve the Domain and the Object Stores
Lesson Objectives
In this lesson, you will
y Write code to retrieve the Domain and the ObjectStore
objects.
19
Instructor Notes:
None
Rev 1.0
Communication with the Content Engine Server
19
Communication with the Content Engine Server
Retrieve the Domain and the Object Stores
Java API Methods Presented in This Lesson
Factory.Domain.fetchInstance(…)
domain.get_ObjectStores()
20
Instructor Notes:
None
Rev 1.0
Communication with the Content Engine Server
20
Communication with the Content Engine Server
Retrieve the Domain and the Object Stores
Domain Object
The Domain object
y Represents a collection of resources and services sharing the
same Global Configuration Database (GCD)
y Is associated with one or more security realms for authenticating
users
The Java API
y Cannot create a new Domain object
y Can retrieve an already persisted Domain object
21
Instructor Notes:
None
Rev 1.0
Communication with the Content Engine Server
21
Communication with the Content Engine Server
Retrieve the Domain and the Object Stores
GCD and Domain Objects
For each Domain object, the GCD defines a common
set of attributes
y Attributes control the functional characteristics of resources and
services for the domain
Domain resources
y Sites and their virtual servers and server instances
y Object store databases
y Full-text index areas
y File storage areas
y Content cache areas
y Add-ons
y Marking sets
22
Instructor Notes:
None
Rev 1.0
Communication with the Content Engine Server
22
Communication with the Content Engine Server
Retrieve the Domain and the Object Stores
Steps to Retrieve a Domain and Objectstores
1. Get the Domain Object
Factory.Domain.fetchInstance(…)
2. Get the Objectstores
domain.get_ObjectStores()
23
ADDITIONAL INFORMATION
An object-valued Domain property can also be retrieved by calling ObjectStore.getDomain() method.
Instructor Notes:
None
Rev 1.0
Communication with the Content Engine Server
23
Communication with the Content Engine Server
Retrieve the Domain and the Object Stores
Factory.Domain.fetchInstance(…)
public static Domain fetchInstance(Connection
conn,String name,PropertyFilter filter)
Parameters
y conn – Specify the Connection object
y name – Specify the symbolic name of the class instance to retrieve
y filter – Specify a PropertyFilter object
Returns
y A Domain object
Notes
y
This method always makes a round trip to the server.
24
ADDITIONAL INFORMATION
If the PropertyFilter value is null, this method returns values for all non-object properties and returns placeholders
for all object-valued properties
Instructor Notes:
None
Rev 1.0
Communication with the Content Engine Server
24
Communication with the Content Engine Server
Retrieve the Domain and the Object Stores
domain.get_ObjectStores()
public ObjectStoreSet get_ObjectStores()
Parameters
y None
Returns
y The collection of ObjectStore objects associated with a given
FileNet P8 domain
25
Instructor Notes:
None
Rev 1.0
Communication with the Content Engine Server
25
Communication with the Content Engine Server
Retrieve the Domain and the Object Stores
Sample Code to Retrieve the Domain
String domainName = "P8Domain";
Domain domain = Factory.Domain.fetchInstance(
connection, domainName, null);
System.out.println(domain.get_Name());
26
Instructor Notes:
None
Rev 1.0
Communication with the Content Engine Server
26
Communication with the Content Engine Server
Retrieve the Domain and the Object Stores
Sample Code to Retrieve the Object Stores
ObjectStoreSet osSet =
domain.get_ObjectStores();
ObjectStore store;
Iterator osIter = osSet.iterator();
while (osIter.hasNext()) {
store = (ObjectStore)osIter.next();
System.out.println(store.get_Name());
}
27
Instructor Notes:
None
Rev 1.0
Communication with the Content Engine Server
27
Communication with the Content Engine Server
Retrieve the Domain and the Object Stores
Activities
In your workbook, see
y Lesson: Retrieve the Domain and the Object
Stores
Complete these activities
y Retrieve the Domain
y Retrieve the Object stores
28
Instructor Notes:
None
Rev 1.0
Communication with the Content Engine Server
28
3
3
Folders
Java API Programmer
Folders
IBM FileNet Content Manager
Instructor Notes:
None
Rev 1.0
Folders
1
Folders
Rev 1.0
Folders
2
Folders
Folders
This module consists of these lessons:
y Create and Delete Folder Objects
y Retrieve Objects from a Folder
3
Instructor Notes:
None
Rev 1.0
Folders
3
Folders
Rev 1.0
Folders
4
Folders
Module: Folders
Lesson:
Create and Delete Folder Objects
5
Instructor Notes:
None
Rev 1.0
Folders
5
Folders
Create and Delete Folder Objects
Lesson Objectives
In this lesson, you will
y Write code to create a folder
y Write code to delete a folder
6
Instructor Notes:
None
Rev 1.0
Folders
6
Folders
Create and Delete Folder Objects
Scenario
y The accounting department of your company wants to
create a folder for each customer to store their ordering
information. As their programmer, you will add a folder
feature that allows users to create and delete folders.
7
Instructor Notes:
None
Rev 1.0
Folders
7
Folders
Create and Delete Folder Objects
Java API Methods Presented in This Lesson
folder. createSubFolder(…)
Factory.Folder.createInstance(…)
Factory.ObjectStore.fetchInstance(…)
objectStore.get_RootFolder()
folder.set_Parent(…)
folder.set_FolderName(…)
folder.save(…)
folder.get_Name()
Factory.Folder.fetchInstance(…)
folder.delete()
8
Instructor Notes:
None
Rev 1.0
Folders
8
Folders
Create and Delete Folder Objects
Folder Definition
Folder object
y Is a container that can hold other containable objects such as
– Child folders
– Documents, custom objects, and their subclasses
y Cannot have content data of its own
Child folders
y Are directly contained
y Have one-to-many relationship
y Can be referentially contained
– Cannot participate in hierarchy index searches
Documents and custom objects
y Are referentially contained using the
– ReferentialContainmentRelationship or
– DynamicReferentialContainmentRelationship classes
y Have many-to-many relationship
9
HELP PATH
FileNet P8 Documentation > Developer Help > Content Engine development > Java and .NET Developer’s
Guide > Getting Started > Concepts
Instructor Notes:
None
Rev 1.0
Folders
9
Folders
Steps to Create a Folder Object
Persist in the
Object Store
Object Store
5. Save
2. Get Root Folder
1. Create an Instance
of a Folder
S
E
T
S
E
T
3. Set Parent
Folder
4.Set Folder
Name
10
ADDITIONAL INFORMATION
•
Create a subfolder under the root or parent folder
•
Get the root or parent folder from the object store
•
Set parent folder
•
Set folder name
•
Save the folder
Instructor Notes:
None
Rev 1.0
Folders
10
Folders
Create and Delete Folder Objects
Steps to Create a Folder Object
1. Create a subfolder under the root or parent folder
folder.createSubFolder(…) Or
Factory.Folder.createInstance(…)
2. Get the root or parent folder from the object store
Factory.ObjectStore.fetchInstance(…)
objectStore.get_RootFolder() Or
Factory.Folder.fetchInstance(…)
3. Set parent folder
folder.set_Parent(…)
4. Set folder name
folder.set_FolderName(…)
5. Save the folder
folder.save(…)
11
Instructor Notes:
None
Rev 1.0
Folders
11
Folders
Create and Delete Folder Objects
folder. createSubFolder(…)
public Folder createSubFolder(String name)
Parameters
y name - Specify the name of the subfolder you want to create
– Cannot be an empty string
– The following characters are not allowed: * \ / : * ? " % & > |
Returns
y A Folder object that represents the new subfolder
Notes
y This method creates a directly contained subfolder for this folder.
12
ADDITIONAL INFORMATION
Three methods are used to create a subfolder:
Factory.Folder.createInstance(…)
ObjectStore.createObject(…)
Folder.createSubFolder(…)
There is no performance difference among these methods. However, the createSubFolder() method is
preferred for type-safety reasons. It ensures that a couple of required properties are set on the newly created
subfolder. Factory.Folder.createInstance() method is also discussed on the next slide and used in the code.
Instructor Notes:
None
Rev 1.0
Folders
12
Folders
Create and Delete Folder Objects
Factory.Folder.createInstance(…)
public static Folder createInstance(ObjectStore
os,String classId)
Parameters
y os - Specify the name of the objectstore
y classId – Specify the identifier of the folder subclass you want to
create. It can be either of the following:
– Class name constant
– Symbolic name of the class
Returns
y An object reference to a new instance of this Folder subclass
Notes
y
This method creates a directly contained subfolder for this folder.
13
Instructor Notes:
None
Rev 1.0
Folders
13
Folders
Create and Delete Folder Objects
Factory.ObjectStore.fetchInstance(…)
public static ObjectStore fetchInstance(Domain domain,
String name, PropertyFilter filter)
Parameters
y domain - Specify the Domain object to which this class instance is
scoped
y name - Specify the symbolic name of the class instance to retrieve
y filter - Specify a PropertyFilter object that represents information for
controlling which property values to return
Returns
y The ObjectStore object requested
Notes
y If the value for the property filter is null, this method returns the
following:
– Values for all non-object properties
– Placeholders for all object-valued properties
14
Instructor Notes:
None
Rev 1.0
Folders
14
Folders
Create and Delete Folder Objects
objectStore.get_RootFolder()
public Folder get_RootFolder()
Parameters
y None
Returns
y The value of the RootFolder property
Notes
y Root folder is the automatically created Folder object representing
the root of the container hierarchy associated with this Object
Store.
15
Instructor Notes:
None
Rev 1.0
Folders
15
Folders
Create and Delete Folder Objects
folder.set_Parent(…)
public void set_Parent(Folder value)
Parameters
y value - Specify the parent folder for this folder you created
Returns
y Nothing
Notes
y This method sets the value of the Parent property.
16
Instructor Notes:
None
Rev 1.0
Folders
16
Folders
Create and Delete Folder Objects
folder.set_FolderName(…)
public void set_FolderName(String value)
Parameters
y value - Specify the name of the subfolder you want to create
– Cannot be an empty string
– The following characters are not allowed: * \ / : * ? " % & >
Returns
y Nothing
Notes
y This method sets the value of the FolderName property.
17
Instructor Notes:
None
Rev 1.0
Folders
17
Folders
Create and Delete Folder Objects
folder.save(…)
public void save(RefreshMode refreshMode)
Parameters
y refreshMode - Specify whether or not to refresh all of the object
properties
Returns
y Nothing
Notes
y This method saves changes made to this folder object.
y Optionally refreshes all of the object properties.
18
Instructor Notes:
None
Rev 1.0
Folders
18
Folders
Create and Delete Folder Objects
folder.get_Name()
public String get_FolderName()
Parameters
y None
Returns
y A String representing the name of this folder
19
Instructor Notes:
None
Rev 1.0
Folders
19
Folders
Create and Delete Folder Objects
Sample Code to Create a Folder
Create a folder under the root folder
Folder myFolder =
Factory.Folder.createInstance(objectStore,null);
Folder rootFolder = objectStore.get_RootFolder();
myFolder.set_Parent(rootFolder);
myFolder.set_FolderName(“NewFolder");
myFolder.save(RefreshMode.REFRESH);
Create a subfolder to an existing folder
Folder subFolder =
myFolder.createSubFolder(“newSubFolder");
subFolder.save(RefreshMode.REFRESH);
20
ADDITIONAL INFORMATION
The Folder.createSubFolder(…) method is preferred for type-safety reasons. It ensures that a couple of
required properties are set on the newly created subfolder.
This sample code also shows the use of other method to create a folder: Factory.Folder.createInstance(…)
There is no performance difference between these methods.
Instructor Notes:
None
Rev 1.0
Folders
20
Folders
Create and Delete Folder Objects
Steps to Delete a Folder Object
1. Get the folder to be deleted
Factory.Folder.fetchInstance(…)
2. Delete the folder
folder.delete()
3. Save the folder
folder.save(…)
21
Instructor Notes:
None
Rev 1.0
Folders
21
Folders
Create and Delete Folder Objects
Factory.Folder.fetchInstance(…)
public static Folder fetchInstance(ObjectStore
os,String path, PropertyFilter filter)
Parameters
y os – Specify the Object Store object where this folder is located
y path - Specify the full-qualified pathname for the Folder object in a
String
y filter – Specify a PropertyFilter object that represents information for
controlling which property values to return
Returns
y The specified Folder object
Notes
y If the value for the property filter is null, this method returns the
following:
– Values for all non-object properties
– Placeholders for all object-valued properties
22
Instructor Notes:
None
Rev 1.0
Folders
22
Folders
Create and Delete Folder Objects
folder.delete()
public void delete()
Parameters
y None
Returns
y Nothing
Notes
y Cannot delete the root folder.
y Must commit the change to the repository.
y In order to delete a folder with directly contained subfolders,
the subfolders must first be deleted.
y Other objects are automatically unfiled from the folder.
y The user must have delete permissions on this Folder object.
23
Instructor Notes:
None
Rev 1.0
Folders
23
Folders
Create and Delete Folder Objects
Sample Code to Delete a Folder
String folderToDelete = "/Test";
Folder delFolder= Factory.Folder.fetchInstance
(objectStore,folderToDelete, null);
delFolder.delete();
delFolder.save(RefreshMode.REFRESH);
24
ADDITIONAL INFORMATION
The Folder.save(…) method needs to be called to persist the changes made to this folder (deletion in this
case).
Instructor Notes:
None
Rev 1.0
Folders
24
Folders
Create and Delete Folder Objects
Activities
In your workbook, see
y Lesson: Create and Delete Folder Objects
Complete these activities
y Create Subfolders
y Delete a Folder
25
Instructor Notes:
None
Rev 1.0
Folders
25
Folders
Rev 1.0
Folders
26
Folders
Module: Folders
Lesson:
Retrieve Objects from a Folder
27
Instructor Notes:
None
Rev 1.0
Folders
27
Folders
Retrieve Objects from a Folder
Lesson Objectives
In this lesson, you will
y Write code to retrieve subfolders from a folder
y Write code to retrieve Document objects from a folder
y Write code to retrieve all the objects from a folder
28
Instructor Notes:
None
Rev 1.0
Folders
28
Folders
Retrieve Objects from a Folder
Scenario
y The billing section in your company wants to retrieve
customer information from the Customer folder. As their
programmer, you will write code to retrieve the contents of
a folder when an employee accesses the folder.
29
Instructor Notes:
None
Rev 1.0
Folders
29
Folders
Retrieve Objects from a Folder
Java API Methods Presented in This Lesson
folder.get_SubFolders()
folder.get_ContainedDocuments()
folder.get_Containees()
referentialContainmentRelationship.get_Name()
referentialContainmentRelationship.get_Head()
independentObject.getClassName()
independentObject.fetchProperties(…)
independentObject.getProperties()
30
Instructor Notes:
None
Rev 1.0
Folders
30
Folders
Retrieve Objects from a Folder
Referential Containment
Most objects “contained” in folders “by reference”
y Hence, same object can be filed in any number of folders
Static relationship between an object and each of its folders
represented by a:
y ReferentialContainmentRelationship object
Dynamic relationship between current document version and
each of its folders represented by a:
y DynamicReferentialContainmentRelationship object
In relationship, Tail points to folder, Head points to contained
object
en
fer
Re
tia
l
Dy
nam
ic
31
ADDITIONAL INFORMATION
The Containable subclasses are CodeModule, CustomObject, Document, Folder, PublishStyleTemplate,
PublishTemplate, WorkflowDefinition, XMLPropertyMappingScript
The ReferentialContainmentRelationship is a static relationship between a folder and a custom object, a
workflow definition, or a specific document version.
The DynamicReferentialContainmentRelationship is a dynamic relationship between a folder and the latest
version of a document.
Instructor Notes:
None
Rev 1.0
Folders
31
Folders
Retrieve Objects from a Folder
Steps to Retrieve Objects from a Folder
Retrieve the child folders from a parent folder
folder.get_SubFolders()
Retrieve the documents from a folder
folder.get_ContainedDocuments()
Retrieve all the objects contained in a folder
folder.get_Containees()
Get information about the retrieved objects
referentialContainmentRelationship.get_Name()
referentialContainmentRelationship.get_Head()
independentObject.getClassName()
independentObject.fetchProperties(…)
independentObject.getProperties()
32
Instructor Notes:
None
Rev 1.0
Folders
32
Folders
Retrieve Objects from a Folder
folder.get_SubFolders()
public FolderSet get_SubFolders()
Parameters
y None
Returns
y A FolderSet collection which has the directly contained child folders
of this Folder
Notes
y Any referentially contained child folders are not included in the
collection.
33
Instructor Notes:
None
Rev 1.0
Folders
33
Folders
Retrieve Objects from a Folder
folder.get_ContainedDocuments()
public DocumentSet get_ContainedDocuments()
Parameters
y None
Returns
y A DocumentSet collection, which has the Documents contained
within this folder
34
Instructor Notes:
None
Rev 1.0
Folders
34
Folders
Retrieve Objects from a Folder
folder.get_Containees()
public ReferentialContainmentRelationshipSet
get_Containees()
Parameters
y None
Returns
y A ReferentialContainmentRelationshipSet collection, which has the
ReferentialContainmentRelationship objects contained within this
folder
35
Instructor Notes:
None
Rev 1.0
Folders
35
Folders
Retrieve Objects from a Folder
referentialContainmentRelationship.get_Name()
public String get_Name()
Parameters
y None
Returns
y A String representing the name of this object
36
Instructor Notes:
None
Rev 1.0
Folders
36
Folders
Retrieve Objects from a Folder
referentialContainmentRelationship.get_Head()
public IndependentObject get_Head()
Parameters
y None
Returns
y The value of the Head property
– Head is an IndependentlyPersistableObject instance that
participates as the logical head (containee) in a relationship
between two objects
Notes
y For a ReferentialContainmentRelationship object, the head can be
any of the Containable subclasses:
– CustomObject, Document, or Folder object
y If the head is a Document, it represents a specific document
version.
37
ADDITIONAL INFORMATION
For a DynamicReferentialContainmentRelationship object, the head is always a versionable object
representing the current document version.
For a Link object, this property can specify any object that is a subclass of the IndependentObject base
class.
Instructor Notes:
None
Rev 1.0
Folders
37
Folders
Retrieve Objects from a Folder
independentObject.getClassName()
public String getClassName()
Parameters
y None
Returns
y The name of the class from which this object is instantiated
38
Instructor Notes:
None
Rev 1.0
Folders
38
Folders
Retrieve Objects from a Folder
independentObject.fetchProperties(…)
public void fetchProperties(PropertyFilter
filter)
Parameters
y filter – Specify a PropertyFilter object that represents information
for controlling which property values to return
– This parameter cannot be null
Returns
y None
Notes
y This method retrieves this object from the server and merges
existing information in the property cache with the retrieved.
y If this object has changed on the server since it was last retrieved,
you must call a refresh method first.
39
Instructor Notes:
None
Rev 1.0
Folders
39
Folders
Retrieve Objects from a Folder
independentObject.getProperties()
public Properties getProperties()
Parameters
y None
Returns
y A Properties collection representing the cached properties of this
object
Notes
y An object reference will not have values in its property collection.
y If the properties of an object reference are required, you must
refresh the object before calling this method.
40
Instructor Notes:
None
Rev 1.0
Folders
40
Folders
Retrieve Objects from a Folder
Sample Code to Retrieve Folder Objects
Get the parent folder
Folder folder= Factory.Folder.fetchInstance
(objectStore,parentFolder, null);
Get the subfolders
FolderSet subFolders = folder.get_SubFolders();
Iterator it = subFolders.iterator();
while(it.hasNext()){
Folder subFolder = (Folder)it.next();
String name = subFolder.get_FolderName();
}
41
Instructor Notes:
None
Rev 1.0
Folders
41
Folders
Retrieve Objects from a Folder
Sample Code to Retrieve Document Objects
DocumentSet documents =
folder.get_ContainedDocuments();
Iterator it = documents.iterator();
while(it.hasNext()){
Document retrieveDoc = (Document)it.next();
String name = retrieveDoc.get_Name();
}
42
Instructor Notes:
None
Rev 1.0
Folders
42
Folders
Retrieve Objects from a Folder
Sample Code to Retrieve Objects from a Folder
ReferentialContainmentRelationshipSet
refConRelSet = folder.get_Containees();
Iterator it = refConRelSet.iterator();
while(it.hasNext()){
ReferentialContainmentRelationship retrieveObj
=(ReferentialContainmentRelationship)it.next();
IndependentObject containee =
retrieveObj.get_Head();
String className = containee.getClassName();
String displayName = retrieveObj.get_Name();
containee.fetchProperties(propertyFilter);
String name = containee.getProperties().
getStringValue(PropertyNames.NAME);
}
43
Instructor Notes:
None
Rev 1.0
Folders
43
Folders
Retrieve Objects from a Folder
Activities
In your workbook, see
y Lesson: Retrieve Objects from a Folder
Complete these activities
y Retrieve the Objects from a Folder
1. Get Subfolders
2. Get Documents
3. Get All of the Objects
44
Instructor Notes:
None
Rev 1.0
Folders
44
4
4
Custom Objects
Java API Programmer
Custom Objects
IBM FileNet Content Manager
Instructor Notes:
None
Rev 1.0
Custom Objects
Custom Objects
Rev 1.0
Custom Objects
Custom Objects
Custom Objects
This unit consists of these lessons:
y Create Custom Objects
y Retrieve Custom Object Properties
3
Instructor Notes:
None
Rev 1.0
Custom Objects
Custom Objects
Rev 1.0
Custom Objects
Custom Objects
Module: Custom Objects
Lesson:
Create Custom Objects
5
Instructor Notes:
None
Rev 1.0
Custom Objects
Custom Objects
Create Custom Objects
Scenario
y Morgan registers online to be a travel agent for the
company. The application uses a custom object class to
store the travel agents profile. You, as a programmer, will
write code to create an instance of the class each time a
travel agent enters this information.
6
Instructor Notes:
None
Rev 1.0
Custom Objects
Custom Objects
Create Custom Objects
Lesson Objectives
In this lesson, you will
y Write code to create a custom object
y Write code to set the properties to the custom object
y Write code to file the custom object to a folder
7
Instructor Notes:
None
Rev 1.0
Custom Objects
Custom Objects
Create Custom Objects
Java API Methods Presented in This Lesson
Factory.CustomObject.createInstance(…)
customObject.getProperties()
properties.putValue(…)
customObject.save(…)
folder.file(…)
referentialContainmentRelationship.save(…)
8
Instructor Notes:
None
Rev 1.0
Custom Objects
Custom Objects
Create Custom Objects
What Are Custom Objects?
A custom object is an object without content
y Created to model its business process usage
y Named for its business process usage
y Used to store properties
Like a Document object, a custom object
y
y
y
y
y
Is independently securable
Can be persisted in an object store
Can be filed into a folder
Can have annotations associated with it
Can subscribe to server-side events
9
HELP PATH
FileNet P8 Documentation > Developer Help > Content Engine development > Java and .NET Developer’s Guide >
Getting Started > Concepts
Instructor Notes:
None
Rev 1.0
Custom Objects
Custom Objects
Create Custom Objects
Custom Objects Are Unlike Documents
Unlike a Document object, a custom object does not
y
y
y
y
y
Carry content
Have a default Name property (in the CustomObject class)
Have multiple versions
Support lifecycle states
Have all the system properties that a document has
10
HELP PATH
FileNet P8 Documentation > Developer Help > Content Engine development > Java and .NET Developer’s Guide >
Getting Started > Concepts
Instructor Notes:
None
Rev 1.0
Custom Objects
Custom Objects
Create Custom Objects
Why Use Custom Objects?
Use custom objects when
y The object simply stores properties
y Saved versions of the object are not needed
y Custom properties are needed for the objects in a class
Applications often associate custom properties with
the objects they process
y Create a CustomObject subclass for each set of
application-specific custom properties
y To link the subclass with another object, create a custom
property that points to the associated object by using the
associated object GUID as the value
11
HELP PATH
FileNet P8 Documentation > Developer Help > Content Engine development > Java and .NET Developer’s Guide >
Getting Started > Concepts
Instructor Notes:
None
Rev 1.0
Custom Objects
Custom Objects
Create Custom Objects
Steps to Create a Custom Object
1. Create an
Instance of
Custom Object
2. Get Properties
Properties Collection
3. Set Values
4.
S
A
V
E
Persist in the
Object Store
5. File
p
u
t
p
u
t
Property-1
Set Value
Property-2
Set Value
Folder
12
ADDITIONAL INFORMATION
1.
Create an instance of custom object
2.
Get the Properties of the custom object
3.
Set Properties to the custom object
4.
Save the custom object
5.
File the custom object in a folder (optional)
Instructor Notes:
None
Rev 1.0
Custom Objects
Custom Objects
Create Custom Objects
Steps to Create a Custom Object
1. Create an instance of custom object
Factory.CustomObject.createInstance(…)
2. Get the Properties of the custom object
customObject.getProperties()
3. Set Properties to the custom object
properties.putValue(…)
4. Save the custom object
customObject.save(…)
5. File the custom object in a folder (optional)
folder.file(…)
referentialContainmentRelationship.save(…)
13
ADDITIONAL INFORMATION:
The steps involved to create a custom object are very similar to creating a Document object except that no content
is added.
Instructor Notes:
None
Rev 1.0
Custom Objects
Custom Objects
Create Custom Objects
Factory.CustomObject.createInstance(…)
public static CustomObject
createInstance(ObjectStore os,String classId)
Parameters
y os - Specify the object store where this custom object is to be
persisted
y classId - Specify the symbolic name of the class instance to create
Returns
y An object reference to a new instance of this CustomObject class
Notes
y This method creates a new instance of the specified CustomObject
class.
y You must call save method to persist this object in the object store.
14
Instructor Notes:
None
Rev 1.0
Custom Objects
Custom Objects
Create Custom Objects
customObject.getProperties ()
public Properties getProperties()
Parameters
y None
Returns
y A Properties collection representing the cached properties of this
object
Notes
y An object reference does not have values in its property collection.
y Therefore, you must refresh the object before calling this method.
y This method is inherited from EngineObject interface
15
Instructor Notes:
None
Rev 1.0
Custom Objects
Custom Objects
Create Custom Objects
properties.putvalue(…)
public void putValue(String propertyName,String
value)
Parameters
y propertyName - Specify the property name
y value - Specify the value for the property
Returns
y None
Notes
y This method creates or updates a PropertyString instance in
this Properties collection.
y If a property with the same name already exists in the
collection, its value will be replaced with the value provided.
16
Instructor Notes:
None
Rev 1.0
Custom Objects
Custom Objects
Create Custom Objects
customObject.save(…)
public void save(RefreshMode refreshMode)
Parameters
y refreshMode - Specify whether or not to refresh all of the object
properties
y RefreshMode.NO_REFRESH or RefreshMode.REFRESH
Returns
y None
Notes
y This method saves changes made to this object.
y You can optionally refresh all of the object properties.
17
Instructor Notes:
None
Rev 1.0
Custom Objects
Custom Objects
Create Custom Objects
folder.file(…)
public ReferentialContainmentRelationship
file(IndependentlyPersistableObject
containee,AutoUniqueName autoUniqueName,String
containmentName,DefineSecurityParentage
defineSecurityParentage)
Parameters
y containee - Specify the custom object to be filed
y autoUniqueName - Specify whether or not to resolve the containment
y
y
names for uniqueness
containmentName - Specify a name for the containment
defineSecurityParentage – DEFINE_SECURITY_PARENTAGE
Returns
y A ReferentialContainmentRelationship object, where this folder is the
tail and the custom object filed is the head
Notes
y This method files the custom object to this folder.
18
ADDITIONAL INFORMATION:
Parameters:
AutoUniqueName :
Specifies whether or not the naming collision (non-uniqueness) of the containment name is
to be detected and automatically resolved
Containment names are set on ReferentialContainmentRelationship or
DynamicReferentialContainmentRelationship objects.
If a naming collision is detected, the containment name of the object is automatically appended with an
integer in parentheses (Example: "myDocument(2)").
Containment names are modified only when a naming collision is detected.
Values:
AUTO_UNIQUE
NOT_AUTO_UNIQUE
DefineSecurityParentage: Specifies that whether or not the object defines the security parentage for its child
objects.
- DEFINE_SECURITY_PARENTAGE
- DO_NOT_DEFINE_SECURITY_PARENTAGE
Instructor Notes:
None
Rev 1.0
Custom Objects
Custom Objects
Create Custom Objects
referentialContainmentRelationship.save(…)
public void save(RefreshMode refreshMode)
Parameters
y refreshMode - Specifies whether or not to refresh all of the properties
of the object.
Returns
y Nothing
Notes
y There is another version of this method:
– public void save(RefreshMode refreshMode, PropertyFilter filter)
– A PropertyFilter object that represents information for controlling
which property values to refresh
– Specifying null for property filter is the same as calling
save(RefreshMode refreshMode)
19
ADDITIONAL INFORMATION
RefreshMode.NO_REFRESH
RefreshMode REFRESH
Specifies that upon saving or committing the object, its property cache is not
refreshed with updated data from the Content Engine server.
Specifies that upon saving or committing the object, its property cache is
refreshed with updated data from the Content Engine server.
Instructor Notes:
None
Rev 1.0
Custom Objects
Custom Objects
Create Custom Objects
Sample Code to Create a Custom Object
CustomObject myObject = Factory.CustomObject.
createInstance(os,"TravelAgent");
Properties props = myObject.getProperties();
props.putValue("AgentName", “John Smith");
props.putValue("Age", 29);
myObject.save(RefreshMode.REFRESH);
ReferentialContainmentRelationship rel =
folder.file(myObject,AutoUniqueName.AUTO_UNIQUE,
customObjectName,
DefineSecurityParentage.DO_NOT_DEFINE_SECURITY_PA
RENTAGE);
rel.save(RefreshMode.NO_REFRESH);
20
Instructor Notes:
None
Rev 1.0
Custom Objects
Custom Objects
Create Custom Objects
Activities
In your workbook, see
y Lesson: Create Custom Objects
Complete these activities:
1.
2.
3.
4.
5.
Create a Custom Object
Set the Properties
File the Custom Object to a Folder
Call the Methods
Run the Code and Verify the Results
21
Instructor Notes:
None
Rev 1.0
Custom Objects
Custom Objects
Rev 1.0
Custom Objects
Custom Objects
Module: Custom Objects
Lesson:
Retrieve Custom Object Properties
23
Instructor Notes:
None
Rev 1.0
Custom Objects
Custom Objects
Retrieve Custom Object Properties
Scenario 1
y The application has a custom object class that stores the
emergency contact information for each customer. As the
programmer, you will write code to retrieve custom object
properties in order to modify the emergency contact object
each time a customer updates this information.
Scenario 2
y The application has a custom object class that stores travel
agent profiles. As the programmer, you will write code to
retrieve properties in order to modify the profile object each
time a travel agent updates this information.
24
Instructor Notes:
None
Rev 1.0
Custom Objects
Custom Objects
Retrieve Custom Object Properties
Lesson Objectives
In this lesson, you will
y Write code to retrieve custom object properties
25
Instructor Notes:
None
Rev 1.0
Custom Objects
Custom Objects
Retrieve Custom Object Properties
Java API Methods Presented in This Lesson
Factory.CustomObject.fetchObject(…)
customObject.getProperties(…)
properties.getInteger32Value(…)
properties.getStringValue(...)
properties.getDateTimeValue(...)
26
Instructor Notes:
None
Rev 1.0
Custom Objects
Custom Objects
Retrieve Custom Object Properties
Steps to Retrieve Custom Object Properties
1. Get the custom object
Factory.CustomObject.fetchInstance(…)
2. Get the custom object Properties collection
customObject.getProperties(…)
3. Get the value of each property
properties.getStringValue(…)
properties.getInteger32Value(…)
properties.getDateTimeValue(…)
27
Instructor Notes:
None
Rev 1.0
Custom Objects
Custom Objects
Retrieve Custom Object Properties
Factory.CustomObject.fetchInstance(…)
public static CustomObject fetchInstance
(ObjectStore os,String path,
PropertyFilter filter)
Parameters
y os - Specify the object store in which this custom object is located
y path - Specify the full folder path for the custom object
y filter - Specify a PropertyFilter object that represents information for
controlling which property values to return
Returns
y The requested CustomObject object
Notes
y If the value for the property filter is null, this method returns
– Values for all non-object properties
– Placeholders for all object-valued properties
28
Instructor Notes:
In the module activity, the students will use null value for the property filter for simplicity. In other modules later, property
filter is used.
Rev 1.0
Custom Objects
Custom Objects
Retrieve Custom Object Properties
CustomObject.getProperties(…)
public Properties getProperties()
Parameters
y None
Returns
y A Properties collection representing the cached properties of this
object
Notes
y CustomObject inherits this method from the EngineObject
interface.
y If the properties of an object reference are required, refresh the
object before calling this method.
29
Instructor Notes:
None
Rev 1.0
Custom Objects
Custom Objects
Retrieve Custom Object Properties
properties.getStringValue(…)
public String getStringValue(String
propertyName)
Parameters
y propertyName – Specify the property name for which you want to
retrieve the value
Returns
y A String specifying the value of this property
Notes
y This method locates a PropertyString property by name in this
Properties collection and returns the value it holds.
30
Instructor Notes:
None
Rev 1.0
Custom Objects
Custom Objects
Retrieve Custom Object Properties
properties.getInteger32Value(…)
public Integer getInteger32Value(String
propertyName)
Parameters
y propertyName – Specify the property name for which you
want to retrieve the value
Returns
y An Integer specifying the value of this property
Notes
y This method locates a PropertyInteger32 property by name
in this Properties collection and returns the value it holds.
31
Instructor Notes:
None
Rev 1.0
Custom Objects
Custom Objects
Retrieve Custom Object Properties
properties.getDateTimeValue(…)
public Date getDateTimeValue
(String propertyName)
Parameters
y propertyName – Specify the property name for which you
want to retrieve the value
Returns
y A Date specifying the value of this property
Notes
y This method locates a PropertyDateTime property by name
in this Properties collection and returns the value it holds.
32
Instructor Notes:
None
Rev 1.0
Custom Objects
Custom Objects
Retrieve Custom Object Properties
Sample Code to Retrieve Custom Object Properties
CustomObject myObject =
Factory.CustomObject.fetchInstance(store,
folderPath, null);
String CustomObjName = myObject.get_Name();
com.filenet.api.property.Properties props =
myObject.getProperties();
String name =
props.getStringValue("agent_name");
Integer age = props.getInteger32Value("age");
Date dateCreated= props.getDateTimeValue
(PropertyNames.DATE_CREATED);
System.out.println("Travel Agent Name: "+name );
System.out.println("Travel Agent age: " + age);
System.out.println("Date created: " +
dateCreated);
33
Instructor Notes:
None
Rev 1.0
Custom Objects
Custom Objects
Retrieve Custom Object Properties
Activities
In your workbook, see
y Lesson: Retrieve Custom Object Properties
Complete this activity:
y Retrieve Custom Object Properties
34
Instructor Notes:
None
Rev 1.0
Custom Objects
5
5
Documents
Java API Programmer
Documents
IBM FileNet Content Manager
Instructor Notes:
None
Rev 1.0
Documents
1
Documents
Rev 1.0
Documents
2
Documents
Documents
This module consists of these lessons:
y Create Document Objects
y Retrieve a Document and Its Content
3
Instructor Notes:
None
Rev 1.0
Documents
3
Documents
Rev 1.0
Documents
4
Documents
Module: Documents
Lesson:
Create Document Objects
5
Instructor Notes:
None
Rev 1.0
Documents
5
Documents
Create Document Objects
Scenario
y Your application requires a feature that creates a
Document object on the Content Engine whenever some
one adds content. You, as the programmer, will write code
to accomplish this.
6
Instructor Notes:
None
Rev 1.0
Documents
6
Documents
Create Document Objects
Lesson Objectives
In this lesson, you will
y
y
y
y
Write code to create a Document object
Write code to set content to the document and check in
Write code to set the properties to the document and save
Write code to file the document to a folder
7
Instructor Notes:
None
Rev 1.0
Documents
7
Documents
Create Document Objects
Java API Methods Presented in This Lesson
Factory.Document.createInstance(…)
Factory.ContentElement.createList()
Factory.ContentTransfer.createInstance()
contentTransfer.setCaptureSource(…)
contentTransfer.set_ContentType(…)
Factory.ContentReference.createInstance()
contentReference.set_ContentLocation(…)
contentReference.set_ContentType(…)
contentElementList.add(…)
Note: Additional methods are listed on the following slide.
8
Instructor Notes:
None
Rev 1.0
Documents
8
Documents
Create Document Objects
Java API Methods Presented in This Lesson
(Continued)
(Continued)
document.set_ContentElements(…)
document.checkin()
document.getProperties()
properties.putValue()
document.set_MimeType(…)
document.save( …)
folder.file(…)
referentialContainmentRelationship.save(…)
9
Instructor Notes:
None
Rev 1.0
Documents
9
Documents
Create Document Objects
Document Objects
A Document object
y Is an instance of the document class or a subclass
A Document object can have the following:
y One or more content elements
y Associated annotations
y Metadata or properties that are used for identification
Document content elements are stored
y Locally - Object store
y Externally
A Document object can be versioned
y Each version of each Document content element is
–Assigned a version number
–Saved as a separate, accessible, unique entity
10
Help Path:
FileNet P8 documentation > FileNet P8 Administration > Content Engine Administration > Content
Engine Overview > Features > Documents
FileNet P8 documentation > Developer Help > Content Engine Development > Java and .NET
developer’s Guide > Getting Started > Concepts
ADDITIONAL INFORMATION:
The main difference between the Document objects and CustomObject objects:
CustomObject objects do not have content or versions but Document objects do.
Instructor Notes:
None
Rev 1.0
Documents
10
Documents
Create Document Objects
Available Actions on Document Objects
A Document object can be
y
y
y
y
y
Filed in a folder
Secured
Repurposed for FileNet site publishing
Set up to be searched for and retrieved
Associated with other documents to form compound
documents
In addition, a Document object can be
y Subclassed to add additional custom properties to the
11
y
y
y
y
Document
Associated with lifecycle policies
Subscribed to a server-side event
Used as an attachment in a workflow step
Designated as the target for a workflow subscription
Help Path:
FileNet P8 documentation > FileNet P8 Administration > Content Engine Administration > Content
Engine Overview > Features > Documents
FileNet P8 documentation > Developer Help > Content Engine Development > Java and .NET
developer’s Guide > Getting Started > Concepts
ADDITIONAL INFORMATION:
Security, search, publish, and subscription concepts are presented in separate modules in this
course.
Workflow concepts will be covered in a separate course.
Instructor Notes:
None
Rev 1.0
Documents
11
Documents
Create Document Objects
Steps to Create a Document
Content Element List
2. Set Content
1. Create an
Instance of
Document
3.
C
H
E
C
K
I
n
a
d
d
Content
Transfer -1
4. Get Properties
6.
S
A
V
E
Persist in the
Object Store
5. Set Values
a
d
d
Content
Reference
Properties Collection
p
p
u
u
t
t
Property-1
Set Value
7. File
a
d
d
Content
Transfer -2
Property-2
Set Value
Folder
12
ADDITIONAL INFORMATION:
1. Create a Document object
2. Set Contents to the Document object
- Create an empty ContentElementList collection
- Create a ContentTransfer object
- Specify the source of the content
- Add contentTransfer element to the contentElementList collection
- Set content to the Document object
3. Check in the document
4. Get Properties from the document
5. Set Properties to the document
6. Save the document
7. File the document in a folder (optional)
Instructor Notes:
None
Rev 1.0
Documents
12
Documents
Create Document Objects
Steps to Create a Document Object
1.
Create a Document object
Factory.Document.createInstance(…)
2.
Set Contents to the Document object
See the next slide
3.
Check in the document
document.checkin()
4.
Get Properties from the document
document.getProperties()
5.
Set Properties to the document
properties.putValue()
document.set_MimeType(…)
6.
Save the document
document.save(…)
7.
File the document in a folder (optional)
folder.file(…)
referentialContainmentRelationship.save(…)
13
Instructor Notes:
None
Rev 1.0
Documents
13
Documents
Create Document Objects
Steps to Set Content of the Document object
1. Create an empty ContentElementList collection
Factory.ContentElement.createList()
2. Create a ContentTransfer object
Factory.ContentTransfer.createInstance()
3. Specify the source of the content
contentTransfer.setCaptureSource(…)
4. Add contentTransfer element to the contentElementList
collection
contentElementList.add(…)
5. Set content to the Document object
document.set_ContentElements(…)
14
Instructor Notes:
None
Rev 1.0
Documents
14
Documents
Create Document Objects
Factory.Document.createInstance(…)
public static Document createInstance(ObjectStore
os,String classId)
Parameters
y os - Specify the object store where this Document is to be persisted
y classId - Specify the symbolic name of the class instance to create
Returns
y An object reference to a new instance of this Document class
Notes
y This method creates a new instance of the specified Document class.
y You must call save method to persist this object in the object store.
15
Instructor Notes:
None
Rev 1.0
Documents
15
Documents
Create Document Objects
Factory.ContentElement.createList()
public static ContentElementList createList()
Parameters
y None
Returns
y ContentElementList object
Notes
y This method creates a new instance of this collection class.
y This list is a dependent object.
y It is persisted on the server when its parent object has been saved
with this new list.
16
Instructor Notes:
None
Rev 1.0
Documents
16
Documents
Create Document Objects
Factory.ContentTransfer.createInstance()
public static ContentTransfer createInstance()
Parameters
y None
Returns
y A ContentTransfer object
Notes
y This method creates a new instance of ContentTransfer class.
y This object is a dependent object.
y It is persisted on the server when its parent object has been saved.
17
Instructor Notes:
None
Rev 1.0
Documents
17
Documents
Create Document Objects
contentTransfer.setCaptureSource(…)
public void setCaptureSource(java.io.InputStream
source)
Parameters
y Source - Specify the source of the content data in an InputStream
object
Returns
y Nothing
18
Instructor Notes:
None
Rev 1.0
Documents
18
Documents
Create Document Objects
contentTransfer.set_ContentType(…)
public void set_ContentType(String type)
Parameters
y type – Specify the MIME format of the content data carried by this
content element
Returns
y Nothing
Notes
y The specified Multipurpose Internet Mail Extensions (MIME) format
y
string of the content data indicates to the server what kind of data
this content element represents.
If you do not set the ContentType property, it is automatically set by
the server.
19
ADDITIONAL INFORMATION
• ContentTransfer class inherits set_Contenttype(…) method from ContentElement interface.
Instructor Notes:
None
Rev 1.0
Documents
19
Documents
Create Document Objects
Factory.ContentReference.createInstance()
public static ContentReference createInstance()
Parameters
y None
Returns
y A ContentReference object
Notes
y This method creates a new instance of ContentReference class.
y This object is a dependent object.
y It is persisted on the server when its parent object has been saved.
20
ADDITIONAL INFORMATION
• The ContentReference object represents external content data that exists outside of an object store (and therefore
outside the control of the Content Engine server), but to which an object store maintains a reference.
• The URL of the resource that contains the content data is stored in the ContentLocation property.
• The object is persisted to an object store when its parent object (the independently persistable object that
references it) is persisted.
• The most frequently used form of this method takes no arguments. Since a dependent object is persisted to the
object store of its parent, there is no need to specify an object store.
• A second form of this method, provided for backward compatibility with the FileNet P8 Content Engine COM API,
takes an object store argument. If the specified object store is not that of the parent object, an exception is thrown
when the parent is persisted.
Instructor Notes:
None
Rev 1.0
Documents
20
Documents
Create Document Objects
contentReference.set_ContentLocation (…)
public void set_ContentLocation(String location)
Parameters
y location - Specify, in URL format, the name of the resource that
contains the content data represented by this ContentReference
object
Returns
y Nothing
21
Instructor Notes:
None
Rev 1.0
Documents
21
Documents
Create Document Objects
contentReference.set_ContentType(…)
public void set_ContentType(String type)
Parameters
y type – Specify the MIME format of the content data carried by this
content element
Returns
y Nothing
Notes
y The specified Multipurpose Internet Mail Extensions (MIME) format
y
string of the content data indicates to the server what kind of data
this content element represents.
If you do not set the ContentType property, it is automatically set by
the server.
22
ADDITIONAL INFORMATION
• ContentTransfer class inherits set_Contenttype(…) method from ContentElement interface.
Instructor Notes:
None
Rev 1.0
Documents
22
Documents
Create Document Objects
document.set_ContentElements(…)
public void set_ContentElements(ContentElementList
value)
Parameters
y value - Specify the ContentElementList that has the content elements
Returns
y Nothing
Notes
y This method sets the content to the Document object.
y Each content element in the list represents content data.
y Data can be either
– Local to an object store (represented by ContentTransfer object)
– External (represented by a ContentReference object)
23
Instructor Notes:
None
Rev 1.0
Documents
23
Documents
Create Document Objects
document.checkin(…)
public void checkin(AutoClassify autoClassify,
CheckinType checkinType)
Parameters
y autoClassify - Specify an autoClassify constant whether or not to
y
enable autoclassification of a document during check-in
checkinType - Specify a CheckinType constant whether to check in a
document as a new minor version or as a new major version
Returns
y Nothing
Notes
y This method checks in this document reservation object by saving it
as a new document version.
y You must have the appropriate access rights to check in a document.
24
ADDITIONAL INFORMATION
Parameters
:
AutoClassify constants
AutoClassify.DO_NOT_AUTO_CLASSIFY
AutoClassify.AUTO_CLASSIFY
CheckinType constants
CheckinType.MINOR_VERSION
CheckinType.MAJOR_VERSION
The autoClassify parameter specifies whether the document should have automatic document classification
enabled. This autoClassify and versions are discussed in separate lessons and modules.
Before you can determine if a document has content, you must set the content for the document.
If you do not want the Content Engine to assign a MIME type to the checked-in document, you must explicitly set
the value.
Instructor Notes:
None
Rev 1.0
Documents
24
Documents
Create Document Objects
document.getProperties ()
public Properties getProperties()
Parameters
y None
Returns
y A Properties collection representing the cached properties of this
object
Notes
y An object reference does not have values in its property collection.
y Therefore, you must refresh the object before calling this method.
25
Instructor Notes:
None
Rev 1.0
Documents
25
Documents
Create Document Objects
Properties.putvalue(…)
public void putValue(String propertyName,String
value)
Parameters
y propertyName - Specify the property name
y value - Specify the value for the property
Returns
y None
Notes
y This method creates or updates a PropertyString instance in this
y
Properties collection.
If a property with the same name already exists in the collection, its
value is replaced with the value provided.
26
Instructor Notes:
None
Rev 1.0
Documents
26
Documents
Create Document Objects
document.set_MimeType(…)
public void set_MimeType(String value)
Parameters
y value - Specify the content type
Returns
y None
Notes
y This method sets the content type for the document content element.
27
ADDITIONAL INFORMATION
• Specifies the Multipurpose Internet Mail Extensions (MIME) format string of the content data carried by this
document.
•You can set the MimeType property for a specific document version while it is a reservation (at creation time and
on subsequent check-outs).
• However, every time you check in a document, its MimeType property value will revert to the system-assigned
value unless you have explicitly set it again.
• Each content element that is attached to a document has its own MIME type, which is specified by its
ContentType property.
Instructor Notes:
None
Rev 1.0
Documents
27
Documents
Create Document Objects
document.save(…)
public void save(RefreshMode refreshMode)
Parameters
y refreshMode - Specify whether or not to refresh all of the object
properties
y RefreshMode.NO_REFRESH or RefreshMode.REFRESH
Returns
y None
Notes
y This method saves changes made to this object.
y You can optionally refresh all of the object properties.
28
Instructor Notes:
None
Rev 1.0
Documents
28
Documents
Create Document Objects
folder.file(…)
public ReferentialContainmentRelationship
file(IndependentlyPersistableObject
containee,AutoUniqueName autoUniqueName,String
containmentName,DefineSecurityParentage
defineSecurityParentage)
Parameters
y containee - Specify the Document object to be filed
y autoUniqueName - Specify whether or not to resolve the containment
y
names for uniqueness
containmentName - Specify a name for the containment. By default it
is the file name of the document.
Returns
y A ReferentialContainmentRelationship object, where this folder is the
tail and the document filed is the head
Notes
y This method files the document in this folder.
29
Instructor Notes:
None
Rev 1.0
Documents
29
Documents
Create Document Objects
referentialContainmentRelationship.save(…)
public void save(RefreshMode refreshMode)
Parameters
y refreshMode - Specifies whether or not to refresh all of the properties
of the object.
Returns
y Nothing
Notes
y There is another version of this method:
– public void save(RefreshMode refreshMode, PropertyFilter filter)
– A PropertyFilter object that represents information for controlling
which property values to refresh
– Specifying null for property filter is the same as calling
save(RefreshMode refreshMode)
30
ADDITIONAL INFORMATION
RefreshMode.NO_REFRESH
RefreshMode REFRESH
Specifies that upon saving or committing the object, its property cache is not
refreshed with updated data from the Content Engine server.
Specifies that upon saving or committing the object, its property cache is
refreshed with updated data from the Content Engine server.
Instructor Notes:
None
Rev 1.0
Documents
30
Documents
Create Document Objects
Sample Code to Create a Document Object
Create a Document object
Document myDoc = Factory.Document.createInstance
(objectStore,“TravelDocument");
Set Content to the Document object
ContentElementList contentList =
Factory.ContentElement.createList();
ContentTransfer content =
Factory.ContentTransfer.createInstance();
content.setCaptureSource(new
FileInputStream(“passport.jpg"));
contentList.add(content);
myDoc.set_ContentElements(contentList);
31
Instructor Notes:
None
Rev 1.0
Documents
31
Documents
Create Document Objects
Sample Code to Create a Document Object (cont’d)
Check in the document
myDoc.checkin(AutoClassify.AUTO_CLASSIFY,
CheckinType.MAJOR_VERSION);
Set Properties to the document and Save the document
myDoc.getProperties().putValue("DocumentTitle",
“Passport document");
myDoc.set_MimeType(“image/jpeg");
myDoc.save(RefreshMode.REFRESH);
File the document to a folder
ReferentialContainmentRelationship rel =
folder.file(myDoc, AutoUniqueName.AUTO_UNIQUE,
"myXMLDoc",DefineSecurityParentage.DO_NOT_
DEFINE_SECURITY_PARENTAGE);
rel.save(RefreshMode.NO_REFRESH);
32
Instructor Notes:
None
Rev 1.0
Documents
32
Documents
Create Document Objects
Sample Code to Set Multiple Content Elements
Set Content data that is local to an object store
…
ContentTransfer content1 =
Factory.ContentTransfer.createInstance();
content1.setCaptureSource(new
FileInputStream("Winter.jpg"));
content1.set_ContentType("image/jpeg");
contentList.add(content1);
ContentTransfer content2 =
Factory.ContentTransfer.createInstance();
content2.setCaptureSource(new
FileInputStream("TestTicket.xml"));
content2.set_ContentType("text/xml");
contentList.add(content2);
…
33
ADDITIONAL INFORMATION
The steps to create a Document object with multiple content elements are similar to creating a Document object
with a single content element.
The difference is adding several content elements to the Content Element List.
Refer to the sample code for creating a document on the previous slides.
Instructor Notes:
None
Rev 1.0
Documents
33
Documents
Create Document Objects
Sample Code to Set Content Reference
External content data that exists outside of an object store
ContentReference contentRef =
Factory.ContentReference.createInstance();
contentRef.set_ContentLocation
("http://www.filenet.com");
contentRef.set_ContentType("image/jpg");
contentList.add(contentRef);
Set content element to the document
myDoc.set_ContentElements(contentList);
34
Instructor Notes:
None
Rev 1.0
Documents
34
Documents
Create Document Objects
Activities
In your workbook, see
y Lesson: Create Document Objects
Complete these activities:
1. Get Object Store and Folder
2. Create a Document object
3. Set Content and Check In the Document
4. Set the Properties and Save the Document
5. File the Document to a Folder
6. Call the Methods That You Wrote
7. Run the Code and Verify the Results
8. Optional: Set Multiple Content Elements to a Document
9. Optional: Set External Content Element to a Document
35
Instructor Notes:
None
Rev 1.0
Documents
35
Documents
Rev 1.0
Documents
36
Documents
Module: Documents
Lesson:
Retrieve a Document and Its Content
37
Instructor Notes:
None
Rev 1.0
Documents
37
Documents
Retrieve a Document and Its Content
Scenario
y Your company employees will access document objects to
review their content. As their programmer, you will write
code to retrieve a document object and its content when an
employee accesses the document.
38
Instructor Notes:
None
Rev 1.0
Documents
38
Documents
Retrieve a Document and Its Content
Lesson Objectives
In this lesson, you will
y Write code to retrieve a document
y Write code to retrieve document content
39
Instructor Notes:
None
Rev 1.0
Documents
39
Documents
Retrieve a Document and Its Content
Java API Methods Presented in This Lesson
Factory.Document.fetchInstance(…)
document.get_Name()
document.get_ContentElements()
contentElement.get_ContentType()
contentTransfer.get_RetrievalName()
contentTransfer.get_ContentSize()
contentTransfer.accessContentStream()
40
Instructor Notes:
None
Rev 1.0
Documents
40
Documents
Retrieve a Document and Its Content
Steps to Retrieve a Document Object
1. Get the Document object
Factory.Document.fetchInstance(…)
2. Get the document name (optional)
document.get_Name()
41
Instructor Notes:
None
Rev 1.0
Documents
41
Documents
Retrieve a Document and Its Content
Steps to Retrieve a Document Object
1. Get the document content elements
document.get_ContentElements()
2. Get the Content type for the content element
contentElement.get_ContentType()
3. Get the file name where the content data is stored
contentTransfer.get_RetrievalName()
4. Get the content size for the document
contentTransfer.get_ContentSize()
5. Get an input stream for reading the content data
contentTransfer.accessContentStream()
42
Instructor Notes:
None
Rev 1.0
Documents
42
Documents
Retrieve a Document and Its Content
Factory.Document.fetchInstance(…)
public static Document
fetchInstance(ObjectStore os,Id objectId,
PropertyFilter filter)
Parameters
y os - Specify the ObjectStore object where this document is located
y Id - Specify GUID or folder path for the document
y filter - Specify a PropertyFilter object for which property values to
return
Returns
y The specified Document object
Notes
y If the value for the property filter is null, this method returns
– Values for all non-object properties
– Placeholders for all object-valued properties
43
Instructor Notes:
Inconsistency in retrieving a document using the folder path and document name:
I have run “add document code” more than once with the document name hard coded. It ended up adding two documents
with the same name on the same folder (it did not complain). When I tried to retrieve the document with the path, it threw
an error.
Even after deleting the duplicate document, it still did not work. However, I was able to retrieve it using the GUID. The
documents that are added once did not have this problem. They were retrieved using folder path.
Rev 1.0
Documents
43
Documents
Retrieve a Document and Its Content
document.get_Name()
public String get_Name()
Parameters
y None
Returns
y A String representing the name of this object
44
Instructor Notes:
None
Rev 1.0
Documents
44
Documents
Retrieve a Document and Its Content
document.get_ContentElements()
public ContentElementList get_ContentElements()
Parameters
y None
Returns
y A ContentElementList object containing the list of content elements
associated with this document
Notes
y Each content element represents content data, which can be either
– Local to an object store
– External
45
Instructor Notes:
None
Rev 1.0
Documents
45
Documents
Retrieve a Document and Its Content
contentElement.get_ContentType()
public String get_ContentType()
Parameters
y None
Returns
y The Value of the ContentType property as a MIME format string
46
ADDITIONAL INFORMATION:
• Multipurpose Internet Mail Extensions (MIME) is a communications protocol that allows for the transmission of
data in many forms:
Examples: audio, binary, or video
• A MIME format string consists of a content type, a content subtype, and an optional parameter in the following
format: "MIME::content type/subtype[;parameter]".
Example: "MIME::text/html"
•For more information on the supported MIME types , see ContentType Property in Content Engine Java API help.
Instructor Notes:
None
Rev 1.0
Documents
46
Documents
Retrieve a Document and Its Content
document.get_ContentElementsPresent()
public StringList get_ContentElementsPresent()
Parameters
y None
Returns
y A StringList object containing the MIME type of each content
element associated with this document at the time it was last saved.
Notes
y This method returns the MIME type of the content elements as the
y
y
method on the previous slide:
contentElement.get_ContentType()
The difference is that the previous method returns the MIME type
for the given content element in a String.
This method retrieves the MIME type for all the content elements of
the given document.
47
ADDITIONAL INFORMATION:
• This method returns the MIME type of the content elements as the method on the previous slide:
contentElement.get_ContentType()
• The difference is that previous method returns the MIME type for a given content element in a String.
• This method retrieves the MIME type for all the content elements of a given document in a StringList collection.
Instructor Notes:
None
Rev 1.0
Documents
47
Documents
Retrieve a Document and Its Content
contentTransfer.get_RetrievalName()
public String get_RetrievalName()
Parameters
y None
Returns
y The file path and file name from which the content data for this
content element can be retrieved
Notes
y The path including the file name can contain up to 2083 characters
y The file name can be up to 255 characters long
48
Instructor Notes:
None
Rev 1.0
Documents
48
Documents
Retrieve a Document and Its Content
contentTransfer.get_ContentSize()
public Double get_ContentSize()
Parameters
y None
Returns
y The size (in bytes) of the content data associated with this
ContentTransfer object
49
Instructor Notes:
None
Rev 1.0
Documents
49
Documents
Retrieve a Document and Its Content
contentTransfer.accessContentStream()
public java.io.InputStream accessContentStream()
Parameters
y None
Returns
y An InputStream object for reading content data
Notes
y This method uses an input stream to obtain read access to
the content data.
y If content data is not present in the object property cache, it
is fetched from the server.
50
Instructor Notes:
The Content Engine will not automatically close the stream after access has finished. Unless you want the stream to remain
open, your application must close the stream after it has finished reading the content data.
Rev 1.0
Documents
50
Documents
Retrieve a Document and Its Content
Sample Code to Retrieve a Document
Retrieve a document
Document document =
Factory.Document.fetchInstance
(objectstore,"/Test/TestDocument",null);
Retrieve a document name
String documentName = doc.get_Name();
51
Instructor Notes:
None
Rev 1.0
Documents
51
Documents
Retrieve a Document and Its Content
Sample Code to Retrieve a Document’s Content
Retrieve individual content elements
ContentElementList contentElements =
document.get_ContentElements();
ContentElement contentElement;
Iterator itContent =
contentElements.iterator();
while (itContent.hasNext()){
contentElement =
(ContentElement)itContent.next();
Retrieve the Content Type for the content element
System.out.println("content type = " +
contentElement.get_ContentType());
Get the ContentStream
y Continued on the next slide
}
52
Instructor Notes:
None
Rev 1.0
Documents
52
Documents
Retrieve a Document and Its Content
Sample Code to Retrieve Get the ContentStream
Get the file name where the content data is stored
String fileName =
contentTransfer.get_RetrievalName();
Get the content size for the document
Double contentSize =
contentTransfer.get_ContentSize();
Get an input stream for reading the content data and flush it out
InputStream inputStream =
contentTransfer.accessContentStream();
OutputStream outputStream = new
FileOutputStream(fileName);
byte[] nextBytes = new byte[64000];
while ((int nBytesRead =
inputStream.read(nextBytes))!= -1){
outputStream.write(nextBytes, 0,nBytesRead);
outputStream.flush();}
53
Instructor Notes:
In the sample code above, the outputstream writes out to a file. Lab instructions include a step to verify that the file has
been created.
Rev 1.0
Documents
53
Documents
Retrieve a Document and Its Content
Activities
In your workbook, see
y Lesson: Retrieve a Document and Its Content
Complete these activities:
1. Retrieve a Document
2. Retrieve Document Content
54
Instructor Notes:
None
Rev 1.0
Documents
54
6
6
Properties
Java API Programmer
Properties
IBM FileNet Content Manager
Instructor Notes:
None
Rev 1.0
Properties
1
Properties
Rev 1.0
Properties
2
Properties
Properties
This module consists of these lessons:
y Retrieve Property Descriptions
y Retrieve a Choice List
y Retrieve Object Properties
3
ADDITIONAL INFORMATION:
Setting property values to an object is discussed in the Custom Object module.
Instructor Notes:
None
Rev 1.0
Properties
3
Properties
Rev 1.0
Properties
4
Properties
Module: Properties
Lesson:
Retrieve Property Descriptions
5
Instructor Notes:
None
Rev 1.0
Properties
5
Properties
Retrieve Property Descriptions
Scenario
y To manage the properties of the Content Engine objects,
you need to retrieve the property descriptions. As a
programmer, you will write code to retrieve and display the
property descriptions of a given Document class.
6
Instructor Notes:
None
Rev 1.0
Properties
6
Properties
Retrieve Property Descriptions
Properties Defined
Properties in an object store are
y Individual values used to describe an object
y Defined on a class and are inheritable by subclasses
Definition of a property includes
y
y
y
y
y
Data type: Scalar or object-valued
Cardinality: Single or multivalue
Settability: Read-only, read-write
Whether it is the “Name” property
If it has a ChoiceList
Definition of a property is accessed via the API
through the property description
7
ADDITIONAL INFORMATION
FileNet P8 documentation > FileNet P8 Administration > Content Engine Administration > Properties > Concepts
FileNet P8 documentation > Developer Help > Content Engine Development > Java and .NET developer’s Guide
> Properties > Concepts
Scalar data types are Binary, Boolean, DateTime, Float, ID, Integer, String. There is a single Object-valued type,
and it is used to represent an object. For example, the annotations associated with a document can be
represented as Object type properties for the document..
Instructor Notes:
Ask students if they are familiar with the general concepts of object classes and properties in the P8 domain and if
necessary, provide them background. This slide and the next two slides deal with basic concepts of properties.
Rev 1.0
Properties
7
Properties
Retrieve Property Descriptions
Setting and Accessing Property Values
Property values are saved on the server when the
associated object is saved
y When first set, the properties are in memory
y The object has to be saved for the properties to persist
Properties can be retrieved for display and update in
the following ways:
y In a group, along with an object
y By name, individually or collectively
y In filtered sets
Properties transit through local cache
y Fetched from server into local cache
y Accessed from there by your program
8
Instructor Notes:
None
Rev 1.0
Properties
8
Properties
Retrieve Property Descriptions
Property Cache
Temporary local store for object and property states
Exists to reduce or eliminate roundtrips to the server
Ways to add object properties to the property cache:
y Call object refresh method for an existing object
y Call fetch property or fetch properties method
y Call object setter methods
Retrieve from cache:
y Individually or in collections
9
HELP PATH
FileNet P8 documentation > Developer Help > Content Engine Development > Java and .NET developer’s Guide >
Properties > Concepts >Property Cache Concepts
ADDITIONAL INFORMATION
To save system resources, each Content Engine object maintains a local (client-side) property cache from which one
or more of an object's properties, if available, can be retrieved.
Object refresh method pulls properties from the server. It replaces the object’s properties currently in cache and adds
any new properties not in cache.
Fetch property or fetch properties methods merge with existing properties and add any new properties not in cache.
Object setter methods are used in your program to write values to properties. You learned about Properties.putValue
in an earlier module. There is also the Property.setObjectValue(java.lang.Object val) method.
Get property or getProperties methods retrieve from cache and throw an exception if a requested property is not in
cache.
The system has an internal property called the update sequence number that it uses to coordinate concurrent
updates among different applications
Instructor Notes:
None
Rev 1.0
Properties
9
Properties
Retrieve Property Descriptions
Lesson Objectives
In this lesson, you will
y Write code to retrieve class descriptions
y Write code to retrieve property descriptions
10
Instructor Notes:
None
Rev 1.0
Properties
10
Properties
Retrieve Property Descriptions
Java API Methods Presented in This Lesson
objectStore.get_ClassDescriptions(…)
classDescription.get_DisplayName()
classDescriptions.describedIsOfClass(…)
classDescription.get_PropertyDescriptions(…)
propertyDescription.get_SymbolicName()
propertyDescription.get_IsReadOnly()
propertyDescription.get_IsValueRequired()
propertyDescription.get_Settability()
propertyDescription.get_Cardinality()
propertyDescription.get_IsSystemGenerated()
11
ADDITIONAL INFORMATION
Other methods discussed in the lesson are the following:
propertyFilter. addIncludeType (…)
propertyFilter.addExcludeProperty (…)
propertyFilter.addIncludeProperty (…)
Instructor Notes:
None
Rev 1.0
Properties
11
Properties
Retrieve Property Descriptions
Class and Property Description Objects
ClassDescription object
y Used to describe a class instance configured in the object
store
y Also used for obtaining class information for any object
stored in a library
PropertyDescription object
y Used to obtain the attributes and data type of a property
assigned to a class
12
Instructor Notes:
None
Rev 1.0
Properties
12
Properties
Retrieve Property Descriptions
ClassDescription Objects
ClassDescription objects
y Are collections of metadata that describes individual
classes
y Provide access to PropertyDescription objects associated
with class
y Return default permission for an object of a particular class
y Check whether versioning is enabled for a particular
Document class
y Assign a document lifecycle policy to a document class or
subclass
13
Instructor Notes:
None
Rev 1.0
Properties
13
Properties
Retrieve Property Descriptions
PropertyDescription Objects
PropertyDescription objects
y Are collections of metadata that describes individual properties
y Are contained in the ClassDescription PropertyDescriptions
property
y Provide information on how the property should be represented to
the user
y Contain information such as choice lists
Each instance of a PropertyDescription object
y Describes a specific property for a single class
14
ADDITIONAL INFORMATION
1.
2.
3.
When you create a new class (for example, a document class), the PropertyDescription that you choose is copied into
the class.
After the class is created, if you modify that PropertyDescription, it is not automatically updated in the Document class.
You need to delete the old PropertyDescription and add the new or modified one to the class.
After the updating the class, only newly created objects (for example, documents) will have the updated property.
Instructor Notes:
None
Rev 1.0
Properties
14
Properties
Retrieve Property Descriptions
Steps to Retrieve a Property Description
1
1. Object
Instance
2
2.Class
Description
3
3.Property
Descriptions
Collection
4
4. Property
Description
for each
property
15
ADDITIONAL INFORMATION
1. Retrieve the target object.
2. Retrieve the class description from the target object.
3. Retrieve the property descriptions from the class description.
4. Iterate through collection and retrieve the descriptive information for each property
Instructor Notes:
None
Rev 1.0
Properties
15
Properties
Retrieve Property Descriptions
Steps to Retrieve Class Descriptions
1. Get the object store.
Factory.ObjectStore.fetchInstance(…)
2. Get all the class descriptions for this object store.
objectStore.getClassDescriptions(…)
3. Get the iterator to get the collection.
classDescriptions.iterator()
4. Display individual class description.
iterator.next()
classDescription.getName()
16
Instructor Notes:
None
Rev 1.0
Properties
16
Properties
Retrieve Property Descriptions
Steps to Retrieve Property Descriptions
1.
Retrieve property descriptions collection.
classDescription.getPropertyDescriptions(…)
2.
Iterate through the collection.
propertyDescriptions.iterator()
3.
Display individual property description.
iterator.next()
propertyDescription.get_SymbolicName()
propertyDescription.get_IsReadOnly()
propertyDescription.get_IsValueRequired()
propertyDescription.get_Settability()
propertyDescription.get_Cardinality()
propertyDescription.get_IsSystemGenerated()
17
Instructor Notes:
None
Rev 1.0
Properties
17
Properties
Retrieve Property Descriptions
objectStore.get_ClassDescriptions()
public ClassDescriptionSet get_ClassDescriptions()
Parameters
y None
Returns
y A ClassDescription collection for the Content Engine classes and
subclasses
Notes
y The ClassDescriptions property returns a snapshot of the latest class
metadata for a given object store.
18
Instructor Notes:
None
Rev 1.0
Properties
18
Properties
Retrieve Property Descriptions
classDescription.describedIsOfClass(…)
public Boolean describedIsOfClass(String className)
Parameters
y className - A String that specifies the symbolic name or ClassNames
constant of the parent class to check this subclass against.
Returns
y Whether the class described by this ClassDescription object is a
subclass of the specified class (true) or not (false)
19
Instructor Notes:
None
Rev 1.0
Properties
19
Properties
Retrieve Property Descriptions
classDescription.get_DisplayName()
public String get_DisplayName()
Parameters
y None
Returns
y A String containing the user-readable name of an object
Notes
y This property is usually the designated Name property of the object
class.
20
Instructor Notes:
None
Rev 1.0
Properties
20
Properties
Retrieve Property Descriptions
classDescription.get_PropertyDescriptions()
public PropertyDescriptionList
get_PropertyDescriptions()
Parameters
y None
Returns
y An ordered collection containing all the PropertyDescription
objects for this ClassDescription object
21
Instructor Notes:
None
Rev 1.0
Properties
21
Properties
Retrieve Property Descriptions
propertyDescription.get_SymbolicName()
public String get_SymbolicName()
Parameters
y None
Returns
y A String that represents the programmatic identifier for this
PropertyDescription
22
Instructor Notes:
None
Rev 1.0
Properties
22
Properties
Retrieve Property Descriptions
propertyDescription.get_IsReadOnly()
public Boolean get_IsReadOnly()
Parameters
y None
Returns
y A Boolean value that indicates whether or not you can modify the
value of the property.
y If true, the property value can be changed only by the server.
23
Instructor Notes:
None
Rev 1.0
Properties
23
Properties
Retrieve Property Descriptions
propertyDescription.get_IsValueRequired()
public Boolean get_IsValueRequired()
Parameters
y None
Returns
y A Boolean value that indicates whether the property is required to
have a value (true) or not (false).
Notes
y If you attempt to save an object containing a property that requires
a value and that property does not have a value assigned to it, an
exception will occur.
24
Instructor Notes:
None
Rev 1.0
Properties
24
Properties
Retrieve Property Descriptions
propertyDescription.get_Settability()
public PropertySettability get_Settability()
Parameters
y None
Returns
y A constant that indicates when the value of a property can be set:
– READ
– READ_WRITE
– SETTABLE_ONLY_BEFORE_CHECKIN
– SETTABLE_ONLY_ON_CREATE
25
ADDITIONAL INFORMATION
Name
Value
Description
READ_ONLY
3
Indicates that a property is read-only. Only the server
can set its value.
READ_WRITE
0
Indicates that a property is read or write. You can set its
value at any time.
SETTABLE_ONLY_BEFORE_CHECKIN 1
Indicates that you can set the value of a property
only before you check in the object to which it belongs.
SETTABLE_ONLY_ON_CREATE
Indicates that you can set the value of a property
only when you create the object to which it belongs.
When you save the object for the first time, the property
value cannot be changed.
2
Instructor Notes:
None
Rev 1.0
Properties
25
Properties
Retrieve Property Descriptions
propertyDescription.get_Cardinality()
public Cardinality get_Cardinality()
Parameters
y None
Returns
y A constant that indicates the cardinality of the PropertyDescription:
– ENUM
– LIST
– SINGLE
26
ADDITIONAL INFORMATION
Name
Value
Description
ENUM
1
Enumeration cardinality indicates a property that returns a read-only
collection of unique items with a data type of object. The items
returned by a property of enumeration cardinality can only be traversed
sequentially. The number, order, and values of the items in an
enumeration collection can change even if a reference to it remains
constant.
LIST
2
List cardinality indicates a property that returns a collection of items,
which might be modifiable (allowing items to be inserted, replaced, or
deleted) or read-only. The items returned by a property of list
cardinality can be accessed in random order. The number, order, and
values of the items in a list collection remain constant as long as a
reference to it is maintained.
SINGLE
0
Single cardinality indicates a property that returns a single value.
Instructor Notes:
None
Rev 1.0
Properties
26
Properties
Retrieve Property Descriptions
propertyDescription.get_IsSystemGenerated()
public Boolean get_IsSystemGenerated()
Parameters
y None
Returns
y A Boolean value that indicates whether the property has its value
set automatically by the Content Engine server (true) or not (false).
Notes
y if the value is true, the described property
– Provides system information OR
– Has its value determined by the server
27
ADDITIONAL INFORMATION
If IsSystemGenerated is true, the described property
•Provides system information
- Example: DateCreated
Or
•Has its value determined by the server according to the results of a method call or some other operation
- Example: If you call a CreateSubFolder folder method, the system automatically adds the newly created
folder to the collection of objects returned by the SubFolders property.
Instructor Notes:
None
Rev 1.0
Properties
27
Properties
Retrieve Property Descriptions
Sample Code to Retrieve Class Descriptions
ClassDescriptionSet classDescriptions =
objectStore.get_ClassDescriptions();
ClassDescription classDesc;
Iterator it = classDescriptions.iterator();
while (it.hasNext()) {
classDesc = (ClassDescription)it.next();
System.out.println("Class name = " +
classDesc.get_DisplayName());
}
28
Instructor Notes:
None
Rev 1.0
Properties
28
Properties
Retrieve Property Descriptions
Sample Code to Retrieve Property Descriptions
…
ClassDescription classDescription =
document.get_ClassDescription();
PropertyDescriptionList propDescs =
classDescription.get_PropertyDescriptions();
PropertyDescription propDesc;
Iterator propIt = propDescs.iterator();
while (propIt.hasNext()) {
propDesc =PropertyDescription)propIt.next();
System.out.println("Property name = " +
propDesc.get_SymbolicName());
System.out.println("Read only? " +
propDesc.get_IsReadOnly().toString());
…
}
29
Instructor Notes:
None
Rev 1.0
Properties
29
Properties
Retrieve Property Descriptions
Activities
In your workbook, see
y Lesson: Retrieve Property Descriptions
Complete these activities:
y Retrieve Class Descriptions
y Retrieve Property Descriptions
30
Instructor Notes:
None
Rev 1.0
Properties
30
Properties
Module: Properties
Lesson:
Retrieve a Choice List
31
Instructor Notes:
None
Rev 1.0
Properties
31
Properties
Retrieve a Choice List
Scenario
y The custom application provides its customers with
payment options when ordering Merchandise. A choice list
for the payment options has been created on the Content
Engine using FileNet Enterprise Manager. As the
programmer, you will write code to retrieve and display the
choice list of payment options.
32
Instructor Notes:
None
Rev 1.0
Properties
32
Properties
Retrieve a Choice List
Lesson Objectives
In this lesson, you will
y Write code to retrieve choice list properties
33
Instructor Notes:
None
Rev 1.0
Properties
33
Properties
Retrieve a Choice List
Java API Methods Presented in This Lesson
propertyDescription.get_ChoiceList(…)
choiceList.get_ChoiceValues()
choiceList.get_HasHierarchy()
choice.get_ChoiceType()
choice.get_ChoiceIntegerValue()
choice.get_ChoiceStringValue()
34
Instructor Notes:
None
Rev 1.0
Properties
34
Properties
Retrieve a Choice List
Choice List Objects
Each Choice List object
y Typically created using FileNet Enterprise Manager
y Contains a list of choices from which users select a value
Elements in the collection are Choice objects
y Represent a set of choices for a settable property
y Can be hierarchical: a Choice element can itself contain a
collection of choices
35
HELP PATH:
FileNet P8 documentation > FileNet P8 Administration > Content Engine Administration > Properties > Concepts
FileNet P8 documentation > Developer Help > Content Engine Development > Java and .NET developer’s Guide
> Properties > Concepts
Note: It is also possible to create a choice list with a custom program written to the API.
Instructor Notes:
None
Rev 1.0
Properties
35
Properties
Retrieve a Choice List
Using Choice Lists
Usage requirements
y A choice list must be assigned to a property template
y A choice list must use either a String or an Integer data
type
y A choice list data type must match the data type for its
associated property template
Usage options
y One choice list can be used by many properties
36
Instructor Notes:
None
Rev 1.0
Properties
36
Properties
Retrieve a Choice List
ChoiceList Interface
The API has two versions of the ChoiceList interface
y com.filenet.api.admin.ChoiceList
y com.filenet.api.collection.ChoiceList
com.filenet.api.admin.ChoiceList
y Has the methods needed to access choice lists
com.filenet.api.collection.ChoiceList
y Defines the ChoiceList collection returned by
com.filenet.api.admin.get_ChoiceValues()
y Provides access to individual choices
37
ADDITIONAL INFORMATION
The PropertyDescription.get_ChoiceList() method returns a com.filenet.api.admin.ChoiceList. Use this when testing
whether a particular property has a choice list associated with it.
The com.filenet.api.admin.ChoiceList.get_ChoiceValues() method returns a collection, or a
com.filenet.api.collection.ChoiceList. Use this to access Choice objects, whether they are singular objects or nested
choice lists.
Instructor Notes:
None
Rev 1.0
Properties
37
Properties
Retrieve a Choice List
Choice Objects
Choice objects (choices)
y Represent possible values of a property
y Can be String or Integer data type
y Can provide access to a nested choice list
The Content Engine Java API
y Includes methods to
– Retrieve a ChoiceList from a PropertyDescription
– Check for a ChoiceList collection contained in a Choice object
– Return the contained ChoiceList collection if found
38
Instructor Notes:
None
Rev 1.0
Properties
38
Properties
Retrieve a Choice List
Steps to Retrieve a Choice List
1. Get the class description for the specified class.
document.get_ClassDescription()
2. Get the property descriptions collection for that class.
classDescription.get_PropertyDescriptions()
3. Get an individual property description.
propertyDescriptionList.iterator()
Iterator.next()
4. Get the choice list from the property description.
propDescription.get_ChoiceList()
5. Get the Choice collection.
choiceList.get_ChoiceValues()
6. Get the individual choice and its value.
choice.get_ChoiceStringValue()
choice.get_ChoiceIntegerValue().toString()
39
Instructor Notes:
Next slides shows the schematic diagram of these steps.
Rev 1.0
Properties
39
Properties
Retrieve a Choice List
Steps to a Retrieve Property and Choice List
1
1. Class
Description
2
2. PropertyDescriptions
Collection
Object
3
3. Property
Description
4
5.Collection
Choice List
6
Choice
Choice
5
4.Admin
Choice List
40
ADDITIONAL INFORMATION
1.
2.
3.
4.
5.
6.
Retrieve the class description for a given Document class from the Document object.
Retrieve the property description collection from the class description.
Retrieve the individual property description from the collection.
Retrieve the choice list or the property metadata from the property description.
Retrieve the choice list collection from the admin choice list.
Retrieve individual choices from the choice list collection.
Note: Retrieving properties and their metadata is discussed in the next lesson.
Instructor Notes:
None
Rev 1.0
Properties
40
Properties
Retrieve a Choice List
PropertyDescription.get_ChoiceList(…)
public ChoiceList get_ChoiceList()
Parameters
y None
Returns
y A ChoiceList that contains the Choice objects
Notes
y There are two ChoiceList classes in Content Engine Java API:
– The method on this slide returns the
com.filenet.api.admin.ChoiceList class.
– The method on the next slide returns the
com.filenet.api.collection.ChoiceList class.
41
ADDITIONAL INFORMATION
A ChoiceList object can have nested ChoiceList objects.
Instructor Notes:
None
Rev 1.0
Properties
41
Properties
Retrieve a Choice List
choiceList.get_ChoiceValues()
public ChoiceList get_ChoiceValues()
Parameters
y None
Returns
y A ChoiceList collection object representing a set of allowable
values
Notes
y The ChoiceValues define the set of possible values in a choice list
group.
y This ChoiceList class belongs to the com.filenet.api.collection
package.
42
Instructor Notes:
None
Rev 1.0
Properties
42
Properties
Retrieve a Choice List
choice.get_ChoiceType()
public ChoiceType get_ChoiceType()
Parameters
y None
Returns
y A ChoiceType constant that indicates the type of data that a Choice
object represents
Notes
y Examples of ChoiceType constants:
– ChoiceType.INTEGER
– ChoiceType.STRING
43
ADDITIONAL INFORMATION
Name
Value
Description
INTEGER
0
Choice object that holds an Integer data type
MIDNODE_INTEGER
2
Choice object that acts as a group node for Choice
objects that hold Integer data types
MIDNODE_STRING
3
Choice object that acts as a group node for Choice
objects that hold String data types.
STRING
1
Choice object that holds a String data type
Instructor Notes:
None
Rev 1.0
Properties
43
Properties
Retrieve a Choice List
choiceList.get_HasHierarchy()
public Boolean get_HasHierarchy()
Parameters
y None
Returns
y A Boolean value that specifies whether a given choice list has a
hierarchical structure (true) or not (false).
44
Instructor Notes:
None
Rev 1.0
Properties
44
Properties
Retrieve a Choice List
choice.get_ChoiceIntegerValue()
public Integer get_ChoiceIntegerValue()
Parameters
y None
Returns
y The value of a Choice object that holds an Integer data type in a
choice list
45
Instructor Notes:
None
Rev 1.0
Properties
45
Properties
Retrieve a Choice List
choice.get_ChoiceStringValue()
public String get_ChoiceStringValue()
Parameters
y None
Returns
y The value of a Choice object that holds a String data type in a
choice list
Notes
y A ChoiceList object can have nested ChoiceList objects.
46
Instructor Notes:
None
Rev 1.0
Properties
46
Properties
Retrieve a Choice List
Sample Code to Retrieve a Choice List
Get the choice list for this property.
…
com.filenet.api.admin.ChoiceList choices
= propDescription.get_ChoiceList();
System.out.println("ChoiceList name = "+
propDescription.get_SymbolicName());
47
Instructor Notes:
None
Rev 1.0
Properties
47
Properties
Retrieve a Choice List
Sample Code to Retrieve a Choice List
com.filenet.api.collection.ChoiceList choices =
choiceList.get_ChoiceValues();
Choice choice;
Iterator choiceIt = choices.iterator();
while (choiceIt.hasNext()) {
choice = (Choice)choiceIt.next();
if (choice.get_ChoiceType().equals
(ChoiceType.INTEGER)){
Integer choiceInt =
choice.get_ChoiceIntegerValue()
System.out.println("choice = " + choiceInt
.toString());
}
else{
String choiceString =
choice.get_ChoiceStringValue();
System.out.println("choice = " + choiceString);
}
}
48
Instructor Notes:
None
Rev 1.0
Properties
48
Properties
Retrieve a Choice List
Activities
In your workbook, see
y Lesson: Retrieve a Choice List
Complete this activity:
y Retrieve a Choice List
49
Instructor Notes:
None
Rev 1.0
Properties
49
Properties
Rev 1.0
Properties
50
Properties
Module: Properties
Lesson:
Retrieve Object Properties
51
Instructor Notes:
None
Rev 1.0
Properties
51
Properties
Retrieve Object Properties
Scenario
y To manage the properties of the Content Engine objects,
you need to retrieve the properties for a given object. As a
programmer, you will write code to retrieve and display the
values of properties of a given Document class.
52
Instructor Notes:
None
Rev 1.0
Properties
52
Properties
Retrieve Object Properties
Lesson Objectives
In this lesson, you will
y Write code to retrieve object properties
53
Instructor Notes:
None
Rev 1.0
Properties
53
Properties
Retrieve Object Properties
Java API Methods Presented in This Lesson
propertyDescription.get_DataType()
property.getStringValue()
property.getStringListValue()
property.getInteger32Value()
property.getInteger32ListValue()
property.getDateTimeValue()
property.getDateTimeListValue()
54
Instructor Notes:
Samples of these methods are presented in the following slides. Since there is not much information for each method, they
are not discussed in individual slides.
Rev 1.0
Properties
54
Properties
Retrieve Object Properties
Steps to Retrieve a Given Property Value
1
4
1. Object
4.Class
Description
5
5.Property
Descriptions
Collection
2
2. Properties
Collection
Property-2
3
Property-1
8
6
Get Data Type 7
Property Value
6. Property
Description for
a property
55
ADDITIONAL INFORMATION
1.
2.
3.
4.
5.
6.
7.
8.
Retrieve the object.
Retrieve the property collection from the object.
Retrieve individual properties from the collection
Retrieve the class description from the target object.
Retrieve the property descriptions from the class description.
Retrieve the property description from the collection for the given property, using the property name.
Retrieve the data type for the property from the property description.
Retrieve the value for the property based on the data type.
Note: Steps 4, 5, 6 and 7 are optional if you know the data type for the property.
Instructor Notes:
None
Rev 1.0
Properties
55
Properties
Retrieve Object Properties
Steps to Retrieve a Property Description for a Property
1. Get the Document.
Factory.Document.fetchInstance(…)
2. Get the properties collection for this Document.
document.getProperties()
3. Get the individual property from collection.
properties.iterator()
Iterator.next()
property.getPropertyName()
4. Get the property descriptions.
document.get_ClassDescription();
classDescription.get_PropertyDescriptions();
propertyDescriptionList.iterator()
Iterator.next()
56
Instructor Notes:
None
Rev 1.0
Properties
56
Properties
Retrieve Object Properties
Steps to Retrieve a Property Value
1. Get the property description for the given property.
propertyDescription.get_SymbolicName()
if(symbolicName.equalsIgnoreCase(propertyName))
2. Get the data type for the property.
propertyDescription.get_Cardinality()
3. Get the value for the property after checking each data type.
if (propertyDesc.get_Cardinality().getValue() ==
Cardinality.SINGLE_AS_INT)
property.getDateTimeValue()
if(propertyDescription.get_Cardinality().getValue()
== Cardinality.SINGLE_AS_INT)
property.getStringValue()
…
57
Instructor Notes:
None
Rev 1.0
Properties
57
Properties
Retrieve Object Properties
Property Filters
Purpose
y Limit properties and property detail retrieved from server
y Improve retrieval performance
A property filter consists of
y A PropertyFilter object
y Filter element represented by a FilterElement object
– Each filter element represents a specification for adding properties
Attributes of a PropertyFilter object
y Act as global defaults for the PropertyFilter object
y Defaults values can be overridden
58
HELP PATH:
FileNet P8 documentation > Developer Help > Content Engine Development > Java and .NET developer’s
Guide > Properties > Concepts >Property Filter Concepts
ADDITIONAL INFORMATION
Because the number and size of properties can be large for certain objects, using a property filter to retrieve a
subset of the available properties can result in better performance by reducing the amount of data that is
retrieved from the server.
Instructor Notes:
None
Rev 1.0
Properties
58
Properties
Retrieve Object Properties
Components of Property Filters Object
IncludeProperty specifications (zero or more)
y Specifies, by identifier or FilterElement, properties to retrieve
from the server
addIncludeProperty(…)
IncludeType specifications (zero or more)
y Specifies, by property type or FilterElement, a class of properties
to retrieve from the server
addIncludeType(…)
ExcludeProperty specifications (zero or more)
y Specifies, by identifier, properties to be excluded from server
retrieval
addExcludeProperty(…)
59
HELP PATH:
FileNet P8 documentation > Developer Help > Content Engine Development > Java and .NET developer’s
Guide > Properties > Concepts >Property Filter Concepts
Instructor Notes:
None
Rev 1.0
Properties
59
Properties
Retrieve Object Properties
propertyFilter.addIncludeProperty (…)
public void addIncludeProperty(int maxRecursion,
Long maxSize, Boolean levelDependents,
String value)
Parameters
y maxRecursion – Specifies the maximum allowable recursion depth for
property retrieval.
y maxSize – Specifies the maximum size of content data to be retrieved.
y levelDependents –
– True if the recursion level is the same as that of the independent
object to which it belongs.
– False if the recursion level is one level deeper.
y value –
– Specifies a space-separated list of the symbolic names OR
– Specifies GUID-string identifiers of the properties to include.
60
ADDITIONAL INFORMATION
This method creates a FilterElement object and adds one or more properties identified by symbolic name or
GUID-string identifier to be included during an object retrieval or object refresh.
The values given for maxRecursion, maxsize, and levelDepenedents parameters override the global value
set by this PropertyFilter object.
Instructor Notes:
None
Rev 1.0
Properties
60
Properties
Retrieve Object Properties
propertyFilter.addExcludeProperty (…)
public void addExcludeProperty(
String value)
Parameters
y value –
– Specifies a space-separated list of the symbolic names OR
– Specifies GUID-string identifiers of the properties to include.
Returns
y Nothing
Notes
y Any properties specified for exclusion will override those properties that
are specified in
– An IncludeProperty OR
– An IncludeType specification
61
Instructor Notes:
None
Rev 1.0
Properties
61
Properties
Retrieve Object Properties
propertyFilter. addIncludeType (…)
public void addIncludeType (int maxRecursion,
Long maxSize, Boolean levelDependents,
FilteredPropertyType value)
Parameters
y maxRecursion – Specifies the maximum allowable recursion depth for
y
y
property retrieval.
maxSize – Specifies the maximum size of content data to be retrieved.
levelDependents –
– True if the recursion level is the same as that of the independent
object to which it belongs.
– False if the recursion level is one level deeper.
y value – Specifies the type of the properties to include.
– Use FilteredPropertyType constants.
62
ADDITIONAL INFORMATION
This method creates a FilterElement object and adds properties identified by type to be included during an
object retrieval or object refresh.
FilteredPropertyType is a constant specifying the type of the properties to include.
The values given in this method for maxRecursion, maxSize, and levelDependents override the global values
set by this PropertyFilter object.
Instructor Notes:
None
Rev 1.0
Properties
62
Properties
Retrieve Object Properties
propertyDescription.get_DataType()
public TypeID get_DataType()
Parameters
y None
Returns
y The data type of the value of the PropertyDescription:
– BINARY
– BOOLEAN
– DATE
– DOUBLE
– GUID
– LONG
– OBJECT
– STRING
63
ADDITIONAL INFORMATION
Name
Value
BINARY
1
Binary data type. Represents binary data by using an array of unsigned 8bit bytes.
BOOLEAN
2
Boolean data type. Represents Boolean data having a value of true or
false.
DATE
3
DateTime data type. Represents an instance in time as a date and time of
day in accordance with ISO 8601.
DOUBLE
4
Double (Float64) data type. Represents an IEEE-standard 64-bit floatingpoint number, which has a value ranging from -1.79769313486232e308 to
+1.79769313486232e308.
GUID
5
GUID (ID) data type. Represents a Globally Unique Identifier (GUID) or DCE
Universally Unique Identifier (UUID), which is a unique 128-bit number, as
a string of 32 hexadecimal characters enclosed by brackets in the following
format: {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}. For example,
{3F2504E0-4F89-11D3-9A0C-0305E82C3301}.
LONG
6
Integer data type. Represents a signed 32-bit integer, which has a value
ranging from -2,147,483,648 to +2,147,483,647.
OBJECT
7
Object data type. Represents an object that is instantiated from a Content
Engine class.
STRING
8
Represents text consisting of a sequential collection of 16-bit Unicode
characters.
Rev 1.0
Description
Properties
63
Properties
Retrieve Object Properties
PropertyDescription.get_RequiresUniqueElements()
public Boolean get_RequiresUniqueElements()
Parameters
y None
Returns
y A value to specify whether multivalue property must be unique
(true) or not (false)
64
Instructor Notes:
None
Rev 1.0
Properties
64
Properties
Retrieve Object Properties
property.getStringValue()
public String getStringValue()
Parameters
y None
Returns
y A String specifying the property value
65
Instructor Notes:
None
Rev 1.0
Properties
65
Properties
Retrieve Object Properties
property.getStringListValue()
public StringList getStringListValue()
Parameters
y None
Returns
y A collection containing all the values for this property in a
StringList object
66
Instructor Notes:
None
Rev 1.0
Properties
66
Properties
Retrieve Object Properties
Sample Code to Retrieve a Property Value
Retrieve the properties collection.
com.filenet.api.property.Properties properties
= document.getProperties();
Retrieve a property by symbolic name.
Property property =
properties.get("DocumentTitle");
Get property value based on the datatype of the property.
String propertyValue = property.getStringValue();
Notes
y To get the data type of the property for which you are
retrieving the value, additional steps are required as
shown in the next two slides.
67
ADDITIONAL INFORMATION
1. Retrieve the object.
2. Retrieve the property collection from the object.
3. Retrieve a property from the collection.
4. Retrieve the value for the property based on the data type.
Note: If you do not know the data type for the property, you need additional steps as described in the next slide.
Typically this involves a switch statement
Instructor Notes:
None
Rev 1.0
Properties
67
Properties
Retrieve Object Properties
Sample Code to Retrieve an Object Property
com.filenet.api.property.Properties properties
= document.getProperties();
Property property;
Iterator it = properties.iterator();
while (it.hasNext())
{
property = (Property)it.next();
String propertyName =
property.getPropertyName();
}
68
Instructor Notes:
None
Rev 1.0
Properties
68
Properties
Retrieve Object Properties
Sample Code to Retrieve a Property Value
…
switch(propertyDescription.get_DataType().getValue()){
case TypeID.DATE_AS_INT:
if(propertyDescription.get_Cardinality().
getValue() == Cardinality.SINGLE_AS_INT)
{
if (property.getDateTimeValue() != null)
property.getDateTimeValue().toString();
}
else
if(property.getDateTimeListValue()!= null)
property.getDateTimeListValue().toString());
break;
…
69
Instructor Notes:
None
Rev 1.0
Properties
69
Properties
Retrieve Object Properties
Activities
In your workbook, see
y Lesson: Retrieve Object Properties
Complete this activity:
y Retrieve object properties
70
Instructor Notes:
None
Rev 1.0
Properties
70
7
7
Searches
Java API Programmer
Searches
IBM FileNet Content Manager
Instructor Notes:
None
Rev 1.0
1
Searches
Searches
Rev 1.0
2
Searches
Searches
Searches
This module consists of these lessons:
y Search for Objects
y Build SQL Statements
y Content-Based Retrieval
3
Instructor Notes:
None
Rev 1.0
3
Searches
Searches
Rev 1.0
4
Searches
Searches
Module: Searches
Lesson:
Search for Objects
5
Instructor Notes:
None
Rev 1.0
5
Searches
Searches
Search for Objects
Scenario
y Your application requires a feature that searches for
Document objects on the given Content Engine. You, as
the programmer, will write code to accomplish this.
6
Instructor Notes:
None
Rev 1.0
6
Searches
Searches
Search for Objects
Lesson Objectives
In this lesson, you will
y Write code to do a property-based search for Documents
on Content Engine
y Write code to search for documents across object stores
7
Instructor Notes:
None
Rev 1.0
7
Searches
Searches
Search for Objects
Java API Methods Presented in This Lesson
searchScope.fetchObjects(…)
searchScope.fetchRows(…)
repositoryRow.getProperties()
Other related methods:
y
y
y
y
y
searchScope.fetchSearchableClassDescriptions(…)
objectStore.set_DefaultQueryTimeLimit (…)
serverCacheConfiguration.set_QueryPageMaxSize(…)
serverCacheConfiguration.set_QueryPageDefaultSize(…)
serverCacheConfiguration.set_NonPagedQueryMaxSize(…)
8
Instructor Notes:
None
Rev 1.0
8
Searches
Searches
Search for Objects
Steps to Search for Objects
1. Instantiate a SearchScope object with the Objectstore to search
from
new SearchScope(…)
2. Instantiate a SearchSQL object with the SQL statement.
new SearchSQL(…)
3. Retrieve the objects.
searchScope.fetchObjects(…)
4. Retrieve the object Properties.
searchScope.fetchRows(…)
repositoryRow.getProperties()
9
Instructor Notes:
None
Rev 1.0
9
Searches
Searches
Search for Objects
Steps to Retrieve Properties of the Objects
2.Document
3. Fetch Rows
Table from the
Database
Repository Row Set
(collection)
Row - 1
Row - 2
Row - N
(SQL)
4. Iterate
through
each row
(SearchScope)
1.Object Stores
6. Display the
Property name
5. Iterate through
each property
Properties Collection
Property-N
Property-1
Property-2
10
ADDITIONAL INFORMATION
1.
2.
3.
4.
5.
6.
SearchScope object defines the object store or object stores to search from.
SQL statement that is passed in as a parameter defines which table and criteria to retrieve.
SearchScope.fetchrows(…) method retrieves the rows collection.
Iterate through each row. Each row contains a collection of properties for a document.
Iterate through a properties collection to retrieve each property.
Get name and value of each property and display.
Instructor Notes:
None
Rev 1.0
10
Searches
Searches
Search for Objects
Searches
The essential parts of a Content Engine search are
y An SQL statement contained in a SearchSQL instance.
y The object store or object stores searched contained in a
SearchScope object.
11
Instructor Notes:
None
Rev 1.0
11
Searches
Searches
Search for Objects
SearchScope Class
SearchScope Class
y Determines which object stores are to be searched.
y Searches for properties, objects, and class metadata
(class descriptions).
y Can search one or more object stores using a single query.
SearchScope Methods
y Execute the SQL statement on one or more object stores:
– SearchScope(ObjectStore objectStore)
– SearchScope(ObjectStore[] objectStores,
MergeMode mergeMode)
MergeMode to specify union or intersection of object stores
12
ADDITIONAL INFORMATION
The SearchScope methods execute the SQL statement on one or more object stores to find objects
(IndependentObject instances), database rows (RepositoryRow instances), or metadata (ClassDescription
instances).
Instructor Notes:
None
Rev 1.0
12
Searches
Searches
Search for Objects
SearchSQL
SearchSQL is a helper class
y Used to assist in building valid SQL statements.
y Used to pass an instance of this class in to the
SearchScope.fetchObjects method to perform a query.
13
ADDITIONAL INFORMATION
There are helper methods on the SearchSQL class to assist you in constructing an SQL statement. The next
lesson deals with these methods.
Alternatively, you can construct an SQL statement independently and pass it to a SearchSQL instance as a
string.
SQL statements need to follow the FileNet standard, which generally conform to SQL-92, with extensions for
FileNet-specific constructs. See SQL Syntax Reference for a complete description.
Instructor Notes:
None
Rev 1.0
13
Searches
Searches
Search for Objects
searchScope.fetchObjects(…)
public IndependentObjectSet fetchObjects(
SearchSQL searchSQL, Integer pageSize,
PropertyFilter filter,
Boolean continuable)
Parameters
y searchSQL – Specify a SearchSQL instance containing the
SQL statement to use for the search.
y pageSize – Specify an integer indicating the maximum number
of objects per page to retrieve. This can be null.
y filter - A PropertyFilter object that represents information for
controlling which property values (and with what level of
detail and recursion) to return.
Returns
y IndependentObject objects collection from the object stores
14
ADDITIONAL INFORMATION
When pageSize is unspecified, the default page size (ServerCacheCofiguration.QueryPageDefaultSize) is
used.
If the continuable parameter is false or null, the pageSize value is ignored.
Instructor Notes:
None
Rev 1.0
14
Searches
Searches
Search for Objects
searchScope.fetchRows(…)
public RepositoryRowSet fetchRows(
SearchSQL searchSQL,
Integer pageSize,
PropertyFilter filter
Boolean continuable)
Parameters
y continuable –
– If false or null, the query is not paged.
– If true, when the end of the first page is reached, a request
for the next page of Properties objects is issued.
– Page requests iterate until all of the Properties objects
satisfying the query are retrieved.
Returns
y RepositoryRowSet object Rows of properties from object
stores
15
ADDITIONAL INFORMATION
Parameters:
A PropertyFilter object - Represents information for controlling which property values (with what level of
detail and recursion) to return.
If null, this method returns values for all nonobject properties and returns placeholders for all object-valued
properties (PropertyEngineObject properties with a state of PropertyState.UNEVALUATED or
PropertyState.REFERENCE).
Any subsequent attempts to access an object-valued property cause an automatic roundtrip to the server to
fetch its value.
SearchSQL - The selection list in the searchSQL parameter determines which top-level properties are
returned.
The property filter specified here determines the subproperties: the properties returned for the applicable
top-level properties. For example, if a top-level property specified in the selection list (searchSQL parameter)
is of type Object, the filter parameter determines which properties are returned in that object.
Queries using continuation use ORDER BY in their implementation. If an ORDER BY clause is not specified
in the SQL statement (the searchSQL parameter), an ORDER BY Id clause is used. If an ORDER BY clause
is specified in the SQL statement but does not contain the Id property, the Id property (having a unique
value) is appended to the end of the ORDER BY clause. You need to consider whether the overhead of
adding the Id property to the ORDER BY clause is significant for your application. Do not use a continuable
query if it might cause a severe performance reduction.
Instructor Notes:
None
Rev 1.0
15
Searches
Searches
Search for Objects
repositoryRow.getProperties()
public Properties getProperties()
Parameters
y none
Returns
y A Properties collection object containing a row of properties.
Notes
y This method gets a single row of properties from the
repository database.
y All properties returned will have the names as specified in
the SQL statement used for the query.
y Any properties that are not defined in a particular repository
will be returned with null values.
16
Instructor Notes:
None
Rev 1.0
16
Searches
Searches
Search for Objects
searchScope.fetchSearchableClassDescriptions(…)
public ClassDescriptionSet
fetchSearchableClassDescriptions (
String[] classNames,
PropertyFilter filter)
Retrieves class description object from object stores.
Parameters
y classNames - Names of the classes to retrieve. Can be the
symbolic name, the display name, or the object ID for the
class.
y filter - Information for controlling which property values (and
with what level of detail and recursion) to return.
Returns
y Collection of ClassDescription objects for the metadata
retrieved
17
ADDITIONAL INFORMATION
If the SearchScope instance references multiple repositories, properties that are not applicable to multiple
repositories will not be present in the ClassDescription objects returned, and will not be present in the
PropertyDescription objects contained in these ClassDescription objects.
If the filter is null, this method returns values for all nonobject properties and returns placeholders for all
object-valued properties (PropertyEngineObject properties with a state of PropertyState.UNEVALUATED or
PropertyState.REFERENCE). Any subsequent attempts to access an object-valued property cause an
automatic roundtrip to the server to fetch its value.
Instructor Notes:
None
Rev 1.0
17
Searches
Searches
Search for Objects
objectStore.set_DefaultQueryTimeLimit (…)
public void set_DefaultQueryTimeLimit(
Integer timeLimit)
Parameters
y timeLimit - An integer specifying the maximum duration of
the query.
Notes
y This method sets the default value (in seconds) for the
maximum amount of time that the server will allow a query to
run before canceling the query.
18
Instructor Notes:
None
Rev 1.0
18
Searches
Searches
Search for Objects
serverCacheConfiguration.set_QueryPageMaxSize (…)
public void set_QueryPageMaxSize(
Integer maxSize)
Parameters
y maxSize – Specifies the maximum size for a query page.
y Default value is 1000.
Notes
y This method sets the maximum size for a query page in a
result set.
19
Instructor Notes:
None
Rev 1.0
19
Searches
Searches
Search for Objects
serverCacheConfiguration.set_QueryPageDefaultSize (…)
public void set_QueryPageDefaultSize(
Integer defaultSize)
This method set the default size of a query page in a result set.
20
Instructor Notes:
None
Rev 1.0
20
Searches
Searches
Search for Objects
serverCacheConfiguration.set_NonPagedQueryMaxSize (…)
public void set_NonPagedQueryMaxSize(
Integer maxSize)
This method sets the maximum size of a nonpaged query result
set.
21
ADDITIONAL INFORMATION
When unspecified, all records that satisfy the query will be returned, subject to the limit of
ServerCacheConfiguration property NonPagedQueryMaxSize.
Instructor Notes:
None
Rev 1.0
21
Searches
Searches
Search for Objects
Sample Code for Property-Based Searching for
Documents
…
SearchScope search = new SearchScope(os);
SearchSQL sql = new SearchSQL("select * from Document
where Creator='administrator'");
DocumentSet documents = (DocumentSet)
search.fetchObjects(sql,Integer.getInteger("50"),
null,Boolean.valueOf(true));
Document doc;
Iterator it = documents.iterator();
while (it.hasNext())
{
doc = (Document)it.next();
System.out.println("document="+
doc.get_Name());
}
22
Instructor Notes:
None
Rev 1.0
22
Searches
Searches
Search for Objects
Sample Code for Retrieving the Properties for the
Searched Documents
…
RepositoryRowSet rowSet = search.fetchRows(sql,
Integer.getInteger("50"), null,
Boolean.valueOf(true));
Iterator itRow = rowSet.iterator();
RepositoryRow row;
while (itRow.hasNext()){
row = (RepositoryRow)itRow.next();
com.filenet.api.property.Properties props =
row.getProperties();
Iterator itProp = props.iterator();
com.filenet.api.property.Property prop;
while (itProp.hasNext()){
prop = (com.filenet.api.property.Property)
itProp.next();
System.out.println(prop.getPropertyName());
}
23
Instructor Notes:
None
Rev 1.0
23
Searches
Searches
Search for Objects
Steps to Search for Objects Across the Object Stores
1. Get the object stores and assign it to an array
ObjectStore objectStores[] = new
ObjectStore[2];
objectStores[0] = os1;
objectStores[1] = os2;
2. Instantiate a SearchScope object with the Objectstores to
search from
new SearchScope(…)
3. Instantiate a SearchSQL object with the SQL statement.
new SearchSQL(…)
4. Retrieve the objects.
searchScope.fetchObjects(…)
24
Instructor Notes:
None
Rev 1.0
24
Searches
Searches
Search for Objects
Sample Code to Search Across Object Stores
…
ObjectStore objectStores[] = new ObjectStore[2];
objectStores[0] = os1;
objectStores[1] = os2;
PropertyFilter pf = new PropertyFilter();
pf.addIncludeProperty(new
FilterElement(Integer.getInteger("2"), null,
Boolean.valueOf (true), "Name"));
SearchScope search = new SearchScope(objectStores,
MergeMode.UNION);
SearchSQL sql = new SearchSQL("select * from Document d
where Creator='administrator' AND NOT (IsClass(d,
CodeModule))");
DocumentSet documents = (DocumentSet)search.fetchObjects
(sql,Integer.getInteger("50"),pf, Boolean.valueOf(true));
Document doc;
Iterator it = documents.iterator();
while (it.hasNext()){
doc = (Document)it.next();
System.out.println("document="+ doc.get_Name());
}
25
Instructor Notes:
None
Rev 1.0
25
Searches
Searches
Search for Objects
Activities
In your workbook, see
y Lesson: Search for Objects
Complete these activities:
y Property-Based Searching for Documents
y Search for Documents Across Object Stores
26
Instructor Notes:
None
Rev 1.0
26
Searches
Searches
Module: Searches
Lesson:
Build SQL Statements
27
Instructor Notes:
None
Rev 1.0
27
Searches
Searches
Build SQL Statements
Scenario
y Your application requires a feature that searches for
Document objects on the given Content Engine. You would
like to use the IBM FileNet P8 capabilities for constructing
SQL statements to run the search. You, as the
programmer, will write code to accomplish this.
28
Instructor Notes:
None
Rev 1.0
28
Searches
Searches
Build SQL Statements
Lesson Objectives
In this lesson, you will
y Write code to build an SQL statement and search for
documents on Content Engine.
29
Instructor Notes:
None
Rev 1.0
29
Searches
Searches
Build SQL Statements
Java API Methods Presented in This Lesson
searchSQL.setSelectList (…)
searchSQL.setFromClauseInitialValue (…)
searchSQL.setWhereClause (…)
Other Related Methods:
y
y
y
y
searchSQL.setOrderByClause (…)
searchSQL.setFromClauseAdditionalJoin (…)
searchSQL.setQueryString(…)
searchSQL.setMaxRecords (…)
30
Instructor Notes:
None
Rev 1.0
30
Searches
Searches
Build SQL Statements
Steps to Build a SQL Statement
1. Create a SearchSQL object.
SearchSQL sql = new SearchSQL()
2. Specify the maximum number of records to be returned
(optional).
sql.setMaxRecords(100)
3. Specify the SELECT list.
sql.setSelectList(…)
4. Specify the FROM clause.
sql.setFromClauseInitialValue(…)
5. Specify the WHERE clause.
sql.setWhereClause(…)
31
Instructor Notes:
None
Rev 1.0
31
Searches
Searches
Build SQL Statements
Folder Operators
INFOLDER
y Matches object contained within specified folder.
y Folder ID
y Full path name
INSUBFOLDER
y Can be used only on subfolders that have the
Folder.Parent property set to the parent of the folder.
32
ADDITIONAL INFORMATION
The INFOLDER operator matches an object contained within a specified folder. The left-hand operand
specifies an object-valued property or an expression that results in a single object value. The right-hand
operand identifies the folder in one of the following forms:
•The folder ID
•The full path name of the folder
INSUBFOLDER can be used only on subfolders that have the Folder.Parent property set to the parent of the
folder (direct containment). The INSUBFOLDER operator will not recognize a subfolder linked to a parent by
referential containment (a ReferentialContainmentRelationship object having the
ReferentialContainmentRelationship.Tail property equal to the subfolder and the
ReferentialContainmentRelationship.Head property equal to the parent folder).
Note: Use of the INSUBFOLDER operator results in a complex query that can take a long time to execute.
Before deploying a solution that uses an INSUBFOLDER search across a large number of folders and
containees, ensure that this search behaves well on a large database and is properly optimized. The
database is not capable of properly optimizing all queries.
Instructor Notes:
None
Rev 1.0
32
Searches
Searches
Build SQL Statements
IN Operator
For multivalued properties (LIST cardinality)
value IN (constant1, constant2, …)
value IN (SELECT someproperty FROM …)
value IN
33
ADDITIONAL INFORMATION
The following formats are used for the IN operator:
•value IN listproperty
Where value is either a property name or a constant (<property_spec> | <literal>), and listproperty is a
property name (<property_spec>) of a property that has the cardinality of LIST. This format is used to search
a property that is of cardinality LIST. If the list has a value equal to value, the expression is true. Note that
you cannot use "value = listproperty" to compare a property of type LIST to a value. The IN operator must be
used.
•value IN (constant1, constant2, constant3,…)
Where constant1, constant2, constant3 are constants. This format is used to determine if value is equal to
one of the constants in the list. Note that when multiple items are enclosed in parentheses, the items must
be constants.
•value IN (SELECT someproperty FROM …)
This format is used to determine if value is one of the results returned by the subquery. Note that the
subquery must select only one property.
Instructor Notes:
None
Rev 1.0
33
Searches
Searches
Build SQL Statements
OBJECT Function
Create object constant to compare with an objectvalue property.
SELECT … FROM Folder WHERE Parent =
OBJECT('/root/sub1/sub1a')
34
ADDITIONAL INFORMATION
The Object function provides a means to create the effect of an object constant, which can then be
compared to an object-valued property or expression.
There are two logical forms of the Object function, one of which takes an argument of type GUID (Id), which
can either be a constant or a GUID-valued property, and the other of which takes a string argument, which
can be one of the following:
•The GUID constant (Id) of the object
•For Folder objects, the full path name of the folder
A <property_spec> for a property of datatype Id. An Object function can be used to compare objects to IDs,
which can be especially useful in joins
Instructor Notes:
None
Rev 1.0
34
Searches
Searches
Build SQL Statements
Class Functions
IsClass
INCLUDESUBCLASSES
EXCLUDESUBCLASSES
SELECT … FROM Document D WHERE
IsClass(D,DocSubclass1) OR IsClass(D,DocSubclass2)
SELECT … FROM Document WITH INCLUDESUBCLASSES
WHERE DocumentTitle = 'MyDoc'
SELECT … FROM Document WITH EXCLUDESUBCLASSES
WHERE DocumentTitle = 'MyDoc'
35
ADDITIONAL INFORMATION
The INCLUDESUBCLASSES and EXCLUDESUBCLASSES operators, along with ISCLASS, are used to
limit results to specific classes or class hierarchies. INCLUDESUBCLASSES is the default. SQL query
examples are shown below.
The IsClass function acts as a filter for finding specific classes. The IsClass function is useful when querying
base classes WITH INCLUDESUBCLASSES, and the results must include objects that belong to one or
more particular subclasses of the base class.
Instructor Notes:
None
Rev 1.0
35
Searches
Searches
Build SQL Statements
Available SearchSQL Helper Class Methods
Methods to assist in building valid SQL statements:
y
y
y
y
y
y
y
setSelectList(…)
setFromClauseInitialValue(…)
setWhereClause(…)
setOrderByClause(…)
setQueryString(…)
setContainsRestriction(…)
setFreeTextRestriction(…)
36
ADDITIONAL INFORMATION
SQL statements need to follow the FileNet standard, which generally conform to SQL-92, with extensions for
FileNet-specific constructs. See SQL Syntax Reference for a complete description.
The SearchSQL helper methods are supplied for assistance in building SQL statements and cannot provide
the level of specification you can achieve with an independently constructed statement.
However, in a development environment, you can use the helper methods for initial construction of the SQL
statement, and then use the SearchSQL.toString() method to get the SQL statement string and manually
refine the SQL statement.
Instructor Notes:
None
Rev 1.0
36
Searches
Searches
Build SQL Statements
searchSQL.setSelectList (…)
public void setSelectList(String selectList)
Parameters
y selectList – Specifies a String containing the query SELECT
list.
Notes
y This method sets the SELECT list for the SQL statement to
the string specified.
y This must be called prior to calling
setFromClauseAdditionalJoin.
37
Instructor Notes:
None.
Rev 1.0
37
Searches
Searches
Build SQL Statements
searchSQL.setFromClauseInitialValue (…)
public void setFromClauseInitialValue(
String symbolicClassName,
String aliasName
boolean includeSubclasses null)
Parameters
y symbolicClassName - A String containing the symbolic name of the
class.
y aliasName - A String containing the alias name of the class. This can
be null.
y includeSubclasses - True if the FROM clause includes any subclasses
of the class specified insymbolicClassName .
Notes
y This method sets the first class to be used in the FROM clause for the
statement.
38
ADDITIONAL INFORMATION
Alias names cannot be used when EngineObject objects are to be returned by the query operation.
Instructor Notes:
None
Rev 1.0
38
Searches
Searches
Build SQL Statements
searchSQL.setWhereClause (…)
public void setWhereClause( String whereClause)
Parameters
y whereClause - A String containing the WHERE clause to use.
Notes
y This method sets the WHERE clause to be used for the SQL
statement to the specified string.
39
Instructor Notes:
None
Rev 1.0
39
Searches
Searches
Build SQL Statements
searchSQL.setOrderByClause (…)
public void setOrderByClause(String orderBy)
Parameters
y orderBy - A String containing the property or properties to
use for the ORDER BY clause.
y You can specify multiple property names separated by
commas.
Notes
y Sets the ORDER BY clause to be used for the SQL statement
to the specified string.
40
Instructor Notes:
None.
Rev 1.0
40
Searches
Searches
Build SQL Statements
searchSQL.setFromClauseAdditionalJoin (…)
public void setFromClauseAdditionalJoin(
JoinOperator joinOperator,
String symbolicClassName, String aliasName,
String joinVar1,JoinComparison joinComparison,
String joinVar2, boolean includeSubclasses )
Parameters
y joinOperator - Specifies the type of join to use for the additional
class.
y joinComparison - Specifies the comparison to use for the
constituents of the ON clause (joinVar1 and joinVar2).
Notes
y Adds another class to the FROM clause used in the SQL statement
Parameters.
41
ADDITIONAL INFORMATION
JoinOperator - INNER, LEFT OUTER, RIGHT OUTER, FULL OUTER
JoinComparison - Specifies the operation to use when comparing the constituents of a SQL join operation.
•EQUAL, GREATER_THAN
•GREATER_THAN_EQUAL_TO
•LESS_THAN
•LESS_THAN_EQUAL_TO
•NOT_EQUAL
Instructor Notes:
None
Rev 1.0
41
Searches
Searches
Build SQL Statements
searchSQL.setQueryString (…)
public void setQueryString(String queryString)
Parameters
y queryString - A String containing the SQL statement to use.
Notes
y Specifies the complete SQL statement. This method cannot be used
in conjunction with any other set method on this class.
42
ADDITIONAL INFORMATION
Any values set by calling another SearchSQL set method (such as, setMaxRecords) and then calling this
method will overwrite or nullify the value initially set.
No SQL validation is performed on the specified string.
Instructor Notes:
None
Rev 1.0
42
Searches
Searches
Build SQL Statements
searchSQL.setMaxRecords (…)
public void setMaxRecords(int maxRecords)
Parameters
y maxRecords - An integer specifying the maximum number of rows
to be returned.
Notes
y This method sets the maximum number of rows that can be
returned in the result set.
43
ADDITIONAL INFORMATION
When unspecified, all records that satisfy the query will be returned, subject to the limit of
ServerCacheConfiguration property NonPagedQueryMaxSize.
Instructor Notes:
None
Rev 1.0
43
Searches
Searches
Build SQL Statements
Sample Code to Construct SQL Statements
…
SearchSQL sql = new SearchSQL();
sql.setSelectList("*");
sql.setFromClauseInitialValue("Document", "d",true);
sql.setWhereClause("Creator='administrator' AND NOT
(IsClass(d, CodeModule))");
…
Resulting SQL statement from the above code:
"select * from Document d where
Creator='administrator’ AND NOT (IsClass(d,
CodeModule))"
44
Instructor Notes:
None
Rev 1.0
44
Searches
Searches
Build SQL Statements
Activities
In your workbook, see
y Lesson: Build SQL Statements
Complete these activities:
y Construct SQL Statements
45
Instructor Notes:
None
Rev 1.0
45
Searches
Searches
Rev 1.0
46
Searches
Searches
Module: Searches
Lesson:
Content-Based Retrieval
47
Instructor Notes:
None
Rev 1.0
47
Searches
Searches
Content-Based Retrieval
Lesson Objectives
In this lesson, you will
y Write code to search for documents on Content Engine
based on content-based retrieval.
48
Instructor Notes:
None
Rev 1.0
48
Searches
Searches
Content-Based Retrieval
Java API Methods Presented in This Lesson
searchSQL.setSelectList (…)
searchSQL.setFromClauseInitialValue (…)
searchSQL.setWhereClause (…)
Other Related Methods:
y
y
y
y
searchSQL.setOrderByClause (…)
searchSQL.setFromClauseAdditionalJoin (…)
searchSQL.setQueryString(…)
searchSQL.setMaxRecords (…)
49
Instructor Notes:
None
Rev 1.0
49
Searches
Searches
Content-Based Retrieval
Content Searches
A content (full-text) search
y Returns documents that contain the text you specify.
y Includes in the query words or phrases that might be stored
in objects or in their string properties.
y Is initiated by either a CONTAINS or a FREETEXT operator
in the SQL statement contained in SearchSQL.
To do a Content Search, you must
y Enable content-based retrieval (CBR) for the object and its
string properties.
y Index the documents.
50
ADDITIONAL INFORMATION
While the CONTAINS operator can search content in all properties or in a single property, the FREETEXT
operator can search content only in all properties. Note that attempting to specify a property name for
FREETEXT generates an exception.
Instructor Notes:
None
Rev 1.0
50
Searches
Searches
Content-Based Retrieval
Full-Text Joins
SELECT … FROM Document D INNER JOIN
ContentSearch CS ON D.This=CS.QueriedObject
WHERE CONTAINS(*,'text') AND D.Creator = 'Frank'
SELECT … FROM Document D LEFT OUTER JOIN
VerityContentSearch CS ON
D.This=CS.QueriedObject WHERE CONTAINS(*,'text')
OR D.Creator = 'Frank'
51
ADDITIONAL INFORMATION
Whenever a CONTAINS or FREETEXT clause is used, a join is performed on the (internal) ContentSearch
or VerityContentSearch classes.
Note: Instances of the ContentSearch or VerityContentSearch classes cannot be retrieved. However, the
properties of these classes are defined in the metadata for a RepositoryRow object.
The join is necessary because when a query with a full-text search is executed, the full-text search is done
first, and then the data from the full-text search is copied to a temporary database table that is referenced by
either the ContentSearch or the VerityContentSearch class name (both behave identically). The remainder of
the search statement is then executed against the repository, joining to this temporary table to access the
full-text search data.
Instructor Notes:
None
Rev 1.0
51
Searches
Searches
Content-Based Retrieval
CONTAINS Function
Search for precise or fuzzy matches
Word or phrase
Prefix of work or phrase
Word near another word
Inflected word
SELECT … FROM Document D INNER JOIN
ContentSearch CS ON D.This=CS.QueriedObject
WHERE CONTAINS(*,'text')
52
ADDITIONAL INFORMATION
Use CONTAINS to search for precise or fuzzy (less precise) matches for the following types of text:
•A word or phrase, or a prefix of a word or phrase
•A word near another word
•A word that is the inflected form of another (For example, drive is the root for the inflected forms drives,
drove, driving, and driven.)
•A word that has a higher designated weighting than another word
The first parameter in the CONTAINS function identifies the property or pseudo-property to which the
content filter is to be applied, and the second parameter specifies the filter expression.
Instructor Notes:
None
Rev 1.0
52
Searches
Searches
Content-Based Retrieval
searchSQL.setContainsRestriction (…)
public void setContainsRestriction(
String symbolicClassName,
String searchExpression)
Parameters
y symbolicClassName - A String containing the symbolic name
of the class.
y searchExpression - A String containing the search text to
use for the CONTAINS function.
Notes
y This method restricts the query to return only items in which
the text in the content element or elements matches the
specified string.
53
ADDITIONAL INFORMATION
The CONTAINS function can perform the search on CBR-enabled properties for the supported content
elements in any of the following ways:
•Search a single property
•Search all properties within a specified zone
•Search all properties
Instructor Notes:
None
Rev 1.0
53
Searches
Searches
Content-Based Retrieval
FREETEXT Function
Search for document content or string property.
Match meaning, not exact wording.
54
ADDITIONAL INFORMATION
Use FREETEXT to search the text of the string property or document content for values that match the
meaning but not the exact wording in the filter expression. When using FREETEXT, the full-text query
engine internally breaks the filter expression into a number of search terms, assigns each term a weight, and
then finds the matches.
Instructor Notes:
None
Rev 1.0
54
Searches
Searches
Content-Based Retrieval
searchSQL.setFreetextRestriction (…)
public void setFreetextRestriction(
String symbolicClassName,
String searchExpression)
Parameters
y symbolicClassName - A String containing the symbolic name
of the class.
y searchExpression - A String containing the search text to
use for the FREETEXT function.
Notes
y Restricts the query to return only items in which the text in
the content elements matches the specified string.
55
ADDITIONAL INFORMATION
This method uses the FREETEXT function for CBR queries. The FREETEXT function searches all content
on all CBR-enabled properties on the supported content elements. To search content on a single CBRenabled property, use setContainsRestriction.
Instructor Notes:
None
Rev 1.0
55
Searches
Searches
Content-Based Retrieval
Common (Stop) Words
Search engine does not look for common words.
Stop words are not added to the collection when a
document is indexed.
Examples: a, about, above, be, because, few, for,
from, and so forth
56
ADDITIONAL INFORMATION
By default, the search engine does not look for certain common words, called Stop Words. When the index
is built, the stop words are not added to the collection so they can never be found.
If one or more words in your search requires a stop word, such as when you use the All or Near modifiers or
the AND operator between lines, the search will fail because these words never appear in the index. See
Autonomy K2 Stop Words for a list of these words.
Instructor Notes:
None
Rev 1.0
56
Searches
Searches
Content-Based Retrieval
Modifiers
Modifier
Desired Search Condition
None
Search for phrase with the exact spelling and casesensitivity
Near
Search for words located near each other
Sentence
Search for words located in the same sentence
Paragraph
Search for words located in the same paragraph
Any
Search for any of the specified words or phrases
All
Search for all of the specified words or phrases
In Zone
Search for one or more words in an HTML or XML tag
57
ADDITIONAL INFORMATION
Simply entering one word as your search criteria causes the search engine to find various forms of that word
(stemmed variations). You can turn off stemming and require matching capitalization using double quotation
marks, look for patterns using the asterisk (*) as a wildcard character, or exclude a word using the
exclamation point (!) at the beginning.
When you enter two or more words, you can specify a relationship between those words.
Your object stores can be configured to use either Near or Sentence and Paragraph (Near is the default). If
your site uses Near, Sentence and Paragraph act like Near. If the specified object stores use Sentence and
Paragraph, then Near operates like Sentence and Paragraph. The words will qualify if they do not cross a
sentence or paragraph boundary.
By default, Near is defined as words within 1000 words of each other.
When you choose In Zone, a dialog box requests the name of the XML/HTML Zone name (often called a
tag). You need to know what tags are used in your documents to take advantage of the faster search in only
that part of the document.
The search engine sees hyphenated words as two separate words.
Instructor Notes:
None
Rev 1.0
57
Searches
Searches
Content-Based Retrieval
Autonomy K2 Query Language
Autonomy K2 query language can be entered in the
Words/Phrases field
y Choose the query language as the modifier.
The text will be passed to the Autonomy K2 search
engine without checking or modification.
58
Instructor Notes:
None
Rev 1.0
58
Searches
Searches
Content-Based Retrieval
Query Option
TimeLimit
y The time limit for the query, in seconds.
FullTextRowLimit
y Indicates the number of rows to pull from the full text index
prior to executing the remainder of the query.
y If a value is not supplied, the value of the
ObjectStore.FullTextRowDefault property (stored in the
GCD) is used.
59
ADDITIONAL INFORMATION
FullTextRowLimit
There is one row for each content element that is indexable, plus one more row for all CBR-enabled strings
of an object. Data from the full-text index is copied to a temporary table, and that table is then joined with the
remainder of the object store database to execute the query.
The FullTextRowLimit option enables you to control the maximum number of rows pulled from the full text
index.
For example, suppose a query has the clause "WHERE color = 'red' and CONTAINS(*, 'blue')". This query
might have a thousand rows that match "CONTAINS(*, 'blue')", but only ten rows that match "color = 'red'"
and "CONTAINS(*, 'blue')". If FullTextRowLimit is set to 500, then only 500 rows are pulled from the full text
index and written to the temporary table. Even though there are only ten rows that match the complete
WHERE clause, not all ten rows might be found because not all ten are necessarily in the 500 rows fetched
from the full text index.
If a value for FullTextRowLimit is supplied and this value is greater than the value of
ObjectStore.FullTextRowMax, then the value of ObjectStore.FullTextRowMax is used instead. The
FullTextRowMax property is present on the ObjectStore class to prevent queries from using too much
processing time and pulling an inordinate number of rows from the full-text index.
Instructor Notes:
None
Rev 1.0
59
Searches
Searches
Content-Based Retrieval
Sample Code for Content-Based Document Searching
…
SearchScope search = new SearchScope(os);
String mySQLString = "SELECT DocumentTitle, Name
FROM Document d INNER JOIN VerityContentSearch v
ON v.QueriedObject = d.This WHERE
d.IsCurrentVersion = TRUE AND CONTAINS(d.*,'" +
keyWord + "')";
SearchSQL sql = new SearchSQL(mySQLString);
DocumentSet documents = (DocumentSet)
search.fetchObjects(sql,Integer.getInteger("50"),
null, Boolean.valueOf(true));
com.filenet.api.core.Document doc;
Iterator it = documents.iterator();
while (it.hasNext()){
doc = (Document)it.next();
System.out.println("document="+ doc.get_Name());
}
…
60
Instructor Notes:
None
Rev 1.0
60
Searches
Searches
Content-Based Retrieval
Activities
In your workbook, see
y Lesson: Content-Based Retrieval
Complete this activity:
y Content-Based Searching for Documents
61
Instructor Notes:
None
Rev 1.0
61
Searches
Searches
Rev 1.0
62
Searches
8
8
Security
Java API Programmer
Security
IBM FileNet Content Manager
Instructor Notes:
None
Rev 1.0
Security
1
Security
Rev 1.0
Security
2
Security
Security
This module consists of these lessons:
y
y
y
y
Retrieve Object Permissions
Set Object Permissions
Apply a Security Template
Retrieve Users and Groups
3
Instructor Notes:
None
Rev 1.0
Security
3
Security
Rev 1.0
Security
4
Security
Module: Security
Lesson:
Retrieve Object Permissions
5
Instructor Notes:
None
Rev 1.0
Security
5
Security
Retrieve Object Permissions
Scenario 1
y As the programmer, you need to write code to determine
the security permissions on folders so that you can set the
permissions on the documents within these folders to be
the same as the folder they are in.
Scenario 2
y Administrators want to be able to see what security
permissions a particular folder has without leaving the
application. As the programmer, you will add this
functionality to the application.
6
Instructor Notes:
None
Rev 1.0
Security
6
Security
Retrieve Object Permissions
Lesson Objectives
In this lesson, you will:
y Write code to retrieve permissions on a Content Engine
object
7
Instructor Notes:
None
Rev 1.0
Security
7
Security
Retrieve Object Permissions
Java API Methods Presented in This Lesson
containable.get_Permissions()
accessPermission.get_GranteeName()
accessPermission.get_GranteeType()
accessPermission.get_PermissionSource()
accessPermission.get_AccessMask()
accessLevel.getInstanceFromInt(…)
accessPermission.get_AccessType()
accessPermission.get_InheritableDepth()
8
ADDITIONAL INFORMATION
Some of these methods are inherited from Permission interface
Instructor Notes:
None
Rev 1.0
Security
8
Security
Retrieve Object Permissions
Object-level Security
Authorization:
y Does the requestor have permission to do what he/she is
asking the specified object to do?
Securable vs. non-securable objects
y Most objects are secured by their own set of access rights
– Example: a document
y Some objects depend on the access rights of the associated
object
– Example: the content element associated with a document
Security grantees are specified on each object
y Also known as “security principal”
y Typically a user or group
9
HELP PATH
FileNet P8 Documentation > FileNet P8 Administration > Enterprise-wide Administration > FileNet P8
Security
ADDITIONAL INFORMATION
• Assets managed in the Content Engine are protected and can be seen or modified only according to a
user's access rights.
• Each Content Engine server object has its own security, which controls a user's (or group's) access to that
object.
• Only securable objects have permissions that can be independently set. Non-securable objects are not
really non-securable; they are simply dependent on their parent object for their access rights (that is, they
are secured via the parent object’s permissions).
• A document with multiple content elements illustrates that you cannot independently control security on the
content element itself, unlike annotations, which are independently securable.
• A grantee is either an individual user or a group of users. A user can be a member of zero, one, or more
groups, and a group can contain zero, one, or more subgroups. A user account is defined on the Content
Engine server using tools provided by the directory service, for example, Microsoft Active Directory or Sun
ONE Directory Services.
Instructor Notes:
None
Rev 1.0
Security
9
Security
Retrieve Object Permissions
Access Control Objects and Properties
Access rights for an object are determined by Access Control
List (ACL)
y Made up of one or more Access Control Entries (ACE)
y An ACE is represented by a Permission object
y An ACL is a Permissions collection (represents the full set of
ACEs)
Each ACE specifies:
y A security grantee (a user or group)
y A permission source (Example: Direct or Security Policy)
y “Allow” or “Deny” access type
y Access level
– Examples: “View Content”, “Full Control”, “Custom”
y Access rights (a more granular access level)
– Example: “Change state”
y Apply To
– Example: this object only or object and immediate children
10
HELP PATH
FileNet P8 Documentation > FileNet P8 Administration > Enterprise-wide Administration > FileNet P8
Security > Access rights
ADDITIONAL INFORMATION
•Each ACE is represented by a Permission object, which establishes the access granted to a user or
group (the "grantee"), and contains a reference to the user or group being assigned the permission.
• A Permissions collection represents the full set of access control entries (ACEs) associated with an
object and forms the object's Access Control List (ACL).
Instructor Notes:
Emphasize the fact that an ACE corresponds to the API’s concept of a “Permission”, and that an ACL is a Permissions
collection.
DEMO
1. Launch FileNet Enterprise Manager and navigate to a document.
2. Select Properties and Security tab
3. Show the sub-tabs and values for Source, Level, Apply to, and Type.
Rev 1.0
Security
10
Security
Retrieve Object Permissions
Permission Sources
Default permissions are from object’s class description
Indirect permissions are from a security policy or a
security parent
Direct permissions are directly set on the object
y They override default and indirect security
Identify permission sources with:
Permission.get_PermissionSource()
y PermissionSource.SOURCE_DIRECT
y PermissionSource.SOURCE_DEFAULT
y PermissionSource.SOURCE_TEMPLATE
y PermissionSource.SOURCE_PARENT
11
HELP PATH
FileNet P8 Documentation > FileNet P8 Administration > Enterprise-wide Administration > FileNet P8
Security
FileNet P8 Documentation>Developer Help>Content Engine Development>Java and .NET Developer’s
Guide > Security > Concepts
ADDITIONAL INFORMATION
A newly-created object acquires its default permissions directly from its class.
The ClassDescription interface's get_DefaultInstancePermissions method returns the default permissions for
an object belonging to the class. You can use this method to determine if the class's permissions are
appropriate for your application or to display the default permissions in a user interface and allow the user to
modify the permissions when you are creating a new object of this class.
An object can also acquire permissions through inheritance and from a security policy.
Instructor Notes:
None
Rev 1.0
Security
11
Security
Retrieve Object Permissions
Steps to Get Object Permissions
1. Get the desired object from the object store
Factory.Folder.fetchInstance(…)
2. Get permissions collection on the object (for example, a folder)
folder.get_Permissions()
3. For each permission in the collection, get grantee name and type
permission.get_GranteeName()
permission.get_GranteeType().toString()
4. For each permission, get the permission source.
accessPermission.get_PermissionSource().toString()
5. For each permission, get access level and type
accessPermission.get_AccessMask()
discretionaryPermission.get_AccessType()
12
Instructor Notes:
None
Rev 1.0
Security
12
Security
Retrieve Object Permissions
containable.get_Permissions()
public AccessPermissionList get_Permissions()
Parameters
y None
Returns
y A Permissions collection containing the basic object permissions
for this object
Notes
y The user must have Read permission on the object's security to
retrieve the object's permissions
– AccessLevel.VIEW or
– AccesRight.READ_ACL
y This method filters out Access Control Entries (ACEs) that
correspond to deleted grantees (users or groups).
13
Instructor Notes:
None
Rev 1.0
Security
13
Security
Retrieve Object Permissions
accessPermission.get_GranteeName()
public String get_GranteeName()
Parameters
y None
Returns
y A string representing the name of the grantee associated with this
particular permission item
Notes
y The returned string is the displayable user or group name
(Principal Name) that can appear in a user interface display.
14
Instructor Notes:
None
Rev 1.0
Security
14
Security
Retrieve Object Permissions
accessPermission.get_GranteeType()
public SecurityPrincipalType get_GranteeType()
Parameters
y None
Returns
y The object type of the permission grantee
– SecurityPrincipalType.USER
– SecurityPrincipalType.GROUP
15
Instructor Notes:
None
Rev 1.0
Security
15
Security
Retrieve Object Permissions
accessPermission.get_PermissionSource()
public PermissionSource get_PermissionSource()
Parameters
y None
Returns
y The source of this permission
Notes
y
y
y
y
y
0 = PermissionSource. SOURCE_DIRECT
1 = PermissionSource.SOURCE_DEFAULT
2 = PermissionSource.SOURCE_TEMPLATE
3 = PermissionSource.SOURCE_PARENT
4 = PermissionSource.MARKING
16
Instructor Notes:
None
Rev 1.0
Security
16
Security
Retrieve Object Permissions
accessPermission.get_AccessMask()
public Integer get_AccessMask()
Parameters
y None
Returns
y An integer representing the type of permission assigned to a user or
group
17
ADDITIONAL INFORMATION
• The access returned is made up by ORing together all the individual permissions on the object for the
particular grantee.
• Each FileNet P8 access level
- Corresponds to a common combination of FileNet P8 access rights
- Is more convenient to use than the individual access rights
• Example: Access level AccessLevel.READ (0x00020001) includes the access righ
- AccessRight.READ (0x00000001) and
- AccessRight.READ_ACL (0x00020000)
Instructor Notes:
None
Rev 1.0
Security
17
Security
Retrieve Object Permissions
accessPermission.get_AccessType()
public AccessType get_AccessType()
Parameters
y None
Returns
y An integer that indicates whether a user or group is allowed or
denied the associated access
Notes
y 1 = AccessType.ALLOW
y 2 = AccessType.DENY
y This method is inherited from DiscretionaryPermission
interface
18
Instructor Notes:
None
Rev 1.0
Security
18
Security
Retrieve Object Permissions
Sample Code to Get Folder Permissions
…
AccessPermissionList permissions=
folder.get_Permissions();
Iterator it = permissions.iterator();
while (it.hasNext()){
AccessPermission permission =
(AccessPermission)it.next();
System.out.println("Grantee Name=“ +
permission.get_GranteeName());
System.out.println("Grantee Type=" +
permission.get_GranteeType().toString());
System.out.println("Permission Source=" +
permission.get_PermissionSource().toString());
…
19
Instructor Notes:
None
Rev 1.0
Security
19
Security
Retrieve Object Permissions
Sample Code to Get Folder Permissions (cont.)
System.out.println("Access level = " +
AccessLevel.getInstanceFromInt(permission.
get_AccessMask().intValue()).toString());
System.out.println("Access type =" +
permission.get_AccessType().toString());
System.out.println("Inheritable depth=" +
permission.get_InheritableDepth());
}
20
Instructor Notes:
None
Rev 1.0
Security
20
Security
Retrieve Object Permissions
Activities
In your workbook, see:
y Lesson: Retrieve Object Permissions
Complete these activities
y Retrieve Folder Permissions
21
Instructor Notes:
None
Rev 1.0
Security
21
Security
Rev 1.0
Security
22
Security
Module: Security
Lesson:
Set Object Permissions
23
Instructor Notes:
None
Rev 1.0
Security
23
Security
Set Object Permissions
Scenario
y There are a number of older documents in the object store
that do not have the desired security settings. As the
programmer, you will write code to update the security
permissions on these documents so that they are the same
as the folder they are filed in.
24
Instructor Notes:
None
Rev 1.0
Security
24
Security
Set Object Permissions
Lesson Objectives
In this lesson, you will:
y Write code to set permissions on a folder
y Write code to set security parent for a document
25
Instructor Notes:
None
Rev 1.0
Security
25
Security
Set Object Permissions
Java API Methods Presented in This Lesson
Factory.AccessPermission.createInstance(…)
accessPermission.set_GranteeName(…)
accessPermission.set_AccessType(…)
accessPermission.set_InheritableDepth(…)
accessPermission.set_AccessMask(…)
folder.set_Permissions(…)
document.get_Containers()
document.set_SecurityParent(…)
26
Instructor Notes:
None.
Rev 1.0
Security
26
Security
Set Object Permissions
Security Inheritance
An object can inherit permissions from:
y A security parent
y A security policy
y Both
– If conflicts occur, “deny” takes precedence over “allow”.
Inherited parent security example:
y A document inherits permissions from its parent folder.
y Inherited permissions are added to existing permissions
Inherited policy security example:
y A document inherits permissions from an applied policy.
y Inherited permissions are added to existing permissions.
27
Help Paths:
FileNet P8 Documentation > FileNet P8 Administration > Enterprise-wide Administration > FileNet P8
Security > Understanding inheritance
ADDITIONAL INFORMATION
Inherited permissions cannot be directly changed.
To determine if an access right is inherited, call Permission.isInherited().
Instructor Notes:
None.
Rev 1.0
Security
27
Security
Set Object Permissions
Setting Security with a Security Parent
Example: A folder is a security parent for a document
The security parent must be enabled to allow
permissions inheritance
y Security parent may allow inheritance to immediate children or
all children (or no inheritance)
y Inheritance for each permission (ACE) is independently set
The child must also be set to allow permissions to be
inherited from the parent
y Applies to all the parent’s ACEs that are set to allow inheritance
y For documents:
– Use setSecurityParent(…) Java API method or
– Check “Inherit Security from folder” in Enterprise Manager
28
HELP PATH
FileNet P8 Documentation > FileNet P8 Administration > Enterprise-wide Administration > FileNet P8
Security > Understanding inheritance
ADDITIONAL INFORMATION
Adding an item to a folder does not immediately cause the item to inherit the folder’s security. The item must
also have its security parent set after adding it to the folder.
Instructor Notes:
None
Rev 1.0
Security
28
Security
Set Object Permissions
Steps to Set Permissions on a Folder
1.
Create a new Permission object with values for a grantee.
Factory.AccessPermission.createInstance(…)
2.
Set the values for the new permission.
accessPermission.set_GranteeName(…)
accessPermission.set_AccessType(…)
accessPermission.set_InheritableDepth(…)
accessPermission.set_AccessMask(…)
3.
Get the existing Permissions collection from the folder.
4.
Add the Permission object to the collection.
Folder.get_Permissions()
Permissions.add(…)
5.
Apply the new Permissions collection to the folder.
Folder.set_Permissions(…)
6.
Save the changes to the folder.
Folder.save(…)
29
ADDITIONAL INFORMATION
• The Folder.get_Permissions() method was described in the previous lesson.
• The add(…) method is the standard Java method to add an item to a list.
Instructor Notes:
None
Rev 1.0
Security
29
Security
Set Object Permissions
Factory.AccessPermission.createInstance(…)
public static AccessPermission createInstance()
Parameters
y None
Returns
y A object reference to a new instance of this class
Notes
y This method creates a new instance of the AccessPermission class
y The created object is a dependent object
y It is only persisted when its parent object is persisted
30
Instructor Notes:
None
Rev 1.0
Security
30
Security
Set Object Permissions
accessPermission.set_GranteeName()
public void set_GranteeName(String value)
Parameters
y value - distinguished name or short name of the user or group whom an
access permission is granted
Returns
y Nothing
31
Instructor Notes:
None
Rev 1.0
Security
31
Security
Set Object Permissions
accessPermission.set_AccessType(…)
public void set_AccessType(AccessType value)
Parameters
y value - the security access type (Allow or Deny) that a user has for
a given AccessPermission object
Returns
y Nothing
32
Instructor Notes:
None
Rev 1.0
Security
32
Security
Set Object Permissions
accessPermission.set_InheritableDepth(…)
Public void set_InheritableDepth (Integer value)
Parameters
y value - specify the maximum depth to which a permission (ACL)
can be inherited
Returns
y Nothing
Notes
y As the ACL gets inherited in a tree of objects, the value is
decremented
y Values allowed:
– 0 - No inheritance
– 1 - Immediate children only.
– -1 - All children (infinite levels deep)
33
Instructor Notes:
None
Rev 1.0
Security
33
Security
Set Object Permissions
accessPermission.set_AccessMask()
public void set_AccessMask(Integer value)
Parameters
y value - bitmask combining bit values representing the security
access rights granted on a given object
Returns
y Nothing
34
Instructor Notes:
None
Rev 1.0
Security
34
Security
Set Object Permissions
folder.set_Permissions(…)
public void set_Permissions(AccessPermissionList
value)
Parameters
y value - Specify a collection of AccessPermission objects in a
AccessPermissionList object
Returns
y Nothing
35
Instructor Notes:
None
Rev 1.0
Security
35
Security
Set Object Permissions
Sample Code to Set Folder Permissions
…
AccessPermission permission =
Factory.AccessPermission.createInstance();
permission.set_GranteeName("MAG_Managers");
permission.set_AccessType(AccessType.ALLOW);
permission.set_InheritableDepth(new Integer(-1));
permission.set_AccessMask(new Integer
(AccessLevel.FULL_CONTROL_FOLDER_AS_INT));
permissions.add(permission);
AccessPermissionList permissions =
folder.get_Permissions();
folder.set_Permissions(permissions);
folder.save(RefreshMode.REFRESH);
36
Instructor Notes:
None
Rev 1.0
Security
36
Security
Set Object Permissions
Steps to Set a Document’s Security Parent
1. Get the document object.
Factory.Document.fetchInstance(…)
2. Get the containers of the document.
document.get_Containers(…)
3. Set the security parent of the document.
document.set_SecurityParent(…)
4. Save the changes to the document.
document.save(…)
37
Instructor Notes:
None
Rev 1.0
Security
37
Security
Set Object Permissions
Document.get_Containers()
public ReferentialContainmentRelationshipSet
get_Containers()
Parameters
y None
Returns
y The ReferentialContainmentRelationship objects collection that
identify the containers of this object
38
Instructor Notes:
None
Rev 1.0
Security
38
Security
Set Object Permissions
Document.set_SecurityParent(…)
public void set_SecurityParent
(ReferentialContainmentRelationship value)
Parameters
y value — Specifies the object from which this object inherits security
Returns
y Nothing
Notes
y If this ContainableObject object is not filed in the specified folder,
then this method also files the object into the specified folder.
y If this object already has a security parent, then the existing security
parent is replaced by the security parent specified in the folder
parameter, but the object remains filed in the original folder.
39
Instructor Notes:
None
Rev 1.0
Security
39
Security
Set Object Permissions
Sample Code to Set a Document’s Security
Parent
ReferentialContainmentRelationshipSet rels =
document.get_Containers();
ReferentialContainmentRelationship rel = null;
Iterator it = rels.iterator();
while (it.hasNext())
rel =(ReferentialContainmentRelationship)it.next();
document.set_SecurityParent(rel);
document.save(RefreshMode.REFRESH);
40
Instructor Notes:
None
Rev 1.0
Security
40
Security
Set Object Permissions
Activities
In your workbook, see:
y Lesson : Set Object Permissions
Complete these activities
y Set Permissions on a Folder
y Set Security Parent for a Document
41
Instructor Notes:
None
Rev 1.0
Security
41
Security
Rev 1.0
Security
42
Security
Module: Security
Lesson:
Apply a Security Template
43
Instructor Notes:
None
Rev 1.0
Security
43
Security
Apply a Security Template
Use Case
y New security measures are being put in place for the
application. A particular folder has already been set as the
security parent for all the documents filed in it, and all those
documents must have the new security applied. As the
programmer, you will write code to apply a security
template to the folder so that it and all the documents within
it have the new security applied.
44
Instructor Notes:
None
Rev 1.0
Security
44
Security
Apply a Security Template
Lesson Objectives
In this lesson, you will:
y Create a simple security policy
y Write code to apply a security template to a folder
45
Instructor Notes:
None
Rev 1.0
Security
45
Security
Apply a Security Template
Java API Methods Presented in This Lesson
objectStore.get_SecurityPolicies()
securityPolicy.get_SecurityTemplates()
securityTemplate.get_DisplayName()
securityTemplate.get_ApplyStateID()
folder.applySecurityTemplate(…)
46
Instructor Notes:
None
Rev 1.0
Security
46
Security
Apply a Security Template
Security Policies and Templates
Used for managing object security
y Can be applied to a Document, Custom Object, or Folder
Security policies consist of one or more security
templates
y Each security template contains a set of access rights to be
applied
Security templates can:
y Override “direct” object security
or
y Add to existing object security
47
HELP PATH
FileNet P8 Documentation > FileNet P8 Administration > Enterprise-wide Administration > FileNet P8
Security > Authorization > Security policies
ADDITIONAL INFORMATION
• Permissions on an object that originate from a security policy will appear on the object's ACL with a Source
type of "Template"
• Applying a template that contains no permissions to an object will have the effect of removing any existing
permissions on that object that were previously applied by a security policy.
Instructor Notes:
None
Rev 1.0
Security
47
Security
Apply a Security Template
Types of Security Templates
Versioning security templates
y Automatically applied to a versionable object as it goes
through version state changes
y Four possible out-of-the-box template names:
– Released
– Reservation
– In process
– Superseded
Application security templates
y Must be explicitly applied to an object programmatically
y Can apply a list of permissions to an object, according to
application logic
y Can be named whatever you want
48
HELP PATH
FileNet P8 Documentation > FileNet P8 Administration > Enterprise-wide Administration > FileNet P8
Security > Authorization > Security policies > About templates
Instructor Notes:
None
Rev 1.0
Security
48
Security
Apply a Security Template
Creating a Security Template
Security templates can be created using:
y Enterprise Manager
y Workplace (Advanced Author Tools)
To create a security template:
1.
2.
3.
4.
Create a security policy.
Add a security template to it.
Add the individual access rights to the template.
Repeat steps 2 to 3 to add additional templates.
49
Instructor Notes:
DEMO
Create a simple security template through Enterprise Manager. Show the pre-defined template options for the
versioning states.
Rev 1.0
Security
49
Security
Apply a Security Template
Steps to Apply a Security Template
To apply a security template:
1. Apply a security policy to the object
–By default for the class
–Or programmatically
2. Assign a specific security template from the policy.
50
HELP PATH
FileNet P8 Documentation > FileNet P8 Administration > Enterprise-wide Administration > FileNet P8
Security > Authorization > Security policies
ADDITIONAL INFORMATION
Security policies may be assigned to new instances of a class if the class is set up to have the security
policy as the default. In that case, the default security policy is automatically associated with the object
instance at the time of creation (unless the default is explicitly overridden).
Instructor Notes:
None
Rev 1.0
Security
50
Security
Apply a Security Template
Steps to Apply a Security Template to a Folder
1. Get the security policies stored in the object store.
objectStore.get_SecurityPolicies()
2. Assign the security policy property to the Properties
collection.
folder.getProperties()
properties.putValue(…)
3. Get the security template from security policy
securityPolicy.get_SecurityTemplates()
4. Apply the security template to the folder.
securityTemplate.get_ApplyStateID()
folder.applySecurityTemplate(…)
51
ADDITIONAL INFORMATION
Applying a security Policy to a Folder object is just like adding a property to an object.
Instructor Notes:
None
Rev 1.0
Security
51
Security
Apply a Security Template
objectStore.get_SecurityPolicies()
public SecurityPolicySet get_SecurityPolicies()
Parameters
y None
Returns
y Collection of the security policies associated with this ObjectStore
object
52
Instructor Notes:
None
Rev 1.0
Security
52
Security
Apply a Security Template
securityPolicy.get_SecurityTemplates()
public SecurityTemplateList get_SecurityTemplates()
Parameters
y None
Returns
y Collection of the security templates associated with a given Security
Policy object
53
Instructor Notes:
None
Rev 1.0
Security
53
Security
Apply a Security Template
securityTemplate.get_ApplyStateID()
public Id get_ApplyStateID()
Parameters
y None
Returns
y Unique identifier for the state to which a given security template
applies
54
Instructor Notes:
None
Rev 1.0
Security
54
Security
Apply a Security Template
folder.applySecurityTemplate(…)
public void applySecurityTemplate(Id applyStateID)
Parameters
y applyStateID - An Id object representing the unique identifier of the
security template to apply
Returns
y Nothing
Notes:
y The specified value for the applyStateID parameter must match the
value of the ApplyStateID property of one of the templates in the
security policy for the object
55
ADDITIONAL INFORMATION
For a versioning security template, the apply state ID can be one of the following:
VersionStatusId.IN_PROCESS
VersionStatusId.RELEASED
VersionStatusId.RESERVATION
VersionStatusId.SUPERSEDED
For an application security template, the apply state ID is defined by your application.
Instructor Notes:
None
Rev 1.0
Security
55
Security
Apply a Security Template
Sample Code to Get and Set a Security Policy
to a Folder
SecurityPolicySet securityPolicies =
store.get_SecurityPolicies();
SecurityPolicy securityPolicy = null;
Iterator it = securityPolicies.iterator();
while (it.hasNext()){
securityPolicy = (SecurityPolicy)it.next();
policyname = securityPolicy.get_Name();
if (policyname.equalsIgnoreCase(policyName))
break;
}
Properties properties = folder.getProperties();
properties.putValue(PropertyNames.SECURITY_POLICY
, securityPolicy);
56
Instructor Notes:
None
Rev 1.0
Security
56
Security
Apply a Security Template
Sample Code to Apply a Security Template to
a Folder
SecurityTemplateList securityTemplates =
securityPolicy.get_SecurityTemplates();
Iterator secTemplateIt = securityTemplates.iterator();
Id securityTempId = null;
while (secTemplateIt.hasNext()){
securityTemplate =(SecurityTemplate)secTemplateIt.next();
securityTemplateName = securityTemplate.get_DisplayName();
if(securityTemplateName.equalsIgnoreCase(templateName)){
securityTempId = securityTemplate.get_ApplyStateID();
System.out.println("apply template id = " +
securityTemplateId);
break;
}
}
folder.applySecurityTemplate(securityTemplateId);
folder.save(RefreshMode.REFRESH);
57
Instructor Notes:
None
Rev 1.0
Security
57
Security
Apply a Security Template
Activities
In your workbook, see:
y Lesson: Apply a Security Template
Complete these activities
y Create a Simple Security Policy
y Apply a Security Template to a Folder
58
Instructor Notes:
None
Rev 1.0
Security
58
Security
Module: Security
Lesson:
Get Users and Groups
59
Instructor Notes:
None
Rev 1.0
Security
59
Security
Get Users and Groups
Use Case
y The application administrators want to find all users and
group names that match a particular pattern, without
leaving the application. As the their programmer, you will
add this functionality to the application.
60
Instructor Notes:
None
Rev 1.0
Security
60
Security
Get Users and Groups
Lesson Objectives
In this lesson, you will:
y Write code to retrieve users and groups names from the
directory service
61
Instructor Notes:
None
Rev 1.0
Security
61
Security
Get Users and Groups
Java API Methods Presented in This Lesson
Factory.EntireNetwork.fetchInstance(…)
EntireNetwork.get_MyRealm()
Realm.findUsers(…)
User.get_DisplayName()
User.get_DistinguishedName()
User.get_ShortName()
Realm.findGroups(…)
Group.get_Name()
62
Instructor Notes:
None
Rev 1.0
Security
62
Security
Get Users and Groups
What Is a Realm?
An abstract entity representing:
y A collection of security principals (users and groups) who
have access to objects controlled by the Content Engine
For Active Directory…
y A realm is the same as the Domain
For other directory services…
y A realm is the base object used to search the directory
y Details were specified during Content Engine installation
63
Instructor Notes:
None
Rev 1.0
Security
63
Security
Get Users and Groups
User and Group Objects
User object
y Part of the security interface that allows a particular user to
access a Content Engine resource
Group object
y Reflects a set of user accounts defined by the directory
service
Creating users, groups, and subgroups
y Users and groups are created using tools provided by the
directory service
y You cannot create a new User or Group object, but you
can instantiate one that has been persisted in the directory
service
64
Help Paths:
Content Java API Documentation: Interface User
Content Java API Documentation: Interface Group
Instructor Notes:
None
Rev 1.0
Security
64
Security
Get Users and Groups
User and Group Names
Distinguished Name is a…
y Group or user's short name and the name of its domain
y Example: "CN=Admins,CN=Users,DC=FileNet,DC=com"
Short Name is the…
y Simple, non-unique portion of the distinguished name that
does not indicate its location relative to a domain or
directory
y Example: the short name form of the distinguished name
above is “Admins”
Principal Name is a…
y Group/user's short name, “@”, and the domain name
y Example: “Administrator@FileNet.com”
65
HELP PATH
FileNet P8 Documentation > FileNet P8 Administration > Enterprise-wide Administration > FileNet P8
Security > Directory service providers
Instructor Notes:
None
Rev 1.0
Security
65
Security
Get Users and Groups
FileNet User and Group Interfaces
FileNet P8 Content Java API has interfaces with same
name as some Java base interfaces
User interface
y com.filenet.api.security.User
Group interface
y com.filenet.api.security.Group
Code must give entire name when referenced
y Examples:
com.filenet.api.security.User user;
com.filenet.api.security.Group group;
66
Instructor Notes:
None
Rev 1.0
Security
66
Security
Get Users and Groups
Steps to Get User Names from the Directory Service
1. Get the EntireNetwork object.
Factory.EntireNetwork.fetchInstance(…)
2. Get the Realm object.
EntireNetwork.get_MyRealm()
3. Get the users in the realm that match a pattern.
Realm.findUsers(…)
4. Retrieve the name properties.
User.get_DistinguishedName()
User.get_Name()
67
Instructor Notes:
None
Rev 1.0
Security
67
Security
Get Users and Groups
Factory.EntireNetwork.fetchInstance(…)
public static EntireNetwork fetchInstance
(Connection conn, PropertyFilter filter)
Parameters
y conn - A Connection object for establishing the connection
to the Content Engine server.
y filter - A PropertyFilter object that represents information for
controlling which property values (and with what level of
detail and recursion) to return.
Returns
y An EntireNetwork object
68
ADDITIONAL INFORMATION
The EntireNetwork object allows your application to obtain access to the FileNet P8 domain and all object
stores in the GCD of the Content Engine.
Instructor Notes:
None
Rev 1.0
Security
68
Security
Get Users and Groups
EntireNetwork.get_MyRealm()
public Realm get_MyRealm()
Parameters
y None
Returns
y The Realm object in which the current user resides
69
Instructor Notes:
None
Rev 1.0
Security
69
Security
Get Users and Groups
Realm.findUsers(…)
public UserSet findUsers
( String searchPattern,
PricipalSearchType searchType,
PrincipalSearchAttribute searchAttribute,
PrincipalSearchSortType sortType,
Integer pageSize, PropertyFilter filter)
Parameters
y searchPattern - Specify a String containing a pattern of characters to
search for.
y searchType - Specify the type of search you want to conduct.
y searchAttribute - Specify which attribute to include in the search criteria.
y sortType - Specify how to sort the User objects in the returned collection.
y pageSize - Specify the number of elements to return per page.
Returns
y A Users collection representing the users that met the specified criteria
70
ADDITIONAL INFORMATION
• Possible values for the searchType parameter:
0 = PrincipalSearchType.NONE
1 = PrincipalSearchType.CUSTOM
2 = PrincipalSearchType.PREFIX_MATCH
3 = PrincipalSearchType.SUFFIX_MATCH
4 = PrincipalSearchType.CONTAINS
5 = PrincipalSearchType.EXACT
• Possible values for the searchedAttribute parameter:
0 = PrincipalSearchAttribute.NONE
1 = PrincipalSearchAttribute.SHORT_NAME
2 = PrincipalSearchAttribute.DISPLAY_NAME
• Possible values for the sortType parameter:
0 = PrincipalSearchSortType.NONE
1 = PrincipalSearchSortType.ASCENDING
2 = PrincipalSearchSortType.DESCENDING
• For pageSize, if null or zero (0), the default is 50
Instructor Notes:
None
Rev 1.0
Security
70
Security
Get Users and Groups
Sample Code to Retrieve User Names
…
propertyFilter.addIncludeProperty(0,null, null,
PropertyNames.MY_REALM);
EntireNetwork entireNetwork = Factory.EntireNetwork.
fetchInstance (connection, propertyFilter);
Realm realm = entireNetwork.get_MyRealm();
UserSet users = realm.findUsers(pattern,
PrincipalSearchType.PREFIX_MATCH,
PrincipalSearchAttribute.SHORT_NAME,
PrincipalSearchSortType.NONE,
Integer.getInteger("50"), null);
com.filenet.api.security.User user;
Iterator it = users.iterator();
while (it.hasNext()){
user = (com.filenet.api.security.User)it.next();
System.out.println("distinguished name =" +
user.get_DistinguishedName());
System.out.println("short name =" +
user.get_ShortName());
System.out.println("name =" + user.get_Name());
System.out.println("display name =" +
user.get_DisplayName());
}
71
Instructor Notes:
Question (from Eric Adel):
On the Select users and groups window( under properties/security tab/add); We have two options Display
name and short name radio buttons. What is the difference, they both return the same results?
Answer (from Phong and Java Doc):
The searchedAttribute parameter identifies the User object attribute to be included in the search criteria, as
follows:
0 (or PRINCIPAL_SEARCH_ATTR_NONE) specifies that no attribute is included in the search criteria.
1 (or PRINCIPAL_SEARCH_ATTR_SHORT_NAME) specifies that the user's short name is to be included
in the search criteria.
2 (or PRINCIPAL_SEARCH_ATTR_DISPLAY_NAME) specifies that the user's display name is to be
included in the search criteria.
The difference between short name and display name is in the way you define user:
If you use Active Directory User and Group tool to open a user or group, you can see there is a name and
a Display name. They can be different; our users/groups have the same short name as the display name,
for example allen, amy. If you want to test, create a user with the name eric, and then set the display name
to something different, say Bruce the Great, then test it and you can see the difference.
Rev 1.0
Security
71
Security
Get Users and Groups
Getting Group Names from the Directory Service
Procedure is the same as for getting users except
y Get a Groups collection from Realm object instead of a
Users collection:
Realm.findGroups(…)
Use Group objects instead of User objects
Same methods apply for Group objects:
Group.get_Name()
Group.get_Groups()
Group.get_Users()
72
Instructor Notes:
None
Rev 1.0
Security
72
Security
Get Users and Groups
Realm.findGroups(…)
public GroupSet findGroups
( String searchPattern,
PrincipalSearchType searchType,
PrincipalSearchAttribute searchAttribute,
PrincipalSearchSortType sortType,
Integer pageSize, PropertyFilter filter)
Parameters
y searchPattern - Specify a String containing a pattern of characters to
search for.
y searchType - Specify the type of search you want to conduct.
y searchAttribute - Specify which attribute to include in the search criteria.
y sortType - Specify how to sort the Group objects in the returned
collection.
y pageSize - Specify the number of elements to return per page.
Returns
y A GroupSet collection representing the groups that met the specified
criteria
73
ADDITIONAL INFORMATION
• Possible values for the searchType parameter:
0 = PrincipalSearchType.NONE
1 = PrincipalSearchType.CUSTOM
2 = PrincipalSearchType.PREFIX_MATCH
3 = PrincipalSearchType.SUFFIX_MATCH
4 = PrincipalSearchType.CONTAINS
5 = PrincipalSearchType.EXACT
• Possible values for the searchedAttribute parameter:
0 = PrincipalSearchAttribute.NONE
1 = PrincipalSearchAttribute.SHORT_NAME
2 = PrincipalSearchAttribute.DISPLAY_NAME
• Possible values for the sortType parameter:
0 = PrincipalSearchSortType.NONE
1 = PrincipalSearchSortType.ASCENDING
2 = PrincipalSearchSortType.DESCENDING
• For pageSize, if null or zero (0), the default is 50
Instructor Notes:
None
Rev 1.0
Security
73
Security
Get Users and Groups
Sample Code to Retrieve Group Names
EntireNetwork entireNetwork =
Factory.EntireNetwork.fetchInstance();
Realm realm = entireNetwork.get_MyRealm();
GroupSet groups = realm.findGroups(pattern,
PrincipalSearchType.PREFIX_MATCH,
PrincipalSearchAttribute.SHORT_NAME,
PrincipalSearchSortType.NONE,
Integer.getInteger("50"), null);
com.filenet.api.security.Group group;
Iterator groupIt = groups.iterator();
while (groupIt.hasNext()){
group=(com.filenet.api.security.Group)groupIt.next();
System.out.println("name =" + group.get_Name());
System.out.println("Distinguished name = " +
group.get_DistinguishedName());
System.out.println("short name =" +
group.get_ShortName());
74
Instructor Notes:
None
Rev 1.0
Security
74
Security
Get Users and Groups
Activities
In your workbook, see:
y Lesson: Retrieve Users and Groups
Complete these activities
y Find User and Group Names
75
Instructor Notes:
None
Rev 1.0
Security
75
Security
Rev 1.0
Security
76