15
Security

This chapter discusses how to secure information in Oracle 9iFS. It covers the following topics:

• Security Overview

• Managing Access to the Repository

• Managing Access to PublicObjects

• Managing Access to ClassObjects

• Granting Implicit Access to Objects

• Sample Code

Security Overview

A fundamental requirement for any content management application is to secure how information is accessed. Oracle 9iFS provides a robust set of interfaces that give you fine-grained control over how information is secured in your application, and that allow you to define broader levels of security that make it easier for end users to manage access to information.

Security in Oracle 9iFS is managed at two levels:

• Repository-level Security

• Object-level Security

Repository-level Security

When a user tries to access information stored in an Oracle 9iFS, Oracle 9iFS first determines if that user has access to the repository. Oracle 9iFS maintains a directory of all users who can access the repository. Before allowing a user to access the repository, Oracle 9iFS authenticates the user's credentials. Once authenticated, the user can browse, search, and manipulate information in the repository, within the constraints of the object-level security defined on the information.

Oracle 9iFS also controls how each user can work in the repository. Oracle 9iFS maintains a profile of the user's preferences, such as the user's distinguished name, home folder, content quota and default ACLs. You can extend profiles to include other preferences that are specific to your application.

Oracle 9iFS makes it easier to manage users' access to information by allowing you to define and create user groups. Groups organize sets of users who have something in common. Groups can include other groups, allowing you to create inclusive hierarchies of users. You can extend Oracle 9iFS to define a custom type of group that possesses attributes and behaviors pertinent to groups of that type. Once you've defined and created user groups, you can assign access permissions and content quotas to several users at once by assigning them to a group.

Object-level Security

Oracle 9iFS allows you to control how users can access each object in the repository. You can control access to objects in three ways:

• Managing Access to PublicObjects. You can control which users can discover, read, modify, and delete specific documents, folders, and other types of information by defining access permissions on PublicObjects.

• Managing Access to ClassObjects. You can control which users can create and search for specific types of information by defining access permissions on ClassObjects.

• Granting Implicit Access to Objects. You can also implicitly grant users full access to an object by designating the user as the object's owner, and full access to all information in the repository by making the user a system administrator.

Managing Access to PublicObjects

Access permissions on PublicObjects are managed with AccessControlLists (ACLs). Whenever a user tries to access a PublicObject, Oracle 9iFS first checks the associated AccessControlList to verify that the user has been granted the appropriate permissions.

An AccessControlList is a list of users and groups who have been granted or revoked access permissions to the PublicObject. Each time a user or group is granted or revoked access permissions, an entry is added to the AccessControlList. Oracle 9iFS resolves a user's effective access to a PublicObject by aggregating the AccessControlEntries in the order that they were created in the AccessControlList. Each AccessControlList is defined independently in Oracle 9iFS and applied to one or more PublicObjects, allowing you to centrally manage common security levels for PublicObjects.

Any user can create an AccessControlList. When an AccessControlList is created, the user can determine who else can apply the AccessControlList to PublicObjects and manage the AccessControlList entries. In this way, users can create personal AccessControlLists that they use to manage access to their information, or share AccessControlLists to manage access to information that they collaborate on with other users. Administrators can also create a special type of AccessControlList, a SystemAccessControlList, to define system-wide security levels that can be applied by any Oracle 9iFS user to information in the repository.

While AccessControlLists can be used to grant and revoke standard permissions defined by Oracle 9iFS, including Discover, GetContent, SetAttribute, SetContent, and Delete, Oracle 9iFS allows you to define custom permissions. You can define extended permissions to manage access to custom application behavior. You can also define broader levels of access by grouping permissions to make it easier for users manage security on PublicObjects.

Managing Access to ClassObjects

As discussed in Chapter 5, "Extending Content Types and Attributes", every content type is defined by a ClassObject. You can control which users and groups can create and search for instances of a content type by defining a ClassAccessControlList for the ClassObject.

Implicit Access Control

Users are implicitly granted full access to information in the repository by virtue of being an owner of an object or a system administrator. When a user is designated as the owner of an object in Oracle 9iFS, the user is granted all access permissions to that object. When a user is designated as an administrator, the user is granted all access permissions to all information in the repository. The access permissions are granted implicitly by Oracle 9iFS in that they are not applied by the object's AccessControlList, but supersede it.

Managing Access to the Repository

This section describes how Oracle 9iFS uses directories to access to the repository. It covers the following topics:

• How Directories Work

• Directory Structure

• Creating, Modifying, and Deleting DirectoryUsers and PrimaryUserProfiles

• Defining ExtendedUserProfile Classes

• Applying ExtendedUserProfiles to DirectoryUsers

• Creating, Modifying, and Deleting DirectoryGroups

• Defining Custom Group Classes

• Creating, Modifying, and Deleting Custom Groups

• Authenticating DirectoryUsers

How Directories Work

Oracle 9iFS maintains a directory of all users who can access the repository. The directory stores information about the user, such as the user's distinguished name, whether the user is an administrator, how the user is authenticated, and how the user prefers to work in the repository. In addition, the Oracle 9iFS directory manages groups that can be used to organize users hierarchically, classify users, and assign access privileges held in common by several users.

Authenticating Users

Before allowing a user to access the repository, Oracle 9iFS authenticates the user's credentials. First, the user is identified in the directory by a distinguished name. Second, the user's password is verified against a credential manager. Each user account is associated with a credential manager that is used to authenticate the user's password. This release of Oracle 9iFS provides a built-in credential manager that is used to authenticate all users. Future releases of Oracle 9iFS will support external credential managers.

Profiling Users

