Getting Started Procedures
The following sections provide information and code examples that describe how to get a connection and get started with base class objects.
Getting a Connection
For Java™ environments, you have the
option of using either of these transports: Enterprise JavaBeans (EJB) or Content Engine Web Service (CEWS). CEWS
is also known as the Web Service Interface (WSI). You determine the
transport to be used with the URI string (as shown in the following Java code example). For the EJB
transport, if a Java Authentication
and Authorization Service (JAAS) context is already established, it
can be used directly. The same can be done for the CEWS transport
if the JAAS login module provided by IBM® FileNet is used. For Java applications that employ a
user name and password for authentication, you can alternatively call
the UserContext.createSubject
convenience method
along with the pushSubject
and popSubject
methods
to establish a JAAS context.
For .NET environments, you must use the CEWS transport. Before you can get a connection to an IBM FileNet P8 domain, you must authenticate the user (as shown in the following C# code example). Microsoft Windows Communication Foundation (WCF) supports only SSL-secured network communication so you must use an HTTPS server URL. If you use an HTTP URL, the API makes the connection by using Microsoft Web Services Extensions (WSE) 3.0, if present, or generates an error if WSE is not present.
Java Example
// Make connection to Content Engine
static void makeConnection(
boolean connectEjb,
String osName)
{
// Determine the transport to use via the URI string
String uri = null;
if (connectEjb == true)
{
// Example of EJB connection for WebLogic
uri = "t3://remotehost:7001/FileNet/Engine";
}
else
{
// Example of WSI connection for
WebSphere
uri = "http://remotehost1:9080/wsi/FNCEWS40MTOM";
}
// Get the connection and default domain
Connection conn = Factory.Connection.getConnection(uri);
Domain domain = Factory.Domain.getInstance(conn, null);
// Get an object store
ObjectStore os = Factory.ObjectStore.fetchInstance(domain, osName, null);
System.out.println("Object store name: " + os.get_Name());
}
C# Example
// includes (for UsernameCredentials and ClientContext)
using FileNet.Api.Authentication;
...
// Make connection to Content Engine
static void makeConnection(
String userName,
String passWord)
{
// Create credentials (either Kerberos or user name and password).
// In this case, username/password are supplied from an existing configuration file.
UsernameCredentials creds = new UsernameCredentials(userName, passWord);
// Associate this ClientContext with the whole process.
ClientContext.SetProcessCredentials(creds);
// Set the transport.
// Example of CEWS transport for WebLogic
String uri = "https://localhost:7001/wsi/FNCEWS40MTOM/";
// Get the connection and default domain.
IConnection conn = Factory.Connection.GetConnection(uri);
IDomain domain = Factory.Domain.GetInstance(conn, null);
// Get an object store.
IObjectStore os = Factory.ObjectStore.FetchInstance(domain, osName, null);
System.Console.WriteLine("Object store name: " + os.Name);
}
Retrieving an EntireNetwork Object
The EntireNetwork
object
is the highest-level object in the Content Engine API object model. Creating
an instance of this object exposes all other public objects in the
hierarchy.
To retrieve an EntireNetwork
object,
call the static methods on the Factory.EntireNetwork
class,
passing in a Connection
object. The Connection
object
provides information necessary to establish communication with the Content Engine server.
Java Example
EntireNetwork en = Factory.EntireNetwork.fetchInstance(conn, null);
After you obtain a reference to an EntireNetwork
object,
you can retrieve the subordinate objects in the hierarchy. For example,
from an EntireNetwork
object, you can instantiate
a Domain
object. From a Domain
object,
you can navigate to an ObjectStore
object, then begin
accessing documents, folders, and so on. You can also use the EntireNetwork
object
to retrieve all of the Realm
objects for the FileNet
P8
domain, then retrieve
the users and groups that are associated with a realm.
Creating a Domain Object
Although it is possible to create a Domain
object
by using API calls, the domain is typically created during the first
invocation of the Administration Console for Content Platform Engine,
after which you get or fetch an instance of that object by using instantiation
methods on the Factory
class. There is no Factory.Domain.createInstance
method
for directly creating a Domain
object. However, on
occasion, you might need to programmatically create a Domain
object.
In such a case, the following information and accompanying code snippets
illustrate how to perform this task.
To programmatically create
a Domain
object, you obtain a fetchlessly instantiated
instance, explicitly set the Create
pending action,
and then persist those changes. The resulting object is known as a
restricted-mode domain. In this mode, you can modify only the Domain
object.
You cannot create new objects (for example, ObjectStore
, MarkingSet
, Site
, and so on).
To enable full domain availability, you must perform two more steps:
add DirectoryConfiguration
objects and set permissions. Until you set the
permissions, the domain is not considered available for general use.
Java Example
// Create the restricted mode domain
String uri = "iiop://localhost:2809/FileNet/Engine"; // URI varies by app server
Connection conn = new ConnectionImpl(uri);
Domain myDomain = Factory.Domain.getInstance(conn, "mydomain");
myDomain.addPendingAction(new Create(ClassNames.DOMAIN, null, null, null, null, null));
myDomain.set_Name("myDomain");
myDomain.save(RefreshMode.REFRESH);
// Add DirectoryConfiguration objects (see notes below)
DirectoryConfigurationList myDirConfigs = buildMyDirectoryObjects();
myDomain.set_DirectoryConfigurations(myDirConfigs);
myDomain.save(RefreshMode.REFRESH);
// Set permissions (see notes below)
AccessPermissionList apl = buildMyPermissions();
myDomain.setPermissions(apl);
myDomain.save(RefreshMode.REFRESH);
C# Example
// Create the restricted mode domain
String uri = "iiop://localhost:7001/wsi/FNCEWS40MTOM"; // URI varies by app server
IConnection conn = new Factory.Connection.GetConnection(uri);
IDomain myDomain = Factory.Domain.GetInstance(conn, "mydomain");
myDomain.AddPendingAction(new Create(ClassNames.DOMAIN, null, null, ReservationType.COLLABORATIVE, null, null));
myDomain.Name = "myDomain";
myDomain.Save(RefreshMode.REFRESH);
// Add DirectoryConfiguration objects (see notes below)
IDirectoryConfigurationList myDirConfigs = buildMyDirectoryObjects();
myDomain.DirectoryConfigurations = myDirConfigs;
myDomain.Save(RefreshMode.REFRESH);
// Set permissions (see notes below)
IAccessPermissionList apl = buildMyPermissions();
myDomain.Permissions = apl;
myDomain.Save(RefreshMode.REFRESH);
- When setting permissions, a best practice is to specify at least one group whose members are allowed access to the object. Doing so eases potential access issues that can occur, for example, in environments with password expiration policies.
- Programmatic deletion of the FileNet P8 domain by using the API is not supported.
Working with Realm Objects
The
primary use of a Realm
object is to retrieve lists
of the users and groups within the FileNet
P8
domain. You can instantiate
a Realm
object by:
- calling static methods on the
Factory.Realm
class. - calling
EntireNetwork.get_MyRealm()
, which returns aRealm
object that represents the realm in which the caller resides. - iterating a
RealmSet
collection.
The following Java code
fragment instantiates a Realm
object for the current
user. The groups of users within the domain are then retrieved and
listed based on those users that meet the search criteria:
Java Example
Realm realm = Factory.Realm.fetchCurrent(domain.getConnection(), null);
System.out.println("Realm Name: " + realm.get_Name()); //print the name of the realm for the current user
UserSet users = realm.findUsers("Ha", PrincipalSearchType.PREFIX_MATCH,
PrincipalSearchAttribute.SHORT_NAME,
PrincipalSearchSortType.ASCENDING,
new Integer(5), null);
// Invoke a routine to print the returned set of users
printPrincipalSet(users, true);
findUsers
method. For details on
each of the parameters that form the filter criteria for the findUsers
and findGroups
methods,
refer to the method descriptions in the Realm
interface documentation.