Getting Started Procedures

This section provides information about, and code examples for, how to get a connection and get started with some base class objects.

Getting a Connection

For Java™ environments, you have the option of using either of these transports: Enterprise Java Beans (EJB) or Content Engine Web Service (CEWS). CEWS is also known as the Web Service Interface (WSI). You determine the transport to be used via the URI string (as shown in the Java code example below). For the EJB transport, a Java Authentication and Authorization Service (JAAS) context is usually already established so you just need to get the connection. For the CEWS transport, you must specify the URI endpoint as FNCEWS40DIME before getting the connection. For legacy Java applications that employ username and password for authentication, call UserContext.createSubject() along with 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 a FileNet® P8 domain, you have to authenticate the user (as shown in the C# code example below).

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/FNCEWS40DIME"; 
    }

    // 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

// Microsoft includes (for UsernameToken and UserContext)
using Microsoft.Web.Services3;
using Microsoft.Web.Services3.Design;
using Microsoft.Web.Services3.Security;
using Microsoft.Web.Services3.Security.Tokens;

...

// Make connection to Content Engine
static void makeConnection(
    String userName,
    String passWord,
    String osName)
{
    // Create a security token (either Kerberos or username).
    // In this case, username/password are supplied from an existing configuration file.
    UsernameToken token = new UsernameToken(userName, passWord, PasswordOption.SendPlainText); 

    // Associate this UserContext with the whole process 
    UserContext.SetProcessSecurityToken(token); 

    // Set the transport
    // Example of CEWS transport for WebLogic
    String uri = "http://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 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 have a reference to an EntireNetwork object, you can retrieve the subordinate objects in the hierarchy. For example, from EntireNetwork, you can instantiate a Domain object. From a Domain, you can navigate to an object store, then begin accessing documents, folders, etc. You can also use the EntireNetwork to retrieve all of the Realm objects for the FileNet P8 domain, then retrieve the users and groups associated with a realm.

Creating a Domain Object

Although it is possible to create a Domain object using API calls, the domain is typically created during the first invocation of the FileNet Enterprise Manager application, after which you get or fetch an instance of that object 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 information below and accompanying code snippets generally 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 only modify 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 additional 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);

Notes

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:

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 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);

Note: Searching for all users or groups in a large directory of users and groups can impact performance. In the example above, the number of users returned is limited by the use of the 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.