Each user account in Oracle 9iFS is associated with one or more profiles that store the user's preferences for working with the repository. Oracle 9iFS defines a set of standard preferences that are stored in a primary user profile. The standard preferences include the user's home folder (i.e., the user's personal work area), content quota (i.e., the amount of storage space allocated for the user), and default ACLs (i.e., the AccessControlLists that will be applied by default to objects the user creates).

Oracle 9iFS allows you to store custom preferences for users by creating extended user profiles. For example, you might store preferences that personalize the user's view of the repository in a custom Web application.

Grouping Users

Oracle 9iFS allows you to organize users hierarchically into groups. Groups represent sets of users who have something in common. For example, you can create groups for the various roles that users may have (e.g. Manager, Developer, Writer). You can also create groups to represent different companies divisions or projects (e.g., Marketing, Sales, Development). Groups can include other groups, allowing you to create inclusive hierarchies of users. For example, the Oracle group could contain the Server Technologies group, which could contain Oracle 9iFS, Oracle Text, and Oracle interMedia groups.

Groups make it easier to enforce security on information for a set of users. You can grant groups access permissions on objects in the repository. For example, you can grant all managers read access to documents in the repository by creating an AccessControList that designates the Manager group as the Grantee of an AccessControlEntry. This allows you to quickly define the access permissions for all users in that group once, instead of on a user by user basis. As users are added to and removed from the group, the access permissions will be dynamically granted to the current members of the group.

Oracle 9iFS allows you to define custom group types that possess extra attributes and behavior. For example, you could create an Organization group type that possesses the attributes VicePresident and MissionStatement. You can define the group types hierarchically so that group types inherit attributes and behaviors. For example, you might create a group type, Company, with the attributes Address and MainPhoneNumber, and then a subgroup type, Partner, that inherits these attributes and adds the attribute ContractNumber.

Directory Structure

Oracle 9iFS provides a set of classes for managing users and groups. The classes DirectoryUser and DirectoryGroup, which descend from PublicObject, serve as the primary interfaces for representing users and groups who work with information in Oracle 9iFS. These classes are supported by a few SystemObject classes that are used to represent each user's preferences for working in the repository, and how users are related to groups. Figure 15-1 illustrates the structure of directory information in Oracle 9iFS.

Figure 15-1 Directory Object Model

DirectoryUsers

Every Oracle 9iFS user is represented by an instance of the DirectoryUser class. DirectoryUser possesses attributes and methods for managing the user, including assigning the user administrative privileges, uniquely naming the user, and specifying the credential manager that is used to authenticate the user.s

Table 15-1 lists the most commonly used attributes and methods on DirectoryUser.

Table 15-1 DirectoryUser Attributes and Methods

User Profiles (Primary and Extended)

Every DirectoryUser possess a profile of preferences for how the user works with the repository, such as the user's home folder and content quota. Oracle 9iFS uses three classes to manage user preferences:

• PrimaryUserProfile has attributes and methods for managing preferences that are defined out-of-the-box with Oracle 9iFS, like the user's home folder and content quota.

• ExtendedUserProfile provides a base content type for managing custom preferences.

• ContentQuota is used to manage how much content a user can store in the Oracle 9iFS repository.

Table 15-2 lists the most commonly used attributes and methods on PrimaryUserProfile.

Table 15-2 PrimaryUserProfile Attributes and Methods

Table 15-3 lists the most commonly used attributes and methods on ExtendedUserProfile.

Table 15-3 ExtendedUserProfile Attributes and Methods

Table 15-4 lists the most commonly used attributes and methods on ContentQuota.

Table 15-4 ContentQuota Attributes and Methods

DirectoryGroups

Groups are represented in Oracle 9iFS by two content types, DirectoryGroup and GroupMemberRelationship. DirectoryGroup descends from PublicObject and, therefore, acts as the primary interface for managing group membership. GroupMemberRelationship, which descends from SystemObject, represents the relationship between a user and a group. An instance of GroupMemberRelationship is created to represent each user's or group's membership.

You can extend DirectoryGroup to classify groups and to add extra attributes and behaviors that are special for those types of groups. For example, you can create a Organization group that extends DirectoryGroup to include the attributes VicePresident and MissionStatement. You can also extend GroupMemberRelationship to manage extra metadata about each user's membership in the Organization group, like TeamRole.

Table 15-5 lists the most commonly used attributes and methods on DirectoryGroup.

Table 15-5 DirectoryGroup Attributes and Methods

Table 15-6 lists the most commonly used attributes and methods on GroupMemberRelationship.

Table 15-6 GroupMemberRelationship Attributes and Methods

Creating, Modifying, and Deleting DirectoryUsers and PrimaryUserProfiles

Oracle 9iFS provides three methods for creating, modifying and deleting DirectoryUsers with PrimaryUserProfiles:

• XML, creating XML files that automatically define DirectoryObjects when imported into Oracle 9iFS

• Java, programmatically defining DirectoryObjects via Oracle 9iFS Java API

• Oracle 9iFS Manager, using a graphical user interface to define DirectoryObjects.

XML

You can use XML files to create and modify DirectoryUsers and PrimaryUserProfiles. When the XML file is imported into Oracle 9iFS, the IfsSimpleXmlParser automatically uses it to create or modify a DirectoryUser instance. The IfsSimpleXmlParser supports a special XML schema, SimpleUser, that makes it easy to create DirectoryUsers. Rather than creating an XML file that includes two elements whose schemas correspond to the DirectoryUser and PrimaryUserProfile classes, the SimpleUser schema allows you to specify DirectoryUser attributes and PrimaryUserProfile attributes in the same element. However to update DirectoryUsers and PrimaryUserProfiles with XML, the schema of the XML file must correspond to the DirectoryUser class or PrimaryUserProfile class according to the syntax rules outlined in Chapter 10, "XML and the Oracle Internet File System".

Example 15-1 and Example 15-2 illustrate how to create and modify DirectoryUsers and PrimaryUserProfiles with XML.

Java

You can use the Oracle 9iFS Java API to programmatically create, modify, and delete DirectoryUsers and PrimaryUserProfiles. The oracle.ifs.adk.user package in the Oracle 9iFS Java API includes a special helper class, UserManager, that provides an easy way to create and delete a DirectoryUser along with a PrimaryUserProfile. Once created, you can modify the DirectoryUser and PrimaryUserProfiles by working directly with the methods defined on their classes.

Example 15-4, Example 15-5, and Example 15-6 illustrate how to create, modify and delete DirectoryUsers and PrimaryUserProfiles with the Java API.

Oracle 9iFS Clients

Oracle 9iFS clients provides a graphical user interface for creating DirectoryUsers and PrimaryUserProfiles.

Example 15-1 Using XML to Create a DirectoryUser

<?xml version = '1.0' standalone = 'yes'?>
<SIMPLEUSER>
  <USERNAME>gking</USERNAME>
  <PASSWORD>ifs</PASSWORD>
  <DISTINGUISHEDNAMESUFFIX>.ambiguity.com</DISTINGUISHEDNAMESUFFIX>
  <ADMINENABLED>true</ADMINENABLED>
  <HOMEFOLDERROOT>/home</HOMEFOLDERROOT>
  <EMAILADDRESSSUFFIX>@ambiguity.com</EMAILADDRESSSUFFIX>
</SIMPLEUSER>

Example 15-2 Using XML to Modify a DirectoryUser

<?xml version = '1.0' standalone = 'yes'?>
 <DIRECTORYUSER>
  <UPDATE RefType = "Name">gking</UPDATE>
  <DISTINGUISHEDNAME>gking.clarity.com</DISTINGUISHEDNAME>
 </DIRECTORYUSER>

Example 15-3 Using XML to Modify a PrimaryUserProfile

<?xml version = '1.0' standalone = 'yes'?>
 <PRIMARYUSERPROFILE>
  <UPDATE RefType = "Name">gking Primary Profile</UPDATE>
  <HOMEFOLDER RefType = "Path">/home/system</HOMEFOLDER>
 </PRIMARYUSERPROFILE>

Example 15-4 Using Java to Create a User

1. Administration mode must be enabled to create a user.

   session.setAdministrationMode(true);
   
   

2. Construct a new instance of UserManager.

   // Creating an user using all the default options;
   UserManager usermanager = new UserManager(session);
   
   

3. Construct a HashTable to hold user options.

   Hashtable userOptions = new Hashtable();
   
   userOptions.put(UserManager.ADMIN_ENABLED, new Boolean(true));
   userOptions.put(UserManager.EMAIL_ADDRESS, "gking@oracle.com");
   
   

4. Create the user.

   DirectoryUser dUser = usermanager.createUser("gkings",
                                                "ifs",
                                                userOptions);
   

Example 15-5 Using Java to Modify a DirectoryUser

1. Fetch the DirectoryUser to be modified.

   Collection duColl = session.getDirectoryUserCollection();
   DirectoryUser dUser = (DirectoryUser) duColl.getItems("gking");
   
   

2. Administration mode must be enabled to modify a user.

   session.setAdministrationMode(true);
   
   

3. Update the user's PrimaryUserProfile to set the default ACL for all documents and folders created by this user

   PrimaryUserProfile pup = dUser.getPrimaryUserProfile();
   
   Collection aclColl = session.getSystemAccessControlListCollection();
   AccessControlList defaultAcl = (AccessControlList) aclColl.getItems("PUBLIC");
   
   pup.putDefaultAcl("DOCUMENT", defaultAcl);
   pup.putDefaultAcl("FOLDER", defaultAcl);
   

Example 15-6 Using Java to Delete a DirectoryUser

1. Administration mode must be enabled to delete a user.

   session.setAdministrationMode(true);
   
   

2. Fetch the DirectoryUser instance to be deleted.

   Collection duColl = session.getDirectoryUserCollection();
   DirectoryUser dUser = (DirectoryUser) duColl.getItems("gking");
   
   

3. Get the user's DistinguishedName.

   String distinguishedName = dUser.getDistinguishedName();
   
   

4. Instantiate a UserManager object.

   UserManager manager = new UserManager(session);
   
   

5. Provide a set of delete options:

   Hashtable options = new Hashtable();
   
   

6. Specify the user's DistinguishedName.

   options.put(UserManager.DISTINGUISHED_NAME,
           AttributeValue.newAttributeValue(distinguishedName));
   
   

7. Specify to delete the user's HomeFolder.

   options.put(UserManager.FREE_HOME_FOLDER,
           AttributeValue.newAttributeValue(true));
                   
   

8. Specify to delete the credential manager user.

   options.put(UserManager.FREE_CREDENTIAL_MANAGER_USER,
           AttributeValue.newAttributeValue(true));
                   
   

9. Specify to change the owner to system for PublicObjects owned by this user.

   options.put(UserManager.CHANGE_OWNER,
           AttributeValue.newAttributeValue(true));
   options.put(UserManager.NEW_OWNER_USER_NAME,
           AttributeValue.newAttributeValue("system"));
   
   

10. Delete the user.

    manager.deleteUser(distinguishedName, options);
    

Defining ExtendedUserProfile Classes

Defining ExtendedUserProfile classes entails the same steps required for defining any custom class. You create a set of SchemaObject instances to represent the ExtendedUserProfile class. You can modify and delete the ExtendedUserProfile by editing or deleting its SchemaObjects. These development tasks can be done with the Java API, XML files, or the Oracle 9iFS Manager.

Example 15-7 illustrates how to create and modify ExtendedUserProfile classes with XML. It is not possible to delete classes with XML.

Example 15-8 and Example 15-12 illustrate how to define, modify, and delete ExtendedUserProfile classes with Java.

Creating ExtendedUserProfile Classes

To create a new ExtendedUserProfile class, you subclass the ExtendedUserProfile class provided out-of-the-box with Oracle 9iFS. Your extended class would possess attributes to hold the custom user preferences. For example, you could create a class, CatalogUserProfile, that extends ExtendedUserProfile and includes the extended attributes DefaultLayout and DefaultRole.

To define the ExtendedUserProfile class, follow these steps:

1. Ensure that you have administration privileges. If you are using XML configuration files, import the files as an administrator. If you are using the Java API, enable Administration Mode for your session with Oracle 9iFS.

2. Create instances of ClassObject to represent the ExtendedUserProfile class.

3. Create instances of Attribute to represent each user preference.

4. Optionally, define any custom methods by creating custom Java classes for the ExtendedUserProfile class.

   
   

   NOTE: See Chapter 17, "Customizing Content Type Behavior" to learn how to create custom Java classes.

Example 15-7 Using XML to Create an ExtendedUserProfile Class

<?xml version="1.0" standalone="yes"?>
<CLASSOBJECT>
    <NAME>CatalogUserProfile</NAME>   
    <SUPERCLASS RefType = "Name">ExtendedUserProfile</SUPERCLASS>  
    <DESCRIPTION>User preferences for the Product Catalog.</DESCRIPTION>
    <ATTRIBUTES>
        <ATTRIBUTE>
            <NAME>DefaultLayout</NAME>
            <DATATYPE>String</DATATYPE>
        </ATTRIBUTE>
        <ATTRIBUTE>
            <NAME>DefaultRole</NAME>
            <DATATYPE>String</DATATYPE>
        </ATTRIBUTE>
    </ATTRIBUTES>
</CLASSOBJECT>

Example 15-8 Using Java to Create an ExtendedUserProfile Class

1. Enable Administration Mode.

   session.setAdministrationMode(true);
   
   

2. Create a ClassObjectDefinition to hold the values for the ClassObject that represents the ExtendedUserProfile.

   ClassObjectDefinition codef = new ClassObjectDefinition(session);
   codef.setAttributeByUpperCaseName(ClassObject.NAME_ATTRIBUTE,
        AttributeValue.newAttributeValue("CatalogUserProfile"));
   
   

3. Specify that your new class extends ExtendedUserProfile.

   ClassObject superClass = session.getClassObjectByName("EXTENDEDUSERPROFILE");
   codef.setSuperclass(superClass);
   
   

4. Create AttributeDefinitions for each attribute pertaining to the ExtendedUserProfile type. Add the AttributeDefinitions to the ClassObjectDefinition.

   AttributeDefinition attdef1 = new AttributeDefinition(session);
   attdef1.setAttributeByUpperCaseName(Attribute.NAME_ATTRIBUTE,
           AttributeValue.newAttributeValue("DefaultLayout"));
   attdef1.setAttributeByUpperCaseName(Attribute.DATATYPE_ATTRIBUTE,
           AttributeValue.newAttributeValue(Attribute.ATTRIBUTEDATATYPE_STRING));
   
   codef.addAttributeDefinition(attdef1);
   
   AttributeDefinition attdef2 = new AttributeDefinition(session);
   attdef2.setAttributeByUpperCaseName(Attribute.NAME_ATTRIBUTE,
           AttributeValue.newAttributeValue("DefaultRole"));
   attdef2.setAttributeByUpperCaseName(Attribute.DATATYPE_ATTRIBUTE,
           AttributeValue.newAttributeValue(Attribute.ATTRIBUTEDATATYPE_STRING));
   
   codef.addAttributeDefinition(attdef2);
   
   

5. Create the ClassObject and Attributes for the new ExtendedUserProfile class.

   ClassObject eupCo = (ClassObject) session.createSchemaObject(codef);
   

Modifying ExtendedUserProfile Classes

You can add, remove, and update attributes on an ExtendedUserProfile class after it has been created.

Example 15-9 Using Java to Add, Remove, and Update Attributes on ExtendedUserProfile Classes

1. Enable Administration Mode.

   session.setAdministrationMode(true);
   
   

2. Get the ClassObject that represents the ExtendedUserProfile class.

   ClassObject co = session.getClassObjectByName("CATALOGUSERPROFILE");
   
   

3. Add an Attribute to the ClassObject.

   AttributeDefinition attdef1 = new AttributeDefinition(session);
   attdef1.setAttributeByUpperCaseName(Attribute.NAME_ATTRIBUTE,
           AttributeValue.newAttributeValue("DefaultWorkArea"));
   attdef1.setAttributeByUpperCaseName(Attribute.DATATYPE_ATTRIBUTE,
           AttributeValue.newAttributeValue(
             Attribute.ATTRIBUTEDATATYPE_PUBLICOBJECT));
   co.addAttribute(attdef1);
   
   

4. Remove an Attribute from the ClassObject.

   Attribute att2 = catco.getAttributeFromLabel("DEFAULTROLE");
   co.removeAttribute(att2);
   
   

5. Update an Attribute on the ClassObject.

   Attribute att3 = co.getAttributeFromLabel("DEFAULTWORKAREA");
   Collection cdColl = session.getClassDomainCollection();
   ClassDomain cd = (ClassDomain) cdColl.getItems("Folder...");
   att3.setClassDomain(cd);
   

Example 15-10 Using Java to Delete ExtendedUserProfile Classes

1. Enable Administration Mode.

   session.setAdministrationMode(true);
   
   

2. Get the ClassObject that represents the ExtendedUserProfile class.

   ClassObject co = session.getClassObjectByName("CATALOGUSERPROFILE");
   
   

3. Delete the ClassObject by calling the free() method.

   co.free();
   

Applying ExtendedUserProfiles to DirectoryUsers

Once you've defined an ExtendedUserProfile class, you can apply the ExtendedUserProfiles to DirectoryUsers. To apply an ExtendedUserProfile, you create an instance of the ExtendedUserProfile class that references the DirectoryUser and holds the user's preferences in extended attributes. ExtendedUserProfile instances can also specify which application uses the profile in the Application attribute inherited from the ExtendedUserProfile class. ExtendedUserProfile instances can subsequently be modified and deleted in the same manner as any other object in Oracle 9iFS. These development tasks can be done with the Java API, XML files or the Oracle 9iFS Manager.

Example 15-11 illustrates how to create an ExtendedUserProfile instance with XML. It is not possible to delete instances with XML.

Example 15-12 and Example 15-13 illustrate how to create and delete an ExtendedUserProfile instance with Java.

Example 15-11 Using XML to Create ExtendedUserProfile Instances

<?xml version="1.0" standalone="yes"?>
<CATALOGUSERPROFILE>
  <DIRECTORYUSER RefType = "Name">gking</DIRECTORYUSER>
  <APPLICATION>ProductCatalog</APPLICATION>
  <DEFAULTLAYOUT>TreeView</DEFAULTLAYOUT>
  <DEFAULTROLE>Consumer</DEFAULTROLE>
</CATALOGUSERPROFILE>

Example 15-12 Using Java to Create ExtendedUserProfile Instances

1. Fetch the DirectoryUser to possess the extended user profile.

   Collection duColl = session.getDirectoryUserCollection();
   DirectoryUser dUser = (DirectoryUser) duColl.getItems("gking");
   
   

2. Create a new UserProfileDefinition.

   UserProfileDefinition eupDef = new UserProfileDefinition(session);
   
   

3. Specify the type of the new ExtendedUserProfile instance.

   ClassObject co = session.getClassObjectByName("CATALOGUSERPROFILE");
   eupDef.setClassObject(co);
   
   

4. Set the values of the ExtendedUserProfile attributes.

   eupDef.setAttributeByUpperCaseName(ExtendedUserProfile.DIRECTORYUSER_ATTRIBUTE, 
        AttributeValue.newAttributeValue(dUser));
   eupDef.setAttributeByUpperCaseName(ExtendedUserProfile.APPLICATION_ATTRIBUTE,
            AttributeValue.newAttributeValue(
              "ProductCatalog"));
   eupDef.setAttributeByUpperCaseName("DEFAULTLAYOUT", 
        AttributeValue.newAttributeValue("TreeView"));
   eupDef.setAttributeByUpperCaseName("DEFAULTROLE",
        AttributeValue.newAttributeValue("Consumer"));
   
   

5. Pass the UserProfileDefinition to the LibrarySession to create a new ExtendedUserProfile instance.

   ExtendedUserProfile eup = (ExtendedUserProfile) 
   session.createPublicObject(eupDef);
   

Example 15-13 Using Java to Delete ExtendedUserProfile Instances

1. Use a Selector to obtain ExtendedUserProfile instances

   Selector s = new Selector(session);
   s.setSearchClassname("CATALOGUSERPROFILE");
   
   LibraryObject[] eups = s.getItems();
   ExtendedUserProfile eup;
   
   

2. Delete the ExtendedUserProfile instances.

   int i;
   int count = (eups == null) ? 0 : eups.length;
   
   for (i = 0; i < count; i++)
   {
      eup = (ExtendedUserProfile) eups[i];
      eup.free();
   }
   

Creating, Modifying, and Deleting DirectoryGroups

Oracle 9iFS provides three methods for creating, modifying and deleting DirectoryGroups:

• XML. You can use XML files to create and modify DirectoryGroups. When the XML file is imported into Oracle 9iFS, the IfsSimpleXmlParser automatically uses it to create or modify a DirectoryGroup instance. The IfsSimpleXmlParser supports a special XML tags, <MEMBERS> and <REF>, that makes it easy to add DirectoryUsers to DirectoryGroups. Example 15-14 and Example 15-15 illustrate how to create and modify DirectoryGroups with XML.

  
  

  NOTE: Oracle 9iFS does not support deleting DirectoryGroups with XML.

• Java. You can use the Oracle 9iFS Java API to programmatically create, modify, and delete DirectoryGroups. Example 15-16, Example 15-17, and Example 15-18 illustrate how to create, modify and delete DirectoryGroups with the Java API.

• Oracle 9iFS Clients. Oracle 9iFS clients provide a graphical user interface for creating DirectoryGroups.

  
  

  NOTE: For instructions on defining DirectoryGroups with the Oracle 9iFS clients, consult the Oracle 9iFS Setup and Administration Guide.

Example 15-14 Using XML to Create a DirectoryGroup Instance

<?xml version = '1.0' standalone = 'yes'?>
 <DIRECTORYGROUP>
  <NAME>Managers</NAME>
  <MEMBERS>
    <REF reftype='name'>msmith</REF>
    <REF reftype='name'>rjones</REF>
    <REF reftype='name'>tturner</REF>
  </MEMBERS>
 </DIRECTORYGROUP>

Example 15-15 Using XML to Modify a DirectoryGroup Instance

<?xml version = '1.0' standalone = 'yes'?>
 <DIRECTORYGROUP>
  <UPDATE RefType = "Name">Managers</UPDATE>
  <MEMBERS>
    <REF RefType = 'Name'>csapo</REF>
  </MEMBERS>
 </DIRECTORYGROUP>

Example 15-16 Using Java to Create a DirectoryGroup Instance

1. Create a new DirectoryGroupDefinition.

   DirectoryGroupDefinition dgDef = new DirectoryGroupDefinition(session);
   
   

2. Set the values of the DirectoryGroup's attributes.

   dgDef.setAttributeByUpperCaseName("NAME",
            AttributeValue.newAttributeValue(
              "Managers"));
   
   

3. Pass the DirectoryGroupDefinition to the LibrarySession to create a new DirectoryGroup instance.

   DirectoryGroup dg = (DirectoryGroup) session.createPublicObject(dgDef);
   
   

4. Obtain the DirectoryUsers who belong in the DirectoryGroup.

   DirectoryUser du;
   LibraryObject[] dus;
   Selector s = new Selector(session);
   s.setSearchClassname("DIRECTORYUSER");
   s.setSearchSelection("NAME IN ('msmith', 'tturner', 'rjones')");
   dus = s.getItems();
   
   int icount = (dus == null) ? 0 : dus.length;
   for (i = 0; i < icount; i++)
   {
       du = (DirectoryUser) du[i];
   
   

5. Add the DirectoryUsers to the DirectoryGroup.

       dg.addMember(du);
   }
   

Example 15-17 Using Java to Modify a DirectoryGroup Instance

/*
 * The following example moves DirectoryUsers 
 * from one group to another.
 */

1. Assume that the application has obtained the DirectoryGroups.

   DirectoryGroup dg1 = ...
   DirectoryGroup dg2 = ...
   
   

2. Fetch the DirectoryUsers from the first group.

   DirectoryObject[] dus = dg1.getDirectMembers();
   
   

3. Add the DirectoryUsers to the second group. The addMembers() method will fail if any of the members already exist in the group.

   dg2.addMembers(dus);
   
   

4. Remove a DirectoryUsers from the first group.

   dg1.removeMembers(dus);
   

Example 15-18 Using Java to Delete a DirectoryGroup Instance

1. Assume that the application has obtained the DirectoryGroup.

   DirectoryGroup dg = ...
   
   

2. Delete the DirectoryGroup.

   dg.free();
   

   
   

   NOTE: Deleting a DirectoryGroup does not automatically delete the DirectoryUsers in that group. To learn how to delete DirectoryUsers, see "Creating, Modifying, and Deleting DirectoryUsers and PrimaryUserProfiles".

Defining Custom Group Classes

Defining custom group classes entails the same steps required for defining any custom class. You can create custom group classes with the Java API, XML files, or the Oracle 9iFS Manager.

Example 15-19 illustrates how to create and modify ExtendedUserProfile classes with XML. It is not possible to delete classes with XML.

Example 15-20 and Example 15-21 illustrate how to define, modify, and delete ExtendedUserProfile classes with Java.

Creating Group Classes

To create a custom group class, you subclass the DirectoryGroup class to add custom attributes and behaviors for that type of group. For example, you could create a class, Organization, that extends DirectoryGroup and includes the extended attributes VicePresident and MissionStatement.

To define the custom group class, follow these steps:

1. Ensure that you have administration privileges. If you are using XML configuration files, import the files as an administrator. If you are using the Java API, enable Administration Mode for your session with Oracle 9iFS.

2. Create instances of ClassObject to represent the group class.

3. Create instances of Attribute to represent each extended attribute.

4. Optionally, define custom methods by creating custom Java classes for the group class.

   
   

   NOTE: See Chapter 17, "Customizing Content Type Behavior" to learn how to create custom Java classes.

Example 15-19 Using XML to Create a Group Class

<?xml version="1.0" standalone="yes"?>
<CLASSOBJECT>
    <NAME>Organization</NAME>   
    <SUPERCLASS RefType = "Name">DirectoryGroup</SUPERCLASS>  
    <DESCRIPTION>Custom group class to manage organizations.</DESCRIPTION>
    <ATTRIBUTES>
        <ATTRIBUTE>
            <NAME>VicePresident</NAME>
            <DATATYPE>DirectoryObject</DATATYPE>
        </ATTRIBUTE>
        <ATTRIBUTE>
            <NAME>MissionStatement</NAME>
            <DATATYPE>String</DATATYPE>
        </ATTRIBUTE>
    </ATTRIBUTES>
</CLASSOBJECT>

Example 15-20 Using Java to Create a Group Class

1. Enable Administration Mode.

   session.setAdministrationMode(true);
   
   

2. Create a ClassObjectDefinition to hold the values for the ClassObject that represents the group class.

   ClassObjectDefinition codef = new ClassObjectDefinition(session);
   codef.setAttributeByUpperCaseName(ClassObject.NAME_ATTRIBUTE,
        AttributeValue.newAttributeValue("Organization"));
   
   

3. Specify that your new category type extends the Category content type.

   ClassObject catco = session.getClassObjectByName("DIRECTORYGROUP");
   codef.setSuperclass(catco);
   
   

4. Create AttributeDefinitions for each attribute pertaining to the category type. Add the AttributeDefinitions to the ClassObjectDefinition.

   AttributeDefinition attdef1 = new AttributeDefinition(session);
   attdef1.setAttributeByUpperCaseName(Attribute.NAME_ATTRIBUTE,
           AttributeValue.newAttributeValue("VicePresident"));
   attdef1.setAttributeByUpperCaseName(Attribute.DATATYPE_ATTRIBUTE,
           AttributeValue.newAttributeValue(Attribute.ATTRIBUTEDATATYPE_
   DIRECTORYOBJECT));
   
   codef.addAttributeDefinition(attdef1);
   
   AttributeDefinition attdef2 = new AttributeDefinition(session);
   attdef2.setAttributeByUpperCaseName(Attribute.NAME_ATTRIBUTE,
           AttributeValue.newAttributeValue("MissionStatement"));
   attdef2.setAttributeByUpperCaseName(Attribute.DATATYPE_ATTRIBUTE,
           AttributeValue.newAttributeValue(Attribute.ATTRIBUTEDATATYPE_STRING));
   
   codef.addAttributeDefinition(attdef2);
   
   

5. Create the ClassObject and Attributes for the new Group class.

   ClassObject groupCo = (ClassObject) session.createSchemaObject(codef);
   

Modifying Group Classes

You can add, remove, and update attributes on a group class after it has been created.

Example 15-21 Using Java to Add, Remove, and Update Attributes on Group Classes

1. Enable Administration Mode.

   session.setAdministrationMode(true);
   
   

2. Get the ClassObject that represents the group class.

   ClassObject co = session.getClassObjectByName("ORGANIZATION");
   
   

3. Add an Attribute to the ClassObject.

   AttributeDefinition attdef1 = new AttributeDefinition(session);
   attdef1.setAttributeByUpperCaseName(Attribute.NAME_ATTRIBUTE,
           AttributeValue.newAttributeValue("OrganizationWorkArea"));
   attdef1.setAttributeByUpperCaseName(Attribute.DATATYPE_ATTRIBUTE,
           AttributeValue.newAttributeValue(
             Attribute.ATTRIBUTEDATATYPE_PUBLICOBJECT));
   co.addAttribute(attdef1);
   
   

4. Remove an Attribute from the ClassObject.

   Attribute att2 = co.getAttributeFromLabel("MISSIONSTATEMENT");
   co.removeAttribute(att2);
   
   

5. Update an Attribute on the ClassObject.

   Attribute att3 = co.getAttributeFromLabel("ORGANIZATIONWORKAREA");
   Collection cdColl = session.getClassDomainCollection();
   ClassDomain cd = (ClassDomain) cdColl.getItems("Folder...");
   att3.setClassDomain(cd);
   

Example 15-22 Using Java to Delete Group Classes

1. Enable Administration Mode.

   session.setAdministrationMode(true);
   
   

2. Get the ClassObject that represents the Group class.

   ClassObject groupCo = session.getClassObjectByName("ORGANIZATION");
   
   

3. Delete the ClassObject by calling the free() method.

   groupCo.free();
   

Creating, Modifying, and Deleting Custom Groups

Once you've defined a custom group class, you can create groups of that class and manage their membership. When creating and managing custom groups, you use many of the same XML tags and Java methods that you would to create DirectoryGroups. However when working with custom group instances, you must identify the class of the group.

Example 15-23 and Example 15-24 illustrate how to create and modify instances of a custom group class with XML. It is not possible to delete instances with XML.

Example 15-25, Example 15-26, and Example 15-27 illustrate how to create, modify and delete an custom group instances with Java.

Example 15-23 Using XML to Create a Custom Group Instance

<?xml version = '1.0' standalone = 'yes'?>
 <ORGANIZATION>
  <NAME>Development</NAME>
  <VICEPRESIDENT RefType = "Name">ztolls</VICEPRESIDENT>
  <MISSIONSTATEMENT>To develop the company products.</MISSIONSTATEMENT>
  <MEMBERS>
    <REF RefType ="Name">czacks</REF>
    <REF RefType = "Name">mwallen</REF>
    <REF RefType = "Name">ztolls</REF>
  </MEMBERS>
 </ORGANIZATION>

Example 15-24 Using XML to Modify a Custom Group Instance

<?xml version = '1.0' standalone = 'yes'?>
 <ORGANIZATION>
  <UPDATE RefType = "Name">Development</UPDATE>
  <VICEPRESIDENT RefType = "Name">lrichards</VICEPRESIDENT>
  <MEMBERS>
    <REF RefType = "Name">lrichards</REF>
  </MEMBERS>
 </ORGANIZATION>

Example 15-25 Using Java to Create a Custom Group Instance

1. Create a new DirectoryGroupDefinition.

   DirectoryGroupDefinition dgDef = new DirectoryGroupDefinition(session);
   
   

2. Specify the class of the group.

   ClassObject co = session.getClassObjectByName("ORGANIZATION");
   dgDef.setClassObject(co);
   
   

3. Set the values of the DirectoryGroup's attributes.

   dgDef.setAttributeByUpperCaseName(DirectoryGroup.NAME_ATTRIBUTE,
            AttributeValue.newAttributeValue(
              "Managers"));
   
   Collection dus = session.getDirectoryUserCollection();
   DirectoryUser du = (DirectoryUser) dus.getItems("tturner")
   dgDef.setAttributeByUpperCaseName("VICEPRESIDENT",
            AttributeValue.newAttributeValue(du));
   
   dgDef.setAttributeByUpperCaseName("MISSIONSTATEMENT",
            AttributeValue.newAttributeValue(
              "To develop the company products."));
   
   

4. Pass the DirectoryGroupDefinition to the LibrarySession to create a new DirectoryGroup instance.

   DirectoryGroup dg = (DirectoryGroup) session.createPublicObject(dgDef);
   
   

5. Obtain the DirectoryUsers who belong in the DirectoryGroup.

   Collection groupDus = session.getDirectoryUserCollection();
   
   int i;
   int icount = groupDus.getItemCount();
   for (i = 0; i < icount; i++)
   {
     du = (DirectoryUser) groupDus.getItems(i);
   
   

6. Add the DirectoryUsers to the DirectoryGroup.

       dg.addMember(du);
   }
   

Example 15-26 Using Java to Modify a Custom Group Instance

/*
 * The following example adds a DirectoryUser to a custom group. 
 */

1. Search for the custom group instance. Specify the class of the group.

   Selector s = new Selector(session);
   s.setSearchClassname("ORGANIZATION");
   s.setSearchSelection("NAME = 'Development'");
   
   

2. Fetch the group instance. Since the custom group extends DirectoryGroup, the instance can be declared as a DirectoryGroup.

   DirectoryGroup dg = (DirectoryGroup) s.getItems(0);
   
   

3. Add a DirectoryUser to the group.

   DirectoryUser du = session.getDirectoryUser();
   dg.addMembers(du);
   
   

Example 15-27 Using Java to Delete a Custom Group Instance

/*
 * The following example deletes all instances of a custom group. 
 */

1. Search for all custom group instances. Specify the class of the group.

   Selector s = new Selector(session);
   s.setSearchClassname("ORGANIZATION");
   LibraryObject[] dgs = s.getItems();
   
   

2. Fetch the group instances. Since the custom group extends DirectoryGroup, the instance can be declared as a DirectoryGroup.

   DirectoryGroup dg;
   
   int i;
   int icount = (dgs == null) ? 0 : dgs.length;
   for (i = 0; i < icount; i++)
   {
     dg = (DirectoryGroup) dgs[i];
   
   

3. Delete the DirectoryGroup.

     dg.free();
   }
   

   
   

   NOTE: Deleting a custom group instances does not automatically delete the DirectoryUsers in that group. See "Creating, Modifying, and Deleting DirectoryUsers and PrimaryUserProfiles" to learn how to delete DirectoryUsers.

Authenticating DirectoryUsers

When a user tries to access information in the repository, Oracle 9iFS first authenticates the user's credentials. Users are authenticated in the following steps:

1. The user supplies credentials via the application being used to log into the repository.

2. The application instantiates a class in the oracle.ifs.common package to hold the credentials. The application can select from a variety of classes depending on the type of credentials being used to authenticate the user. CleartextCredential is most commonly used for managing credentials.

3. The application passes the credentials to the LibraryService to attempt to establish a session with the repository.

4. The LibraryService retrieves the a DirectoryUser instance that corresponds to the user's DistinguishedName specified. If a DirectoryUser instance does not exist, the LibraryService refuses to connect.

5. If a DirectoryUser instance exists, the LibraryService passes the user's credentials to the credential manager identified in the DirectoryUser CredentialManager attribute.

   
   

   NOTE: This release of Oracle 9iFS provides a built-in credential manager that is used to authenticate all users. Support for external credential managers is planned for a future release of Oracle 9iFS.

6. The credential manager verifies the credentials. If the credentials are valid, the LibraryService creates a LibrarySession that connects the application to Oracle 9iFS. The LibrarySession serves as a factory for all operations performed by the user in the repository (e.g., creating, updating and deleting repository objects).

   
   

   NOTE: Example 15-28 illustrates how an application can authenticate a user using a CleartextCredentials. Chapter 4, "Creating an Oracle Internet File System Document" discusses more fully other aspects of working with LibraryServices and LibrarySessions that are beyond the scope of this section.

Example 15-28 Authenticating a User using Java

//Connect to Oracle 9iFS.
LibraryService service = 
       LibraryService.startService("IfsDefault", "ifssys");
ConnectOptions cop = new ConnectOptions();
CleartextCredential cred = 
       new CleartextCredential("system", "manager");
LibrarySession session = service.connect(cred, cop);

Managing Access to PublicObjects

This section describes how Oracle 9iFS uses AccessControlLists to manage access to PublicObjects. It covers the following topics:

• How AccessControlLists Work

• AccessControlList Structure

• Creating, Modifying, and Deleting AccessControlLists

• Applying ACLs to PublicObjects

• Managing Access to AccessControlLists

How AccessControlLists Work

Access to every PublicObject is managed by an AccessControlList. An AccessControlList is a list of users and groups who have been granted or revoked access permissions to the PublicObject. Each time a user or group is granted or revoked access permissions, a new entry is created in the AccessControlList. The entry records the Grantee (i.e., the user or group), the AccessLevel (i.e., a set of permissions), and whether the permissions are being granted or revoked.

Resolving Access Permissions

If the Grantee is a group, then the entry applies to all users belonging to that group or any of its subgroups. If multiple AccessControlEntries apply to a user, Oracle 9iFS resolves the user's effective access permissions by aggregating the entries in the order that they were created in the AccessControlList. For example, if a user was granted Discover and GetContent in the first entry, then granted SetAttribute and SetContent in a second, and then revoked SetContent in a third, Oracle 9iFS would resolved the effective access permissions to Discover, GetContent and SetAttribute.

Sharing AccessControlLists

AccessControlLists exist independently in the repository, and can be assigned to one or more PublicObjects. An AccessControlList is assigned to a PublicObject by referencing the AccessControlList in the PublicObject's ACL attribute.

Each AccessControlList possesses an attribute, Shared, that indicates if the AccessControlList is private to one PublicObject or shared between multiple PublicObjects. Sharing AccessControlLists makes it easy to control access to many PublicObjects that have similar security constraints. For example, you might create an AccessControlList to control access to all PublicObjects pertaining to a particular project. You can define who can read the project documents, who has been designated as a content contributor in the project, and who manages the folders in the project work area. Subsequently, you can share the AccessControlList across all project documents and folders. This allows you to maintain project security once in a single AccessControlList, instead of separately for each document and folder.

Defining System-Wide Security Levels

Administrators can create a special type of AccessControlList, a SystemAccessControlList, that defines access permissions that can be applied by any Oracle 9iFS user to information in the repository. Oracle 9iFS is installed with four SystemAccessControlLists: Private, Protected, Published, and Public.

Defining Custom Permissions

Oracle 9iFS is installed pre-configured with a standard set of permissions that can be granted or revoked in an AccessControlList, including Discover, GetContent, SetAttribute, SetContent, Delete, and many others. Oracle 9iFS also allows you to define custom access permissions, that is ExtendedPermissions, and use them to control if users can perform tasks implemented by custom application code. For example, you can define an custom permission for the ability to digitally sign a document to support an application for managing legal contracts.

Defining Broader Levels of Access

The permissions defined out-of-the-box with Oracle 9iFS give you fine grained control over how information is accessed. Oracle 9iFS also allows you to define broader permission levels by grouping access permissions into PermissionBundles. For example, you might group the Discover, Add Item, and Remove Item permissions together into a ModifyFolderPermissionBundle to more easily grant users the ability to modify folders.

AccessControlList Structure

Each AccessControlList is represented by an instance of the AccessControlList class. Each entry that grants or revokes access permissions to a user or group is represented by an instance of the AccessControlEntry class. Each AccessControlEntry possesses an attribute, ACL, that references the AccessControlList to which it belongs. The AccessControlEntry also possesses attributes for recording which permissions were granted or revoked to which user or group. An AccessControlEntry can reference an AccessLevel, one or more ExtendedPermissions, and PermissionBundles. AccessLevels represent a set of standard permissions defined by Oracle 9iFS. ExtendedPermissions represent custom permissions that you have defined. PermissionBundles represent higher levels of access comprised of a group of permissions.

Figure 15-2 illustrates the structure of an AccessControlList.

Figure 15-2 AccessControlList Structure

AccessControlList

The AccessControlList class serves as the primary interface for granting and revoking permissions to users and groups in the list. Table 15-7 lists the most commonly used attributes and methods on AccessControlList.

Table 15-7 AccessControlList Attributes and Methods

AccessControlEntries

The AccessControlEntry class possesses attributes and methods for defining each entry in the AccessControlList: the grantee, the permissions, and whether the permissions are being granted or revoked. The relationship between the AccessControlList and the AccessControlEntry is maintained by two attributes on the AccessControlEntry: ACL and SortSequence. The ACL attribute references the AccessControlList to which the AccessControlEntry belongs. The SortSequence attribute determines the AccessControlEntries relative position to other AccessControlEntries in the AccessControlList. The AccessControlEntries SortSequence is used to determine the precedence of the permissions that they grant or revoke.

Table 15-8 lists the most commonly used attributes and methods on AccessControlEntry.

Table 15-8 AccessControlEntry Attributes and Methods

AccessLevels

Oracle 9iFS uses the AccessLevel class to represent a set of standard permissions that have been granted or revoked in an AccessControlEntry. The AccessLevel class possesses constants to represent each standard permission defined by Oracle 9iFS. Table 15-9 lists the standard permissions that are pertinent to PublicObjects.

Table 15-9 PublicObject Permissions

• To learn more about Relationships, see Chapter 6, "Applying Arbitrary Metadata and Behavior".

• To learn more about Versioning, see Chapter 14, "Implementing Versioning in a Custom Application".

Table 15-10 lists the most commonly used methods on AccessLevel.

Table 15-10 AccessLevel Attributes and Methods

ExtendedPermissions

Oracle 9iFS allows you to define custom permissions as instances of the ExtendedPermissions class. For example, you can define an custom permission for the ability to digitally sign a document to support an application for managing legal contracts. To define the custom permission, you would create an instance of the ExtendedPermission class that is uniquely named (e.g., Sign) to identify the custom permission. Subsequently, you can grant and revoke the ExtendedPermission in an AccessControlEntry by constructing an AccessLevel to hold the ExtendedPermissions.

The AccessLevel class in the Java API provides a set of methods for working with ExtendedPermissions. Table 15-11 lists the methods on AccessLevel that are used to work with ExtendedPermissions.

Table 15-11 AccessLevel methods related to ExtendedPermissions

After an ExtendedPermission has been applied to an AccessControlList, you can build custom applications that use the ExtendedPermission to control how users can work with PublicObjects. Your application would implement an override to check if a user has been granted the ExtendedPermission on a PublicObject, and then allow or disallow the user to perform operations based on its findings.

Table 15-12 lists the methods on S_PublicObject that are used to work with ExtendedPermissions.

Table 15-12 S_PublicObject Methods related to ExtendedPermissions

PermissionBundles

AccessLevel provides an extensive list of permissions that give you fine control over how information is accessed. However, you may want to define security levels that make it easier for users to apply broader access permissions on PublicObjects.

Oracle 9iFS allows you to define broader security levels as instances of the class PermissionBundle, that are stored persistently in Oracle 9iFS. For example, you might group the Discover, Add Item, and Remove Item permissions together into a ModifyFolderPermissionBundle to more easily grant users the ability to modify folders.

Table 15-13 lists the most commonly used attributes and methods of PermissionBundle.

Table 15-13 PermissionBundle Attributes and Methods

Creating, Modifying, and Deleting AccessControlLists

Oracle 9iFS provides three methods for creating, modifying and deleting AccessControlLists:

• XML, creating XML files that automatically define AccessControlLists when imported into Oracle 9iFS

• Java, programmatically defining AccessControlLists via Oracle 9iFS Java API

• Oracle 9iFS Clients, defining AccessControlLists in the Oracle 9iFS windows and Web clients.

This section discusses how to define AccessControlLists with XML and Java. For instructions on defining AccessControlLists in the Oracle 9iFS clients, consult the Oracle 9iFS Online Help facility for each client.

Using XML to Create and Modify AccessControlLists

You can use XML files to define AccessControlLists in Oracle 9iFS. When the XML file is imported into Oracle 9iFS, the IfsSimpleXmlParser automatically uses it to create or modify a AccessControlList and the AccessControlEntry instances. Oracle 9iFS does not support deleting AccessControlLists using XML.

Example 15-29 and Example 15-30 illustrate how to create and modify AccessControlLists with XML.

Example 15-29 Using XML to Create an AccessControlList

<?xml version = '1.0' standalone = 'yes'?>
<ACCESSCONTROLLIST>
  <NAME>ContentManagementProjectACL</NAME>
  <DESCRIPTION>
     ACL used to manage access to all information 
     pertaining to the Content Management project.
  </DESCRIPTION>
  <OWNER RefType = "Name">guest</OWNER>
  <ACEs>
    <ACCESSCONTROLENTRY>
      <GRANTEE ClassName="DirectoryUser" RefType="Name">
         guest
      </GRANTEE>
      <ACCESSLEVEL>
          <DISCOVER> true </DISCOVER>
          <GETCONTENT> true </GETCONTENT>
          <SETATTRIBUTE> true </SETATTRIBUTE>
          <SETCONTENT> true </SETCONTENT>
          <DELETE> true </DELETE>
      </ACCESSLEVEL>
      <GRANTED>true</GRANTED>
    </ACCESSCONTROLENTRY>
  </ACEs>
</ACCESSCONTROLLIST>

Example 15-30 Using XML to Modify an AccessControlList

<?xml version = '1.0' standalone = 'yes'?>
<ACCESSCONTROLLIST>
  <UPDATE RefType = "Name">ContentManagementProjectACL</UPDATE>
    <OWNER RefType = 'Name'>system</OWNER>
  <ACEs>
    <ACCESSCONTROLENTRY>
      <GRANTEE ClassName='DirectoryUser' RefType="Name"> guest </GRANTEE>
      <ACCESSLEVEL>
          <SETATTRIBUTE> true </SETATTRIBUTE>
          <SETCONTENT> true </SETCONTENT>
          <DELETE> true </DELETE>
      </ACCESSLEVEL>
      <GRANTED>false</GRANTED>
    </ACCESSCONTROLENTRY>
  </ACEs>
</ACCESSCONTROLLIST>

Each element in the XML configuration file is used to specify the value for the attributes of the AccessControlList and AccessControlEntry instances.

Example 15-14 lists each of the XML elements in a AccessControlList configuration file. The table specifies the Java class and attribute in the Oracle 9iFS Java API that corresponds to the element, how the element is used, and any valid XML attributes for the element

.

Table 15-14 AccessControlList XML Configuration File Elements

Using Java to Create, Modify, and Delete AccessControlLists

The Oracle 9iFS Java API provides a more robust interface for manipulating each component of an AccessControlList. Example 15-31, Example 15-32, and Example 15-33 illustrate how to create, modify, and delete AccessControlLists with the Java API.

Example 15-31 Using Java to Create an AccessControlList

1. Assume that the application has already obtained the DirectoryUser who will be granted permissions in the AccessControlList.

   DirectoryGroup du = ...
   
   

2. Create a new AccessControlListDefinition.

   AccessControlListDefinition aclDef = new AccessControlListDefinition(session);
   
   

3. Set the values of the AccessControlList attributes.

   aclDef.setAttributeByUpperCaseName("NAME",
            AttributeValue.newAttributeValue(
              "ContentManagementProjectACL"));
   
   aclDef.setShared(TRUE);
   
   

4. Pass the AccessControlListDefinition to the LibrarySession to create the new AccessControlList.

   AccessControlList acl = (AccessControlList) session.createPublicObject(aclDef);
   
   

5. Create an AccessControlEntryDefinition to grant permissions to the DirectoryUser. Set the AccessControlEntryDefinition on the AccessControlList.

   AccessControlEntryDefinition aceDef1 = 
                new AccessControlEntryDefinition(session);
   aceDef1.setGrantee(du);
   
   String[] levels = {"Discover",
                      "GetContent",
                      "SetAttribute", 
                      "SetContent",
                      "Delete"};
   AccessLevel al1 = new AccessLevel(levels);
   aceDef1.setDistinctAccessLevel(al1);
   
   acl.grantAccess(aceDef1);
   
   

6. Create an AccessControlEntryDefinition to revoke the Delete permission from the DirectoryUser. Set the AccessControlEntryDefinition on the AccessControlList.

   AccessControlEntryDefinition aceDef2 = 
                new AccessControlEntryDefinition(session);
   aceDef2.setGrantee(du);
   
   AccessLevel al2 = new AccessLevel(AccessLevel.ACCESSLEVEL_DELETE);
   aceDef2.setDistinctAccessLevel(al2);
   
   acl.revokeAccess(aceDef2);
   

Example 15-32 Using Java to Modify an AccessControlList

1. Assume that the application has already obtained the AccessControlList, and the DirectoryUser who will be granted new permissions on the AccessControlList.

   AccessControlList acl = ...
   DirectoryUser du = ...
   
   

2. Create a new AccessControlEntryDefinition to grant all permissions to the user.

   AccessControlEntryDefinition aceDef = 
        new AccessControlEntryDefinition(session);
   aceDef.setGrantee(du);
   aceDef.setGranted(true);
   
   AccessLevel al = new AccessLevel();
   al.enableAllStandardPermissions();
   aceDef.setDistinctAccessLevel(al);
   
   

3. Specify that new the AccessControlEntry should be inserted at the top of the AccessControlList so that any AccessControlEntries that revoke permissions from members of that group maintain precedence when resolved by Oracle 9iFS.

   AccessControlEntry firstAce = acl.getAccessControlEntrys(0);
   aceDef.setInsertBeforeAccessControlEntry(firstAce);
   
   

4. Add the AccessControlEntry to the AccessControlList.

   acl.addAccessControlEntry(aceDef);
   

Example 15-33 Deleting an AccessControlList with Java

1. Assume that the application has already obtained the AccessControlList.

   AccessControlList acl = ...
   
   

2. Delete the AccessControlList. Oracle 9iFS will automatically delete all AccessControlEntries in the AccessControlList.

   acl.free();
   

Applying ACLs to PublicObjects

An AccessControlList must be applied to every PublicObject created in Oracle 9iFS. An AccessControlList can be applied in three ways:

• Explicitly Setting the ACL Attribute. An AccessControlList is usually applied to a PublicObject by setting the PublicObject's ACL attribute. The ACL attribute references the AccessControlList that should be used to manage access to the PublicObject.

• Defaulting the ACL on a PublicObject. If the ACL attribute is not explicitly set when a new PublicObject is created, Oracle 9iFS will automatically set the ACL attribute to the creator's default AccessControlList for that class of object. User's who possess the permission to Grant access to the PublicObject, including the PublicObject's owner and any system administrator, can update the ACL attribute after it has been created.

• Applying ACLs by Proxy. As an alternative to using the ACL attribute to apply an AccessControlList, you can apply another PublicObject's AccessControlList by proxy. When one PublicObject is specified as the SecuringPublicObject for another PublicObject, the securing PublicObject's AccessControlList is used to control access to the other PublicObject.

This section illustrates how use XML and Java to apply an AccessControlList to a PublicObject.

Explicitly Setting the ACL Attribute

This section illustrates how to apply an AccessControlList to a PublicObject by explicitly setting the ACL attribute. Example 15-34,Example 15-35, and Example 15-36 illustrate how to use XML to set the ACL attribute. Example 15-37 and Example 15-38 illustrate how to use Java to set the ACL attribute.

Example 15-34 Using XML to Apply an ACL to a New PublicObject

<?xml version="1.0" standalone="yes"?>
<FOLDER>
  <NAME>My Work-in-Progress</NAME>
  <DESCRIPTION>
     ACL used to manage access to all information pertaining to 
     the Content Management project.
  </DESCRIPTION>
  <ACL>
    <NAME>MyCMWorkInProgressACL</NAME>
    <ACL RefType = "Name">Private</ACL>
    <ACEs>
      <ACCESSCONTROLENTRY>
        <GRANTEE ClassName='DirectoryGroup' RefType="Name">
           CMProjectGroup
        </GRANTEE>
        <ACCESSLEVEL>
          <DISCOVER> true </DISCOVER>
          <GETCONTENT> true </GETCONTENT>
        </ACCESSLEVEL>
        <GRANTED>true</GRANTED>
      </ACCESSCONTROLENTRY>
    </ACEs>
  </ACL>
</FOLDER>

Example 15-35 Using XML to Apply an Existing ACL to a New PublicObject

<?xml version="1.0" standalone="yes"?>
<FOLDER>
    <NAME>Content Management Research</NAME>
    <ACL RefType = "Name">
      ContentManagementProjectACL
    </ACL>
    <FOLDERPATH>.</FOLDERPATH>
</FOLDER>

Example 15-36 Using XML to Modify the ACL for an Existing PublicObject

<?xml version="1.0" standalone="yes"?>
<FOLDER>
    <UPDATE RefType = "Name">Content Management Research</UPDATE>   
    <ACL RefType = "Name">
      Public
    </ACL>
    <FOLDERPATH>.</FOLDERPATH>
</FOLDER>

Example 15-37 Using Java to Apply an Existing ACL to a New PublicObject

1. Fetch the AccessControlList.

   Collection aclColl = session.getSystemAccessControlListCollection();
   AccessControlList acl = 
       (AccessControlList) aclColl.getItems("Protected");
   
   

2. Create a FolderDefinition and set the ACL attribute.

   FolderDefinition fd = new FolderDefinition(session);
   fd.setAttributeByUpperCaseName(Folder.NAME_ATTRIBUTE, 
        AttributeValue.newAttributeValue("Collateral"));
   fd.setAttributeByUpperCaseName(Folder.ACL_ATTRIBUTE, 
        AttributeValue.newAttributeValue(acl));
   
   

3. Pass the FolderDefinition to the LibrarySession to create a new Folder.

   Folder f = (Folder) session.createPublicObject(fd);
   

Example 15-38 Using Java to Apply a Folder's ACL Recursively to Subfolders

/** This example illustrates how to recursively 
 * apply an ACL to multiple PublicObjects.
 */

1. Enable administration mode to ensure that the user will have implicit permission to set the ACL for any subfolder found. Otherwise, the user may not be able to apply an ACL if the user is not the owner of the subfolder, or unless the user has been granted the Grant permission in the subfolder's ACL.

   session.setAdministrationMode(true);
   
   

2. Obtain the parent folder whose ACL will be recursively applied to its subfolders.

   PublicObject parentFolder, item;
   
   FolderPathResolver fpr = new FolderPathResolver(session);
   fpr.setRootFolder();
   parentFolder = fpr.findPublicObjectByPath("/public");
   
   

3. Obtain the parent folder's ACL.

   AccessControlList acl = parentFolder.getAcl();
   
   

4. Obtain an array of all subfolders.

   PublicObject[] folderItems = parentFolder.getItems();
   
   for (int i = 0 ; i < parentFolder.getItemCount(); i++ )
   {
   

5. If the item is a subfolder, apply the parent folder's ACL.

      item = ( PublicObject ) folderItems[i];
      if( item instanceof Folder )
      {
         item.setAcl( acl );
      }
   }
   

Defaulting the ACL on a PublicObject

If the ACL attribute is not explicitly set when a PublicObject is created, Oracle 9iFS will automatically set the ACL to reference the user's default AccessControlList for that class of object. The default AccessControlList is identified in the user's PrimaryUserProfile. The PrimaryUserProfile possesses two attributes that hold the user's default AccessControlLists:

• DefaultACLs, used to specify default AccessControlLists for non-versioned PublicObjects

• DefaultVersionedACLs, used to default AccessControlLists for versioned PublicObjects

Both attributes reference a PropertyBundle that consist of a list of Properties, which are name/value pairs. The Name of each Property specifies the class of object to which the AccessControlList applies (e.g., DOCUMENT, FOLDER). The Property's value references the AccessControlList that should be applied by default for instances of that class.

To learn how to specify a default AccessControlList for a user, see the "Profiling Users"section. Example 15-5 illustrates how to add an AccessControlList to the DefaultACLs PropertyBundle in a user's PrimaryUserProfile with Java.

Applying ACLs by Proxy

Oracle 9iFS provides an alternative method for controlling access to PublicObjects. Instead of applying an AccessControlList directly to the PublicObject by setting the ACL attribute, you can apply another PublicObject's AccessControlList by setting the SecuringPublicObject attribute.

Every PublicObject includes an attribute, SecuringPublicObject, that can be optionally used to specify another PublicObject that is used to secure this PublicObject. When the SecuringPublicObject attribute references another PublicObject, Oracle 9iFS will use that PublicObject's AccessControlList instead.

Proxy security is particularly useful when working with versioned PublicObjects. For example, you can set the SecuringPublicObject for all versions of a document to reference the document's Family. This enables you to maintain security for all versions of the document in one place, rather than separately on each version.

Example 15-39 Setting the SecuringPublicObject attribute on a PublicObject with Java

1. Create the DocumentDefinition.

   DocumentDefinition dd = new DocumentDefinition(session);
   dd.setAttribute(Document.NAME_ATTRIBUTE, 
      AttributeValue.newAttributeValue(docname));
   
   Collection formatColl = session.getFormatCollection();
   Format fmt = (Format) formatColl.getItems("Text");
   dd.setFormat(fmt);
   
   dd.setContent("A new versioned document.");
   
   Folder hf = session.getUser().getPrimaryUserProfile().getHomeFolder();
   dd.setAddToFolderOption(hf);
   
   

2. Create the VersionDescriptionDefinition.

   VersionDescriptionDefinition vdd = new VersionDescriptionDefinition(session);
   vdd.setAttribute(VersionDescription.NAME_ATTRIBUTE, 
       AttributeValue.newAttributeValue("Versioning1 VersionDescription"));
   vdd.setAttribute("VERSIONLABEL", 
       AttributeValue.newAttributeValue("Version 1.0"));
   vdd.setPublicObjectDefinition(dd);
   
   

3. Pass the VersionDescriptionDefinition to the LibrarySession to implicitly create the Document, VersionDescription, VersionSeries, and Family, and return the VersionDescription.

   VersionDescription vd = (VersionDescription)session.createPublicObject(vdd);
   
   

4. Use the VersionDescription to fetch the other components.

   Family f = vd.getFamily();
   VersionSeries vs = vd.getVersionSeries();
   Document d = (Document) vd.getResolvedPublicObject();
   
   

5. Set the SecuringPublicObject for the VersionDescription and VersionSeries to be the document's Family.

   d.setSecuringPublicObject(f);
   vd.setSecuringPublicObject(f);
   vs.setSecuringPublicObject(f);
   

Managing Access to AccessControlLists

Any end user can create an AccessControlList. When a user creates an AccessControlList, Oracle 9iFS automatically designates the user as the owner of that AccessControlList.

As the owner, the user can control how the AccessControlList can be accessed by other users. The owner can specify who can discover the AccessControlList and apply it to their PublicObjects. The owner can also specify who can modify the AccessControlList to grant or revoke permissions. The owner of the AccessControlList determines who can discover and modify it by setting the AccessControlList's ACL attribute, just like any other PublicObject. For example, to prevent other users from discovering the AccessControlList and using it to manage access to their PublicObjects, the owner can set the AccessControlList's ACL attribute to reference the Private SystemAccessControlList. In another case, the owner can share the responsibility of maintaining an AccessControlList by applying an AccessControlList that grants other users the Grant permission. The Grant permission is used to determine who can add new AccessControlEntries to an AccessControlList.

Example 15-40 Granting Access to an AccessControlList with XML

<?xml version = '1.0' standalone = 'yes'?>
<OBJECTLIST>

1. Create an AccessControlList to control access to other AccessControlLists.

    <ACCESSCONTROLLIST>
     <NAME>CMProjectACLAdministration</NAME>
     <DESCRIPTION>ACL used to allow the Content Managmeent project members to use 
   the AccessControlList, and project leads to manage 
   AccessControlLists.</DESCRIPTION>
     <OWNER RefType = "Name">tturner</OWNER>
     <ACEs>
       <ACCESSCONTROLENTRY>
         <GRANTEE ClassName="DirectoryGroup" RefType="Name">
            CMProjectGroup
         </GRANTEE>
         <ACCESSLEVEL>
             <DISCOVER> true </DISCOVER>
         </ACCESSLEVEL>
         <GRANTED>true</GRANTED>
       </ACCESSCONTROLENTRY>
       <ACCESSCONTROLENTRY>
         <GRANTEE ClassName="DirectoryGroup" RefType="Name">
            CMProjectLeads
         </GRANTEE>
         <ACCESSLEVEL>
             <GRANT> true </GRANT>
         </ACCESSLEVEL>
         <GRANTED>true</GRANTED>
       </ACCESSCONTROLENTRY>
     </ACEs>
    </ACCESSCONTROLLIST>
   
   

2. Set the ACL attribute on an AccessControlList

    <ACCESSCONTROLLIST>
     <NAME>ContentManagementProjectACL</NAME>
     <DESCRIPTION>
        ACL used to manage access to all information 
        pertaining to the Content Management project.
     </DESCRIPTION>
     <OWNER RefType = "Name">tturner</OWNER>
     <ACL RefType = "Name">CMProjectACLAdministration</ACL>
     <ACEs>
       <ACCESSCONTROLENTRY>
         <GRANTEE ClassName="DirectoryGroup" RefType="Name">
            CMProjectGroup
         </GRANTEE>
         <ACCESSLEVEL>
             <DISCOVER> true </DISCOVER>
             <GETCONTENT> true </GETCONTENT>
             <SETCONTENT> true </SETCONTENT>
             <DELETE> true </DELETE>
         </ACCESSLEVEL>
         <GRANTED>true</GRANTED>
       </ACCESSCONTROLENTRY>
     </ACEs>
    </ACCESSCONTROLLIST>
   
   </OBJECTLIST>
   

Managing Access to ClassObjects

You can control which users and groups can create and search for specific classes of information with ClassAccessControlLists.

This section discusses the following:

• How ClassAccessControlLists Work

• Creating ClassAccessControlLists

• Applying ClassAccessControlLists to ClassObjects

How ClassAccessControlLists Work

ClassAccessControlList is a subclass of AccessControlList that is only applied to ClassObjects. Since ClassAccessControlList extends AccessControlList, it possesses all of the attributes and behaviors described in "How AccessControlLists Work" and "AccessControlList Structure". In addition, ClassAccessControlLists possess the attribute, UniqueName, that is used to uniquely identify the ClassAccessControlList by a string. Oracle 9iFS also maintains a collection of ClassAccessControlLists that make it easy to retrieve them from a LibrarySession without having to search the repository.

A ClassAccessControlList is applied to a ClassObject by referencing the ClassAccessControlList in the ClassACL attribute on the ClassObject. ClassAccessControlLists apply two special permissions to ClassObjects: Create and SelectorAccess. These permissions are represented by constants on the AccessLevel class in the Oracle 9iFS Java API.

Table 15-15 lists the AccessLevel constants and their usage

Table 15-15 ClassObject Permissions

Creating ClassAccessControlLists

ClassAccessControlLists are created in the same manner as AccessControlLists. The key differences are that:

• The ClassAccessControlList class is instantiated

• Only the AccessLevel_Create and AccessLevel_SelectorAccess permissions are included.

• A UniqueName is automatically generated.

Example 15-41 and Example 15-42 illustrate how to create a ClassAccessControlList with XML and Java.

Example 15-41 Creating a ClassAccessControList with XML

<?xml version = '1.0' standalone = 'yes'?>
<CLASSACCESSCONTROLLIST>
  <NAME>ProductCatalogClassACL</NAME>
  <DESCRIPTION>
    ClassACL used to manage access any custom classes 
    created for the ProductCatalog application.
  </DESCRIPTION>
  <ACEs>
    <ACCESSCONTROLENTRY>
      <GRANTEE ClassName="DirectoryGroup" RefType="Name">
         CMProjectGroup
      </GRANTEE>
      <ACCESSLEVEL>
          <SELECTORACCESS> true </SELECTORACCESS>
      </ACCESSLEVEL>
      <GRANTED>true</GRANTED>
    </ACCESSCONTROLENTRY>
    <ACCESSCONTROLENTRY>
      <GRANTEE ClassName="DirectoryGroup" RefType="Name">
         CMProjectLeads
      </GRANTEE>
      <ACCESSLEVEL>
          <CREATE> true </CREATE>
      </ACCESSLEVEL>
      <GRANTED>true</GRANTED>
    </ACCESSCONTROLENTRY>
  </ACEs>
</CLASSACCESSCONTROLLIST>

Example 15-42 Creating a ClassAccessControList with Java

1. Assume that the application has already obtained the DirectoryUsers and DirectoryGroups who will be granted permissions in the AccessControlList.

   DirectoryGroup CMGroup = ...
   DirectoryGroup CMLeads = ...
   
   

2. Administration Mode must be enabled to create a ClassAccessControlList.

   session.setAdministrationMode(true);
   
   

3. Create a new ClassAccessControlListDefinition.

   ClassAccessControlListDefinition aclDef = 
         new ClassAccessControlListDefinition(session);
   
   

4. Set the values of the ClassAccessControlList attributes.

   aclDef.setAttributeByUpperCaseName("NAME",
            AttributeValue.newAttributeValue(
              "ProductCatalogClassACL"));
   aclDef.setShared(TRUE);
   
   

5. Pass the ClassAccessControlListDefinition to the LibrarySession to create the new ClassAccessControlList and AccessControlEntry instances.

   ClassAccessControlList classAcl = 
        (ClassAccessControlList) session.createPublicObject(aclDef);
   
   

6. Create an AccessControlEntryDefinition to grant members of the Content Management group the ability to search for instances of the classes.

   AccessControlEntryDefinition aceDef1 = 
                new AccessControlEntryDefinition(session);
   aceDef1.setGrantee(dg1);
   
   AccessLevel al1 = new AccessLevel(AccessLevel.ACCESSLEVEL_SELECTORACCESS);
   aceDef1.setDistinctAccessLevel(al1);
   
   acl.grantAccess(aceDef1);
   
   

7. Create an AccessControlEntryDefinition to grant members of the Content Management leads group the ability to create instances of the classes.

   AccessControlEntryDefinition aceDef2 = 
                new AccessControlEntryDefinition(session);
   aceDef2.setGrantee(dg2);
   
   AccessLevel al2 = new AccessLevel(AccessLevel.ACCESSLEVEL_CREATE);
   aceDef2.setDistinctAccessLevel(al2);
   
   acl.grantAccess(aceDef2);
   

Applying ClassAccessControlLists to ClassObjects

You can apply ClassAccessControlLists to ClassObjects by referencing the ClassAccessControlList in the ClassObject' ClassACL attribute.

Example 15-43 illustrates how to apply an existing ClassAccessControlList to a new ClassObject.

Example 15-43 Using XML to Apply a ClassAccessControlList to a ClassObject

<?xml version="1.0" standalone="yes"?>
<CLASSOBJECT>
    <NAME>Image</NAME>   
    <SUPERCLASS RefType = "Name">Document</SUPERCLASS>  
    <CLASSACL RefType = "Name">ProductCatalogClassACL</CLASSACL>
    <ATTRIBUTES>
        <ATTRIBUTE>
            <NAME>Width</NAME>
            <DATATYPE>Integer</DATATYPE>
        </ATTRIBUTE>
        <ATTRIBUTE>
            <NAME>Height</NAME>
            <DATATYPE>Integer</DATATYPE>
        </ATTRIBUTE>
    </ATTRIBUTES>
</CLASSOBJECT>

Example 15-44 Using Java to Apply a ClassAccessControlList to a ClassObject

1. Enable Administration Mode.

   session.setAdministrationMode(true);
   
   

2. Create the ClassObjectDefinition to hold the values for the new ClassObject.

   ClassObjectDefinition codef = new ClassObjectDefinition(session);
   codef.setAttributeByUpperCaseName(ClassObject.NAME_ATTRIBUTE,
           AttributeValue.newAttributeValue("IMAGE"));
   codef.setAttributeByUpperCaseName(ClassObject.DESCRIPTION_ATTRIBUTE,
          AttributeValue.newAttributeValue("Image files"));
   
   ClassObject superClass = session.getClassObjectByName("DOCUMENT");
   codef.setSuperclass(superClass);
   
   AttributeDefinition adef1 = new AttributeDefinition(session);
   adef1.setAttributeByUpperCaseName(Attribute.NAME_ATTRIBUTE,
           AttributeValue.newAttributeValue("Height")); 
   adef1.setAttributeByUpperCaseName(Attribute.DESCRIPTION_ATTRIBUTE, 
        	AttributeValue.newAttributeValue("Image Height"));
   adef1.setAttributeByUpperCaseName(Attribute.DATATYPE_ATTRIBUTE,
        AttributeValue.newAttributeValue(Attribute.ATTRIBUTEDATATYPE_INTEGER));
   adef1.setAttributeByUpperCaseName(Attribute.REQUIRED_ATTRIBUTE,  
                AttributeValue.newAttributeValue(false));
   codef.addAttributeDefinition(adef1);
   
   AttributeDefinition adef2 = new AttributeDefinition(session);
   adef2.setAttributeByUpperCaseName(Attribute.NAME_ATTRIBUTE,
           AttributeValue.newAttributeValue("Width")); 
   adef2.setAttributeByUpperCaseName(Attribute.DESCRIPTION_ATTRIBUTE, 
        	AttributeValue.newAttributeValue("Image Width"));
   adef2.setAttributeByUpperCaseName(Attribute.DATATYPE_ATTRIBUTE,
        AttributeValue.newAttributeValue(Attribute.ATTRIBUTEDATATYPE_INTEGER));
   adef2.setAttributeByUpperCaseName(Attribute.REQUIRED_ATTRIBUTE,  
                AttributeValue.newAttributeValue(false));
   codef.addAttributeDefinition(adef2);
   
   

3. Fetch the ClassAccessControlList from the ClassAccessControlList collection, and apply it to the ClassObjectDefinition.

   Collection classAclColl = session.getClassAccessControlListCollection();
   ClassAccessControlList classACL = 
        (ClassAccessControlList) classAclColl.getItems("PRODUCTCATALOGCLASSACL");
   codef.setAttributeByUpperCaseName(ClassObject.CLASSACL_ATTRIBUTE, 
       AttributeValue.newAttributeValue(classACL));
   
   

4. Pass the ClassObjectDefinition to the LibrarySession to create the ClassObject and Attribute instances for the content type.

   ClassObject classObj = (ClassObject) session.createSchemaObject(codef);	
   

Granting Implicit Access to Objects

Oracle 9iFS implicitly grants full access to information in two cases:

• Administration, if the user is a system administrator.

• Ownership, if the user is the owner of an object.

Administration

System Administrators are implicitly granted full access to all information in the repository. Any user can be given administration privileges by setting the AdminEnabled attribute on the DirectoryUser object that represents that user. Subsequently, that user can obtain full access to all information in the repository by enabling Administration Mode in their session with Oracle 9iFS.

Example 15-45 and Example 15-46 illustrate how to give a user administration privileges with XML and Java.

Example 15-45 illustrates how a client application enables Administration Mode for the user's session with Oracle 9iFS.

Example 15-45 Using XML to Grant Administration Privileges to a User

<?xml version = '1.0' standalone = 'yes'?>
<SIMPLEUSER>
  <USERNAME>gking</USERNAME>
  <PASSWORD>ifs</PASSWORD>
  <DISTINGUISHEDNAMESUFFIX>.ambiguity.com</DISTINGUISHEDNAMESUFFIX>
  <ADMINENABLED>true</ADMINENABLED>
  <HOMEFOLDERROOT>/home</HOMEFOLDERROOT>
  <EMAILADDRESSSUFFIX>@ambiguity.com</EMAILADDRESSSUFFIX>
</SIMPLEUSER>

Example 15-46 Using Java to Grant Administration Privileges to a User

1. Administration mode must be enabled to create a user.

   session.setAdministrationMode(true);
   
   

2. Construct a new instance of UserManager.

   // Creating an user using all the default options;
   UserManager usermanager = new UserManager(session);
   
   

3. Construct a HashTable of options that set the Admin_Enabled attribute to 'true'.

   Hashtable userOptions = new Hashtable();
   userOptions.put(UserManager.ADMIN_ENABLED, new Boolean(true));
   
   

4. Create the user.

   DirectoryUser dUser = usermanager.createUser("Gary.King",
                                                "ifs",
                                                userOptions);
   

Example 15-47 Using Java to Enable Administration Mode

1. Assume that the application has obtained the LibrarySession.

   LibrarySession session = ....
   
   

2. Administration mode must be enabled to create a user.

   session.setAdministrationMode(true);
   

Ownership

Every object in Oracle 9iFS is owned by a user who has full access to that object. The user is given ownership of the object by referencing the user in the object's Owner attribute. When an object is created in the repository, Oracle 9iFS automatically sets the Owner attribute to the user who created the object. The Owner attribute can be modified to reference a different user at any time.

Example 15-48 Using XML to Set the Owner of a New PublicObject

<?xml verssion="1.0" standalone="yes"?>
<FOLDER>
  <NAME>My Work-in-Progress</NAME>
  <OWNER RefType = "Name">tturner</OWNER>
</FOLDER>

Example 15-49 Using XML to Change the Owner of an Existing PublicObject

<?xml verssion="1.0" standalone="yes"?>
<FOLDER>
  <UPDATE RefType = "Name">My Work-in-Progress</UPDATE>
  <OWNER RefType = "Name">gking</OWNER>
</FOLDER>

Example 15-50 Using Java to Set the Owner of a New PublicObject

1. Create a FolderDefinition.

   FolderDefinition fd = new FolderDefinition(session);
   fd.setAttributeByUpperCaseName(Folder.NAME_ATTRIBUTE, 
        AttributeValue.newAttributeValue("Collateral"));
   
   

2. Set the Owner attribute on the FolderDefinition

   Collection duColl = session.getDirectoryUserCollection();
   DirectoryUser du = (DirectoryUser) duColl.getItems("tturner");
   fd.setAttributeByUpperCaseName(Folder.OWNER_ATTRIBUTE,
       AttributeValue.newAttributeValue(du));
   
   

3. Pass the FolderDefinition to the LibrarySession to create a new Folder.

   Folder f = (Folder) session.createPublicObject(fd);
   

Example 15-51 Using Java to Change the Owner of an Existing PublicObject

1. Assume that the application has already obtained a folder.

   Folder f = ....
   
   

2. Set the Owner attribute on the Folder.

   Collection duColl = session.getDirectoryUserCollection();
   DirectoryUser du = (DirectoryUser) duColl.getItems("gking");
   f.setOwner(du);
   

Sample Code

Oracle 9iFS comes with a two sets of sample code files which you can use to get started working with the Java API.

• Documentation Example Files

• API Sample Code

Documentation Example Files

Oracle 9iFS is installed with runnable sample code files for the examples in this chapter. The sample code files are located in the <ORACLE_HOME>/9ifs/samplecode/oracle/ifs/examples/devdoc/security directory. These sample code files are useful for testing the chapter's examples. However, they must be run in the appropriate sequence and may cause naming conflicts if run more than once.

Table 15-16 lists the sample code files and their corresponding examples.

Table 15-16 Example Sample Code Files

Running the Java Sample Code Files

To run the Java sample code files, follow these steps:

1. Ensure that the CLASSPATH on the Oracle 9iFS host machine includes the Java API jar files.

2. With JDK 1.2.2, compile the sample code file in the <ORACLE_HOME>/9ifs/samplecode/oracle/ifs/examples/devdoc/security directory.

Example 15-52 Compiling the Sample Code Files on Solaris

> cd $ORACLE_HOME/9ifs/samplecode/oracle/ifs/examples/devdoc/security
> javac CreateUser.java

> java oracle.ifs.examples.documentation.security.CreateUser.java
newuser=lrichards admin=false emailAddress=lrichards@ambiguity.com acl=Public

  Running with arguments :
    user = system
    password = manager
    service = IfsDefault
    schemapassword = ifssys
    newuser = lrichards
  -----------Results----------
New User Created : lrichards
  DistinguishedName = lrichards
  AdminEnabled = false