Getting Started Procedures

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

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