bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Programming BPM Client Apps

Configuring the Security Realms

This section explains how to configure the security realm, including the following topics:

- Getting Basic Security Information

- Configuring Organizations, Roles, and Users

- Mapping Security Information

- Configuring Permissions

For more information about implementing security for tasks associated with managing business processes, see "About Security Realms" in Administering Data in Using the WebLogic Integration Studio.

Getting Basic Security Information

Using the com.bea.wlpi.server.principal.WLPIPrincipal methods and/or the com.bea.wlpi.client.common.WLPI class convenience methods, you can get the following security-related information:

- Class name of the WebLogic Server security realm, which allows you to determine, for example, whether the default WebLogic Server security realm is in use

- Whether or not the WebLogic Server security realm is manageable and/or persistent

- Process engine URL

- User ID

The following sections explain how to get these types of security information, and provides an example.

Getting the Security Realm Class Name

To get the class name of the WebLogic Server security realm, use the following com.bea.wlpi.server.principal.WLPIPrincipal method:

>     public java.lang.String getSecurityRealmClassName(
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

This method returns the fully qualified security realm class name.

For example, the following code gets the class name of the WebLogic security realm and saves it to the string security_class. In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB:

>     String security_class = principal.getSecurityRealmClassName();

For more information about the getSecurityRealmClassName() method, see the com.bea.wlpi.server.principal.WLPIPrincipal Javadoc.

Determining Whether the Security Realm Is Manageable and/or Persistent

In a manageable security realm, applications can update group and user security information. In a nonmanageable security realm, applications can view the security information for groups and users only. For more information, see "Managing Security" in the BEA WebLogic Server Administration Guide in the BEA WebLogic Server documentation set. This document is available, in the BEA WebLogic Server document set, at the following URL:

>     http://e-docs.bea.com/wls/docs70/adminguide/index.html

To determine whether or not the security realm is manageable, use the following com.bea.wlpi.server.principal.WLPIPrincipal method:

>     public boolean isManageableSecurityRealm(
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

This method returns true if the security realm is manageable (that is, if it implements the ManageableRealm interface), and false if it is nonmanageable.

To determine whether or not the security realm is both manageable and persistent, use the following com.bea.wlpi.client.common.WLPI method:

>     public boolean allowSecurityRealmUpdates(
>     ) throws java.lang.IllegalStateException

This method returns true if the security realm is manageable and persistent, and false if both characteristics are not present.

For example, the following code determines whether or not the security realm is manageable. In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB:

>     Boolean ismanageable = principal.isManageableSecurityRealm();

For more information about the isManageableSecurityRealm() method, see the com.bea.wlpi.server.principal.WLPIPrincipal Javadoc.For more information about the allowSecurityRealmUpdates() method, see the com.bea.wlpi.client.common.WLPI Javadoc.

Getting the Server URL

To get the URL of the WebLogic Integration process engine, use the following com.bea.wlpi.client.common.WLPI method:

>     public java.lang.String getURL()

This method returns the process engine URL. If you are not currently logged on, this method returns null.

For example, the following code gets the process engine URL and saves it to url:

>     String url = com.bea.wlpi.client.common.WLPI.getURL();

For more information about the getURL() method, see the com.bea.wlpi.client.common.WLPI Javadoc.

Getting the User ID

To get the current user ID, use the following com.bea.wlpi.client.common.WLPI method:

>     public java.lang.String getUserId()

This method returns the user ID. If you are not currently logged on, this method returns null.

For example, the following code gets the user ID and saves it to user:

>     String user = com.bea.wlpi.client.common.WLPI.getUserId();

For more information about the getUserId() method, see the com.bea.wlpi.client.common.WLPI Javadoc.

Example of Getting Basic Security Information

This section provides excerpts from the command-line administration example showing how to get basic security realm information.

Note: For more information about the command-line administration example, see Command-Line Administration Example.

In this example, an input stream is defined to communicate with the user, and the user is prompted to select an action from a menu. If the user selects the Security Realm option, the system displays the security class name and indicates whether or not the security realm is manageable.

Important lines of code are highlighted in bold. In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB.

>     /* Create an input stream to communicate with the user */
>     stdIn = new BufferedReader( new InputStreamReader( System.in ) )

>     /* Display Tool Title */
>        System.out.print( "\n---  Command Line Administration v1.1  ---" );

>     /* Display the main menu and interact with user */
>     while( true ) {
>     /* Display the menu */
>        System.out.println( "\n---             Main Menu            ---" );
>        System.out.println( "\nEnter choice:" );
>        System.out.println( "1) Organizations" );
>        System.out.println( "2) Roles" );
>        System.out.println( "3) Users" );
>        System.out.println( "4) Security Realm" );
>        System.out.println( "5) Business Operations" );
>        System.out.println( "6) Event Keys" );
>        System.out.println( "7) Business Calendars" );
>        System.out.println( "8) EJB Catalog" );
>        System.out.println( "9) Server Properties" );
>        System.out.println( "Q) Quit" );
>        System.out.print( ">> " );
>           .
>           .
>           .
>     /* Security Realm */
>              case '4' :
>                 /* Display WLPI security realm
>                  * properties and attributes */
>                 System.out.println( "\nSecurity Realm:" );
>                 /* Retrieve and display WLPI security realm
>                  * class currently use */
>                 System.out.println( "- Class Name: " +
>                 /* WLPI Public API Method */
>                 /* NOTE: Would be nice to add code to capture any
>                  * thrown exceptions */
>                 principal.getSecurityRealmClassName( ) );
>                 /* WLPI Public API Method */
>                 /* Retrieve and display info on manageability of WebLogic Process
>                  * Integrator security realm currently use */
>                 /* NOTE: Would be nice to add code to capture any
>                  * thrown exceptions */
>                 if( principal.isManageableSecurityRealm( ) )
>                    System.out.println( "- This realm is manageable" );
>                 else
>                    System.out.println( "- This realm is not manageable" );

>                    break;
>                    .
>                    .
>                    .

Configuring Organizations, Roles, and Users

Organizations are defined using the Studio client or a custom definition client to represent different business entities, geographical locations, or any other classifications that are relevant to the particular business of the company. You can configure roles within organizations, and users to further delineate security permissions.

This section describes the following topics:

- Configuring Organizations

- Configuring Roles

- Configuring Users

Configuring Organizations

The following sections explain how to configure organizations, including:

- Adding an Organization

- Adding a User to an Organization

- Getting All Organizations

- Getting the Roles Defined for an Organization

- Getting the Users Defined for an Organization

- Getting Organization Information

- Setting Organization Information

- Deleting a User from an Organization

- Deleting an Organization

- Example of Configuring Organizations

Adding an Organization

To add an organization to the security realm, use the following com.bea.wlpi.server.principal.WLPIPrincipal method:

>     public void addOrganization(
>       com.bea.wlpi.common.OrganizationInfo orgInfo
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

The following table describes the addOrganization() method parameter for which you must specify a value.

Table 9-1 addOrganization() Method Parameter

Parameter | Description | Valid Values
--- | --- | ---
orgInfo | New organization information. | An OrganizationInfo object. For information about defining the OrganizationInfo object, see OrganizationInfo Object.

For example, the following code adds an organization, based on the contents of the specified orgInfo object. In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB:

>     principal.addOrganization(orgInfo);

For more information about the addOrganization() method, see the com.bea.wlpi.server.principal.WLPIPrincipal Javadoc.

Adding a User to an Organization

To add a user to an organization, use the following com.bea.wlpi.server.principal.WLPIPrincipal method:

>     public void addUserToOrganization(
>       java.lang.String userId,
>       java.lang.String orgId
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

The following table describes the addUserToOrganization() method parameters for which you must specify values.

Table 9-2 addUserToOrganization() Method Parameters

Parameter | Description | Valid Values
--- | --- | ---
userId | ID of the user that you want to add to the organization. | String specifying a valid user ID. For information about getting a list of users, see Getting All Users.
orgId | ID of the organization to which you want to add the user. | String specifying a valid organization ID. For information about getting a list of all organization IDs, see Getting All Organizations.

For example, the following code adds the user joe to the specified organization, ORG1. In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB:

>     principal.addUserToOrganization("joe", "ORG1");

For more information about the addUserToOrganization() method, see the com.bea.wlpi.server.principal.WLPIPrincipal Javadoc.

Getting All Organizations

To get a list of all organizations defined for the security realm, use the following com.bea.wlpi.server.principal.WLPIPrincipal method:

>     public java.util.List getAllOrganizations(
>        boolean obtainAttributes
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

The following table describes the getAllOrganizations() method parameter for which you must specify a value.

Table 9-3 getAllOrganizations() Method Parameter

Parameter | Description | Valid Values
--- | --- | ---
obtainAttributes | Boolean flag specifying whether you want to get all attributes or only the organization IDs. | true (all attributes) or false (organization IDs only).

This method returns a list of com.bea.wlpi.common.OrganizationInfo objects. To access information about each organization, use the OrganizationInfo object methods described in OrganizationInfo Object.

For example, the following code gets only the organization IDs (the obtainAttributes parameter is set to false) and saves them to the orgList list variable. In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB:

>     List orgList = principal.getAllOrganizations(false);

For more information about the getAllOrganizations() method, see the com.bea.wlpi.server.principal.WLPIPrincipal Javadoc.

Getting the Roles Defined for an Organization

You can get a list of the roles defined for an organization or determine whether a specific role is defined for an organization using the methods described in the following sections.

Getting a List of Roles Defined for an Organization

To get a list of all the roles defined for an organization, use the following com.bea.wlpi.server.principal.WLPIPrincipal method:

>     public java.util.List getRolesInOrganization(
>       java.lang.String orgId,
>       boolean obtainAttributes
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

The following table describes the getRolesInOrganization() method parameters for which you must specify values.

Table 9-4 getRolesInOrganization() Method Parameters

Parameter | Description | Valid Values
--- | --- | ---
orgId | ID of the organization for which you want to get roles. | String specifying a valid organization ID. For information about getting a list of all organization IDs, see Getting All Organizations.
obtainAttributes | Flag specifying whether you want to get all attributes or only the role IDs. | true (all attributes) or false (role IDs only).

This method returns a list of com.bea.wlpi.common.RoleInfo objects. To access information about each role, use the RoleInfo object methods described in RoleInfo Object.

For example, the following code gets the roles in the ORG1 organization, returning all attributes (as the obtainAttributes parameter is set to true). In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB.

>     List roles = principal.getRolesInOrganization("ORG1", true);

For more information about the getRolesInOrganization() method, see the com.bea.wlpi.server.principal.WLPIPrincipal Javadoc.

Determining Whether a Role Is Defined for an Organization

To determine whether or not a specific role is defined for an organization, use the following com.bea.wlpi.server.principal.WLPIPrincipal method:

>     public boolean isRoleInOrganization(
>       java.lang.String roleId,
>       java.lang.String orgId
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

The following table describes the isRoleInOrganization() method parameters for which you must specify values.

Table 9-5 isRoleInOrganization() Method Parameters

Parameter | Description | Valid Values
--- | --- | ---
roleId | ID of the role that you want to verify. | String specifying a valid role ID. For information about getting a list of roles, see Getting the Roles Defined for an Organization.
orgId | ID of the organization that you want to check. | String specifying a valid organization ID. For information about getting a list of all organization IDs, see Getting All Organizations.

This method returns true if the role is defined for the organization and false if it is not.

For example, the following code determines whether or not the role1 role is defined for the ORG1 organization. In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB.

>     List roles = principal.isRoleInOrganization("role1", "ORG1");

For more information about the isRoleInOrganization() method, see the com.bea.wlpi.server.principal.WLPIPrincipal Javadoc.

Getting the Users Defined for an Organization

You can get a list of all the users defined for an organization or determine whether a specific user is defined for an organization using the methods described in the following section.

Getting a List of Users Defined for an Organization

To get a list of users defined for an organization, use the following com.bea.wlpi.server.principal.WLPIPrincipal method:

>     public java.util.List getUsersInOrganization(
>       java.lang.String orgId,
>       boolean obtainAttributes
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

The following table describes the getUsersInOrganization() method parameters for which you must specify values.

Table 9-6 getUsersInOrganization() Method Parameters

Parameter | Description | Valid Values
--- | --- | ---
orgId | ID of the organization for which you want to get a list of users. | String specifying a valid organization ID. For information about getting a list of all organization IDs, see Getting All Organizations.
obtainAttributes | Flag specifying whether you want to get all attributes or only the user IDs. | true (all attributes) or false (user IDs only).

This method returns a list of com.bea.wlpi.common.UserInfo objects. To access information about each role, use the UserInfo object methods described in UserInfo Object.

For example, the following code gets the list of users in the ORG1 organization, returning all attributes (as the obtainAttributes parameter is set to true). In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB.

>     List users = principal.getUsersInOrganization("ORG1", true);

For more information about the getUsersInOrganization() method, see the com.bea.wlpi.server.principal.WLPIPrincipal Javadoc.

Determining Whether a User Is Defined for an Organization

To determine whether or not a specific user is defined for an organization, use the following com.bea.wlpi.server.principal.WLPIPrincipal method:

>     public void isUserInOrganization(
>       java.lang.String userId,
>       java.lang.String orgId
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

The following table describes the isUserInOrganization() method parameters for which you must specify values.

Table 9-7 isUserInOrganization() Method Parameters

Parameter | Description | Valid Values
--- | --- | ---
userId | ID of the user that you want to verify. | String specifying a valid user ID. For information about getting a list of users, see Getting All Users.
orgId | ID of the organization that you want to check. | String specifying a valid organization ID. For information about getting a list of all organization IDs, see Getting All Organizations.

This method returns true if the user is defined for the organization, and false if it is not.

For example, the following code determines whether or not the user1 user is defined for the ORG1 organization. In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB.

>     List roles = principal.isUserInOrganization("user1", "ORG1");

For more information about the isUserInOrganization() method, see the com.bea.wlpi.server.principal.WLPIPrincipal Javadoc.

Getting Organization Information

To get organization information, use the following com.bea.wlpi.server.principal.WLPIPrincipal method:

>     public com.bea.wlpi.common.OrganizationInfo getOrganizationInfo(
>       java.lang.String orgId
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

The following table describes the getOrganizationInfo() method parameter for which you must specify a value.

Table 9-8 getOrganizationInfo() Method Parameter

Parameter | Description | Valid Values
--- | --- | ---
orgId | ID of the organization for which you want to get information. | String specifying a valid organization ID. For information about getting a list of all organization IDs, see Getting All Organizations.

This method returns a com.bea.wlpi.common.OrganizationInfo object. To access information about the organization, use the OrganizationInfo object methods described in OrganizationInfo Object.

For example, the following code gets the organization corresponding to the specified organization ID. In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB.

>     OrganizationInfo orgInfo = principal.getOrganizationInfo(orgId)

For more information about the getOrganizationInfo() method, see the com.bea.wlpi.server.principal.WLPIPrincipal Javadoc.

Setting Organization Information

To set organization information, use the following com.bea.wlpi.server.principal.WLPIPrincipal method.

>     public void setOrganizationInfo(
>       com.bea.wlpi.common.OrganizationInfo orgInfo
>     ) throws java.rmi.RemoteException

The following table describes the setOrganizationInfo() method parameter for which you must specify a value.

Table 9-9 setOrganizationInfo() Method Parameter

Parameter | Description | Valid Values
--- | --- | ---
orgInfo | Organization information to be updated. | An OrganizationInfo object. For information about getting a list of all OrganizationInfo objects, see Getting All Organizations. (Be sure to set the Boolean parameter, obtainAttributes, to true to avoid inadvertently clearing any organization attributes.) For information about updating an OrganizationInfo object, see OrganizationInfo Object.

For example, the following code updates an organization based on the contents of the specified orgInfo object. In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB.

>     principal.updateOrganization(orgInfo);

For more information about the setOrganizationInfo() method, see the com.bea.wlpi.server.principal.WLPIPrincipal Javadoc.

Deleting a User from an Organization

To delete a user from an organization, use the following com.bea.wlpi.server.principal.WLPIPrincipal method:

>     public void removeUserFromOrganization(
>       java.lang.String userId,
>       java.lang.String orgId
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

The following table describes the removeUserFromOrganization() method parameters for which you must specify values.

Table 9-10 removeUserFromOrganization() Method Parameters

Parameter | Description | Valid Values
--- | --- | ---
userId | ID of the user that you want to delete. | String specifying a valid user ID. For information about getting a list of users, see Getting All Users.
orgId | ID of the organization associated with the user. | String specifying a valid organization ID. For information about getting a list of all organization IDs, see Getting All Organizations.

For example, the following code removes the user1 user from the ORG1 organization. In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB.

>     principal.removeUserFromOrganization("user1", "ORG1");

For more information about the removeUserFromOrganization() method, see the com.bea.wlpi.server.principal.WLPIPrincipal Javadoc.

Deleting an Organization

To delete an organization, use the following com.bea.wlpi.server.principal.WLPIPrincipal method:

>     public void deleteOrganization(
>       java.lang.String orgId
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

The following table describes the deleteOrganization() method parameter for which you must specify a value.

Table 9-11 deleteOrganization() Method Parameter

Parameter | Description | Valid Values
--- | --- | ---
orgId | ID of the organization that you want to delete. | String specifying a valid organization ID. For information about getting a list of all organization IDs, see Getting All Organizations.

The following code example deletes the organization specified by the organization ID. In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB.

>     principal.deleteOrganization(organization.getId())

The organization ID is obtained using the methods associated with the com.bea.wlpi.common.OrganizationInfo object, organization. The organization object can be obtained using the methods described in Getting All Organizations.

For more information about the deleteOrganization() method, see the com.bea.wlpi.server.principal.WLPIPrincipal Javadoc.

Example of Configuring Organizations

This section provides excerpts from the command-line administration example showing how to configure organizations.

Note: For more information about the command-line administration example, see Command-Line Administration Example.

In this example, an input stream is defined to communicate with the user, and the user is prompted to specify one of the following actions to be performed:

- Adding an Organization

- Deleting an Organization

- Setting Organization Information

- Adding a User to an Organization

- Deleting a User from an Organization

- Getting All Organizations

- Getting the Users Defined for an Organization

- Determining Whether a User Is Defined for an Organization

- Getting the Roles Defined for an Organization

- Determining Whether a Role Is Defined for an Organization

Important lines of code are highlighted in bold. In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB.

>     /* Create an input stream to communicate with the user */
>     stdIn = new BufferedReader( new InputStreamReader( System.in ) )

>     /* Display Tool Title */
>        System.out.print( "\n---  Command Line Administration v1.1  ---" );

>     /* Display the main menu and interact with user */
>     while( true ) {
>     /* Display the menu */
>        System.out.println( "\n---             Main Menu            ---" );
>        System.out.println( "\nEnter choice:" );
>        System.out.println( "1) Organizations" );
>        System.out.println( "2) Roles" );
>        System.out.println( "3) Users" );
>        System.out.println( "4) Security Realm" );
>        System.out.println( "5) Business Operations" );
>        System.out.println( "6) Event Keys" );
>        System.out.println( "7) Business Calendars" );
>        System.out.println( "8) EJB Catalog" );
>        System.out.println( "9) Server Properties" );
>        System.out.println( "Q) Quit" );
>        System.out.print( ">> " );
>           .
>           .
>           .
>     public static void mngOrganizations( ) {
>        String answer;
>        String calendarId;
>        String orgId;
>        String userId;
>        String eMail;
>        String defaultOrgId;

>        /* Create an input stream to communicate with the user */
>        BufferedReader stdIn = new BufferedReader( new InputStreamReader( System.in ) );

>        try {
>        /* WLPI Public API Method */
>           boolean isRealmManageable = principal.isManageableSecurityRealm( );

>           /* Display the menu and interact with user */
>           while( true ) {
>              /* Display the menu */
>              System.out.println( "\n\n---        WLPI Organizations        ---" );
>              System.out.println( "\nEnter choice:" );
>              /* Is the realm manageable ? */
>              if( isRealmManageable ) {
>                 /* The realm is manageable realm; Display menu options that
>                  * requires a manageable realm */
>                 System.out.println( "0) Add a new Organization" );
>                 System.out.println( "1) Delete an Organization" );
>                 System.out.println( "2) Update Organization Info" );
>                 System.out.println( "3) Assign a User to an Organization" );
>                 System.out.println( "4) Remove a User from an Organization" );
>              }
>              System.out.println( "5) List all Organizations" );
>              System.out.println( "6) List Organization Info" );
>              System.out.println( "7) List Users assigned to an Organization" );
>              System.out.println( "8) Is User assigned to an Organization" );
>              System.out.println( "9) List Roles defined in an Organization" );
>              System.out.println( "A) Is Role in an Organization" );
>              System.out.println( "B) Back to previous menu" );
>              System.out.println( "Q) Quit" );
>              System.out.print( ">> " );

>              /* Get user's selection */
>              String line = stdIn.readLine( );

>              /* User pressed enter without making a selection ? */
>              if( line.equals( "" ) )
>                 continue;
>              /* User entered more than one char ? */
>              else if( line.length( ) > 1 ) {
>                 System.out.println( "*** Invalid selection" );
>                 continue;
>              }
>              /* Realm is not manageable and user entered a hidden selection ? */
>              else if( !isRealmManageable && line.charAt( 0 ) < '5' ) {
>                 System.out.println( "*** Invalid selection" );
>                 continue;
>              }

>              /* Convert to uppercase and to char */
>              char choice = line.toUpperCase( ).charAt( 0 );

>              /* Process user's selection */
>              switch( choice ) {
>              .
>              .
>              .

Adding an Organization

The following excerpt shows how to add an organization.

>              /* Add a New Organization */
>              case '0' :
>                 /* Get Organization ID for the new organization to add */
>                 if( ( orgId = askQuestion( "\nEnter new Organization ID" ) )
>                    == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 /* Get Calendar ID to assign to this organization (optional) */
>                 calendarId = askQuestion( "Enter Calendar ID (press
>                    enter for none)" );

>                 /* Create an OrganizationInfo object; required to add
>                  * a new organization */
>                 OrganizationInfo orgInfo =
>                   new OrganizationInfo( orgId, calendarId );

>                 try {
>                    /* WLPI Public API Method */
>                    /* Add the new organization */
>                    principal.addOrganization( orgInfo );

>                    /* Success (No exception thrown) */
>                    System.out.println( "- Success" );
>                 }
>                 catch( Exception e ) {
>                    System.out.println( "*** Unable to add the organization\n" );
>                    System.err.println( e );
>                 }
>                 break;
>                 .
>                 .
>                 .

Deleting an Organization

The following excerpt shows how to delete an organization.

>                 /* Delete an Organization */
>                 case '1' :
>                    /* Get Organization ID for the organization to remove */
>                    if( ( orgId = askQuestion( "\nEnter Organization
>                       ID to delete" ) ) == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 try {
>                    /* WLPI Public API Method */
>                    /* Remove the organization */
>                    principal.deleteOrganization( orgId );

>                    /* Success (No exception trown) */
>                    System.out.println( "- Success" );
>                 }
>                 catch( Exception e ) {
>                    System.out.println( "*** Unable to delete the organization\n" );
>                    System.err.println( e );
>                 }
>                 break;
>                 .
>                 .
>                 .

Setting Organization Information

The following excerpt shows how to set information about the organization.

>              /* Update Organization Info */
>              case '2' :
>              /* Get Organization ID for the organization to update */
>                 if( ( orgId = askQuestion(
>                    "\nEnter Organization ID to update" ) ) == null ) {
>                 /* User cancelled the operation */
>                 System.out.println( "*** Cancelled" );
>                 break;
>              }

>                 /* Get Calendar ID; only organization attribute defined in
>                  * WLPI v1.2.1 thus, only attribute that can be updated */
>                 calendarId = askQuestion(
>                    "Enter new Calendar ID (press enter for none)" );

>                 /* Create an OrganizationInfo object; required to update
>                  * the organization */
>                 orgInfo = new OrganizationInfo( orgId, calendarId );

>                 try {
>                    /* WLPI Public API Method */
>                    /* Update the organization (read calendar) */
>                    principal.setOrganizationInfo( orgInfo );

>                    /* Success (No exception trown) */
>                    System.out.println( "- Success" );
>                 }
>                 catch( Exception e ) {
>                    System.out.println( "*** Unable to update the organization\n" );
>                    System.err.println( e );
>                 }
>                 break;            .
>                 .
>                 .

Adding a User to an Organization

The following excerpt shows how to assign a user to an organization.

>      /* Assign a User to an Organization */
>              case '3' :
>                 /* Get User ID for the user to assign to an organization */
>                 if( ( userId = askQuestion( "\nEnter User ID to assign" )
>                    ) == null ) {
>                 /* User cancelled the operation */
>                 System.out.println( "*** Cancelled" );
>                 break;
>                 }

>                 /* Get Organization ID where the user is to be assigned */
>                 if( ( orgId = askQuestion( "Enter Organization ID" ) ) == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 try {
>                    /* WLPI Public API Method */
>                    /* Assign the user to the organization */
>                    principal.addUserToOrganization( userId, orgId );

>                    /* Success (No exception trown) */
>                    System.out.println( "- Success" );
>                 }
>                 catch( Exception e ) {
>                    System.out.println( "*** Unable to
>                       assign user to the organization\n" );
>                    System.err.println( e );
>                 }
>                 break;
>                 .
>                 .
>                 .

Deleting a User from an Organization

The following excerpt shows how to remove a user from an organization.

>              /* Remove a User from an Organization */
>              case '4' :
>                 /* Get User ID for the user to remove from an organization */
>                 if( ( userId = askQuestion(
>                    "\nEnter User ID to remove" ) ) == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                  }

>                 /* Get Organization ID where the user is to be removed */
>                 if( ( orgId = askQuestion( "Enter Organization ID" ) ) == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 try {
>                    /* WLPI Public API Method */
>                    /* Remove this user from this organization */
>                    principal.removeUserFromOrganization( userId, orgId );

>                    /* Success (No exception trown) */
>                    System.out.println( "- Success" );
>                 }
>                 catch( Exception e ) {
>                    System.out.println(
>                       "*** Unable to remove user from organization\n" );
>                    System.err.println( e );
>                 }
>                 break;
>                 .
>                 .
>                 .

Getting All Organizations

The following excerpt shows how to get a list of all organizations.

>              /* List all Organizations */
>              case '5' :
>                 /* Prompt user to select if we need to display
>                  * the organization attributes */
>                 if( ( answer = askQuestion(
>                    "\nList all attributes (y/n)?" ) ) == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 /* Parse the answer */
>                 boolean isGetAttributes = ( answer.equals( "y" ) ||
>                    answer.equals( "Y" ) );

>                 /* WLPI Public API Method */
>                 /* Retrieve all organizations */
>                 /* NOTE: Would be nice to add code to capture any
>                  * thrown exceptions */
>                 List orgList = principal.getAllOrganizations( isGetAttributes );

>                 /* Any organizations defined ? */
>                 if( orgList.size( ) == 0 )
>                    System.out.println( "\nNo Organization defined" );
>                 else
>                    System.out.println( "\nDefined organizations:" );

>                 /* Process the list to display organization and attributes */
>                 for( int i = 0; i < orgList.size( ); i++ ) {
>                    /* Retrieve an element from the list */
>                    orgInfo = ( OrganizationInfo )orgList.get( i );
>                    /* Retrieve and display organization id */
>                    System.out.println( "- ID: " + orgInfo.getOrgId( ) );

>                    /* Display attributes ? */
>                    if( isGetAttributes ) {
>                       /* Retrieve calendar id */
>                       if( ( calendarId = orgInfo.getCalendarId( ) ) == null )
>                          /* Assigned 'none' if none defined for this organization */
>                          calendarId = "None";

>                       /* Display calendar id */
>                       System.out.println( "
>                          Attributes: Calendar ID=" + calendarId + "\n" );
>                    }
>                 }
>                 break;
>                 .
>                 .
>                 .

Getting Organization Information

The following excerpt shows how to get information about an organization.

>              /* List Organization Info */
>              case '6' :
>                 /* Get Organization ID for the organization to display */
>                 if( ( orgId = askQuestion( "\nEnter Organization ID" ) ) == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 try {
>                    /* WLPI Public API Method */
>                    /* Retrieve info on this organization */
>                    orgInfo = principal.getOrganizationInfo( orgId );

>                    /* Retrieve and display organization id */
>                    System.out.println( "- ID: " + orgInfo.getOrgId( ) );

>                    /* Retrieve calendar id */
>                    if( ( calendarId = orgInfo.getCalendarId( ) ) == null )
>                       /* Assigned 'none' if none defined for this organization */
>                       calendarId = "None";

>                    /* Display calendar id */
>                    System.out.println( "
>                       Attributes: Calendar ID=" + calendarId + "\n" );
>                 }
>                 catch( Exception e ) {
>                    System.out.println(
>                       "*** Unable to retrieve organization info\n" );
>                    System.err.println( e );
>                 }
>                 						break;
>                 .
>                 .
>                 .

Getting the Users Defined for an Organization

The following excerpt shows how to get a list of users defined for an organization.

>              /* List Users assigned to an Organization */
>              case '7' :
>                 /* Get Organization ID to query for */
>                 if( ( orgId = askQuestion( "\nEnter Organization ID" ) ) == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 /* Prompt user to select if we need to display
>                  * the user attributes */
>                 if( ( answer = askQuestion(
>                    "List user attributes (y/n)?" ) ) == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 /* Parse the answer */
>                 isGetAttributes = ( answer.equals( "y" ) || answer.equals( "Y" ) );

>                 /* WLPI Public API Method */
>                 /* Retrieve all users assigned to this organization */
>                 /* NOTE: Would be nice to add code to capture any
>                  * thrown exceptions */
>                 List userList = principal.getUsersInOrganization(
>                    orgId, isGetAttributes );

>                 /* Any user assigned ? */
>                 if( userList.size( ) == 0 )
>                    System.out.println( "\nNo user assigned" );
>                 else
>                    System.out.println( "\nAssigned Users:" );

>                 /* Process the list to display users and attributes */
>                 for( int i = 0; i < userList.size( ); i++ ) {
>                 /* Retrieve an element from the list */
>                    UserInfo userInfo = ( UserInfo )userList.get( i );
>                    /* Retrieve and display user id */
>                    System.out.println( "- User ID: " + userInfo.getUserId( ) );

>                    /* Display attributes ? */
>                    if( isGetAttributes ) {
>                       /* Retrieve eMail address */
>                       if( ( eMail = userInfo.getEMailAddress( ) ) == null )
>                          /* Assigned 'none' if none defined for this user */
>                          eMail = "None";

>                       /* Retrieve default organization id */
>                       if( ( defaultOrgId = userInfo.getDefaultOrgId( ) ) == null )
>                          /* Assigned 'none' if none defined for this user */
>                          defaultOrgId = "None";

>                       /* Retrieve calendar id */
>                       if( ( calendarId = userInfo.getCalendarId( ) ) == null )
>                          /* Assigned 'none' if none defined for this user */
>                          calendarId = "None";

>                       /* Display email address, default ord id and calendar id */
>                       System.out.println( "  Attributes:\n  - eMail: " + eMail );
>                       System.out.println( "  - Default ORG ID: " + defaultOrgId );
>                       System.out.println( "  - Calendar ID=" + calendarId + "\n" );
>                    }
>                 }
>                 break;
>                 .
>                 .
>                 .

Determining Whether a User Is Defined for an Organization

The following excerpt shows how to determine whether a user defined for an organization.

>              /* Is User assigned to an Organization */
>              case '8' :
>                 /* Get User ID to query for */
>                 if( ( userId = askQuestion( "\nEnter User ID" ) ) == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 /* Get Organization ID for organization to query */
>                 if( ( orgId = askQuestion( "Enter Organization ID" ) ) == null ) {
>                 /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 /* WLPI Public API Method */
>                 /* Is the user assigned to this organization ? */
>                 /* NOTE: Would be nice to add code to capture any
>                  * thrown exceptions */
>                 if( principal.isUserInOrganization( userId, orgId ) )
>                    System.out.println( "User is assigned to the organization" );
>                 else
>                    System.out.println( "User is not assigned to the organization" );
>                 break;
>                 .
>                 .
>                 .

Getting the Roles Defined for an Organization

The following excerpt shows how to get a list of roles defined for an organization.

>              /* List Roles defined in an Organization */
>              case '9' :
>                 /* Get Organization ID for organization to query */
>                 if( ( orgId = askQuestion( "Enter Organization ID" ) ) == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 /* Prompt user to select if we need to display the user attributes */
>                if( ( answer = askQuestion(
>                   "List role attributes (y/n)?" ) ) == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 /* Parse the answer */
>                    isGetAttributes = ( answer.equals( "y" ) || answer.equals( "Y" ) );

>                 /* WLPI Public API Method */
>                 /* Retrieve all roles defined in this organization */
>                 /* NOTE: Would be nice to add code to capture any
>                  * thrown exceptions */
>                 List roleList = principal.getRolesInOrganization(
>                    orgId, isGetAttributes );

>                 /* Any roles defined ? */
>                 if( roleList.size( ) == 0 )
>                    System.out.println( "\nNo roles defined" );
>                 else
>                    System.out.println( "\nRoles Defined:" );

>                 /* Process the list to display roles and attributes */
>                 for( int i = 0; i < roleList.size( ); i++ ) {
>                    /* Retrieve an element from the list */
>                    RoleInfo roleInfo = ( RoleInfo )roleList.get( i );
>                    /* Retrieve and display role id */
>                    System.out.println( "- Role ID: " + roleInfo.getRoleId( ) );

>                    /* Display attributes ? */
>                    if( isGetAttributes ) {
>                       /* Retrieve calendar id */
>                       if( ( calendarId = roleInfo.getCalendarId( ) ) == null )
>                          /* Assigned 'none' if none defined for this role */
>                          calendarId = "None";

>                       /* Display calendar id */
>                       System.out.println(
>                         "  Attributes: Calendar ID=" + calendarId + "\n" );
>                    }
>                 }
>                 break;
>                 .
>                 .
>                 .

Determining Whether a Role Is Defined for an Organization

The following excerpt shows how to determine whether a role is defined for an organization.

>              /* Is Role in an Organization */
>              case 'A' :
>                 /* Get Role ID for role to query for */
>                 if( ( roleId = askQuestion( "\nEnter Role ID" ) ) == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 /* Get Organization ID to query */
>                 if( ( orgId = askQuestion( "Enter Organization ID" ) ) == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 /* WLPI Public API Method */
>                 /* Is the role defined in this organization ? */
>                 /* NOTE: Would be nice to add code to capture any
>                    thrown exceptions */
>                 if( principal.isRoleInOrganization( roleId, orgId) )
>                    System.out.println( "Role defined in the organization" );
>                 else
>                    System.out.println( "Role not defined in the organization" );
>              break;
>              .
>              .
>              .

Configuring Roles

The following sections explain how to configure roles, including:

- Adding a Role

- Adding a User to a Role

- Getting the Users Defined for a Role

- Getting Role Information

- Setting Role Information

- Deleting a User from a Role

- Deleting a Role

- Example of Configuring Roles

Adding a Role

To add a role to the security realm, use the following com.bea.wlpi.server.principal.WLPIPrincipal method.

>     public void addRole(
>       com.bea.wlpi.common.RoleInfo roleInfo
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

The following table describes the addRole() method parameter for which you must specify a value.

Table 9-12 addRole() Method Parameter

Parameter | Description | Valid Values
--- | --- | ---
roleInfo | New role information. | A RoleInfo object. For information about defining the RoleInfo object, see RoleInfo Object.

For example, the following code adds a role based on the contents of the specified roleInfo object. In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB.

>     principal.addRole(roleInfo);

For more information about the addRole() method, see the com.bea.wlpi.server.principal.WLPIPrincipal Javadoc.

Adding a User to a Role

To add a user to a role, use the following com.bea.wlpi.server.principal.WLPIPrincipal method:

>     public void addUserToRole(
>       java.lang.String userId,
>       java.lang.String orgId,
>       java.lang.String roleId
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

The following table describes the addUserToRole() method parameters for which you must specify values.

Table 9-13 addUserToRole() Method Parameters

Parameter | Description | Valid Values
--- | --- | ---
userId | ID of the user that you want to add to the role. | String specifying a valid user ID. For information about getting a list of users, see Getting All Users.
orgId | ID of the organization associated with the user. | String specifying a valid organization ID. For information about getting a list of all organization IDs, see Getting All Organizations.
roleId | ID of the role to which you want to add the user. | String specifying a valid role ID. For information about getting a list of roles, see Getting Role Information.

For example, the following code adds the user1 user to the role1 role in the ORG1 organization. In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB.

>     principal.addUserToRole("user1", "ORG1", "role1");

For more information about the addUserToRole() method, see the com.bea.wlpi.server.principal.WLPIPrincipal Javadoc.

Getting the Users Defined for a Role

To get a list of users defined for a role, use the following com.bea.wlpi.server.principal.WLPIPrincipal method:

>     public java.util.List getUsersInRole(
>       java.lang.String roleId,
>       java.lang.String orgId,
>       boolean obtainAttributes
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

The following table describes the getUsersInRole() method parameters for which you must specify values.

Table 9-14 getUsersInRole() Method Parameters

Parameter | Description | Valid Values
--- | --- | ---
roleId | ID of the role for which you want to get users. | String specifying a valid role ID. For information about getting a list of all role ides, see Getting the Roles Defined for an Organization.
orgId | ID of the organization associated with the role. | String specifying a valid organization ID. For information about getting a list of all organization IDs, see Getting All Organizations.
obtainAttributes | Flag specifying whether you want to get all attributes or only the user IDs. | true (all attributes) or false (user IDs only).

This method returns a list of com.bea.wlpi.common.UserInfo objects. To access information about each user, use the UserInfo object methods described in UserInfo Object.

For example, the following code gets a list of users defined for the role1 role in the ORG1 organization, returning all attributes (as the obtainAttributes parameter is set to true). In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB.

>     List users = principal.getUsersInRole("role1", "ORG1", true);

For more information about the getUsersInRole() method, see the com.bea.wlpi.server.principal.WLPIPrincipal Javadoc.

Getting Role Information

To get information about a role, use the following com.bea.wlpi.server.principal.WLPIPrincipal method:

>     public com.bea.wlpi.common.RoleInfo getRoleInfo(
>       java.lang.String roleId,
>       java.lang.String orgId
>     ) throws java.rmi.RemoteException

The following table describes the getRoleInfo() method parameters for which you must specify values.

Table 9-15 getRoleInfo() Method Parameters

Parameter | Description | Valid Values
--- | --- | ---
roleId | ID of the role for which you want to get information. | String specifying a valid role ID. For information about getting a list of users, see Getting the Roles Defined for an Organization.
orgId | ID of the organization associated with the role. | String specifying a valid organization ID. For information about getting a list of all organization IDs, see Getting All Organizations.

This method returns a com.bea.wlpi.common.RoleInfo object. To access information about the role, use the RoleInfo object methods described in RoleInfo Object.

For example, the following code gets information about the role1 role in the ORG1 organization. In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB.

>     principal.addUserToRole("role1", "ORG1");

For more information about the getRoleInfo() method, see the com.bea.wlpi.server.principal.WLPIPrincipal Javadoc.

Setting Role Information

To set information about a role, use the following com.bea.wlpi.server.principal.WLPIPrincipal method.

>     public void setRoleInfo(
>       com.bea.wlpi.common.RoleInfo roleInfo
>     ) throws java.rmi.RemoteException

The following table describes the setRoleInfo() method parameter for which you must specify a value.

Table 9-16 setRoleInfo() Method Parameter

Parameter | Description | Valid Values
--- | --- | ---
roleInfo | Role information to be updated. | A RoleInfo object. For information about getting a list of all RoleInfo objects, see Getting a List of Roles Defined for an Organization. (Be sure to set the Boolean parameter, obtainAttributes, to true to avoid inadvertently clearing any organization attributes.) For information about updating a RoleInfo object, see RoleInfo Object.

For example, the following code sets information about a role based on the contents of the specified roleInfo object. In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB.

>     principal.setRoleInfo(roleInfo);

For more information about the setRoleInfo() method, see the com.bea.wlpi.server.principal.WLPIPrincipal Javadoc.

Deleting a User from a Role

To delete a user from a role, use the following com.bea.wlpi.server.principal.WLPIPrincipal method:

>     public void removeUserFromRole(
>       java.lang.String userId,
>       java.lang.String orgId,
>       java.lang.String roleId
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

The following table describes the removeUserFromRole() method parameters for which you must specify values.

Table 9-17 removeUserFromRole() Method Parameters

Parameter | Description | Valid Values
--- | --- | ---
userId | ID of the user that you want to delete. | String specifying a valid user ID. For information about getting a list of users, see Getting All Users.
orgId | ID of the organization associated with the user. | String specifying a valid organization ID. For information about getting a list of all organization IDs, see Getting All Organizations.
roleId | ID of the role from which you want to delete the user. | String specifying a valid role ID. For information about getting a list of all role IDs, see Getting the Roles Defined for an Organization.

For example, the following code removes the user1 user from the role1 role within the ORG1 organization. In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB.

>     principal.removeUserFromOrganization("user1", "ORG1", "role1");

For more information about the removeUserFromRole() method, see the com.bea.wlpi.server.principal.WLPIPrincipal Javadoc.

Deleting a Role

To delete a role, use the following com.bea.wlpi.server.principal.WLPIPrincipal method:

>     public void deleteRole(
>       java.lang.String orgId,
>       java.lang.String roleId
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

The following table describes the deleteRole() method parameters for which you must specify values.

Table 9-18 deleteRole() Method Parameters

Parameter | Description | Valid Values
--- | --- | ---
orgId | ID of the organization associated with the role to be deleted. | String specifying a valid organization ID. For information about getting a list of all organization IDs, see Getting All Organizations.
roleId | ID of the role that you want to delete. | String specifying a valid role ID. For information about getting a list of all role IDs, see Getting the Roles Defined for an Organization.

For example, the following code deletes the role corresponding to the specified role ID in the ORG1 organization. In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB.

>     principal.deleteRole(role.getId(), "ORG1")

The role ID is obtained using the methods associated with the com.bea.wlpi.common.RoleInfo object, role. The role object can be obtained using the methods described in Getting a List of Roles Defined for an Organization.

For more information about the deleteRole() method, see the com.bea.wlpi.server.principal.WLPIPrincipal Javadoc.

Example of Configuring Roles

This section provides excerpts from the command-line administration example showing how to configure roles.

Note: For more information about the command-line administration example, see Command-Line Administration Example.

In this example, an input stream is defined to communicate with the user, and the user is prompted to specify one of the following actions to be performed:

- Adding a Role

- Adding a User to a Role

- Deleting a Role

- Deleting a User from a Role

- Setting Role Information

- Getting Role Information

- Getting Users Defined for a Role

Important lines of code are highlighted in bold. In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB.

>     /* Create an input stream to communicate with the user */
>     stdIn = new BufferedReader( new InputStreamReader( System.in ) )

>     /* Display Tool Title */
>        System.out.print( "\n---  Command Line Administration v1.1  ---" );

>     /* Display the main menu and interact with user */
>     while( true ) {
>     /* Display the menu */
>        System.out.println( "\n---             Main Menu            ---" );
>        System.out.println( "\nEnter choice:" );
>        System.out.println( "1) Organizations" );
>        System.out.println( "2) Roles" );
>        System.out.println( "3) Users" );
>        System.out.println( "4) Security Realm" );
>        System.out.println( "5) Business Operations" );
>        System.out.println( "6) Event Keys" );
>        System.out.println( "7) Business Calendars" );
>        System.out.println( "8) EJB Catalog" );
>        System.out.println( "9) Server Properties" );
>        System.out.println( "Q) Quit" );
>        System.out.print( ">> " );
>           .
>           .
>           .
>     public static void mngRoles( ) {
>        String answer;
>        String calendarId;
>        String orgId;
>        String roleId;
>        String userId;
>        String eMail;
>        String defaultOrgId;

>        /* Create an input stream to communicate with the user */
>        BufferedReader stdIn = new BufferedReader(
>           new InputStreamReader( System.in ) );

>        try {
>           /* WLPI Public API Method */
>           boolean isRealmManageable = principal.isManageableSecurityRealm( );

>           /* Display the menu and interact with user */
>           while( true ) {
>           /* Display the menu */
>              System.out.println( "\n\n---            WLPI Roles            ---" );
>              System.out.println( "\nEnter choice:" );
>              /* Is the realm manageable ? */
>              if( isRealmManageable ) {
>                 /* The realm is manageable realm; Display menu options that
>                  * requires a manageable realm */
>                 System.out.println( "1) Add a new Role" );
>                 System.out.println( "2) Assign a User to a Role" );
>                 System.out.println( "3) Delete a Role" );
>                 System.out.println( "4) Remove a User from a Role" );
>                 System.out.println( "5) Update Role Info" );
>              }
>              System.out.println( "6) List Role Info" );
>              System.out.println( "7) List Users in a Role" );
>              System.out.println( "B) Back to previous menu" );
>              System.out.println( "Q) Quit" );
>              System.out.print( ">> " );

>              /* Get user's selection */
>              String line = stdIn.readLine( );

>              /* User pressed enter without making a selection ? */
>              if( line.equals( "" ) )
>                 continue;
>              /* User entered more than one char ? */
>              else if( line.length( ) > 1 ) {
>                 System.out.println( "*** Invalid selection" );
>                 continue;
>              }
>              /* Realm is not manageable and user entered a hidden selection ? */
>              else if( !isRealmManageable && line.charAt( 0 ) < '6' ) {
>                 System.out.println( "*** Invalid selection" );
>                 continue;
>              }

>              /* Convert to uppercase and to char */
>              char choice = line.toUpperCase( ).charAt( 0 );

>              /* Process user's selection */
>              switch( choice ) {
>                 .
>                 .
>                 .

Adding a Role

The following excerpt shows how to add a role:

>              /* Add a new Role */
>              case '1' :
>                 /* Get Role ID for new role to add */
>                 if( ( roleId = askQuestion(
>                    "\nEnter a new Role ID" ) ) == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 /* Get Organization ID where to add new user; required */
>                 if( ( orgId = askQuestion(
>                    "Enter Organization ID" ) ) == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 /* Get Calendar ID to assign to this role (optional) */
>                 calendarId = askQuestion(
>                    "Enter Calendar ID (press enter for none)" );

>                 /* Create a RoleInfo object; required to add a new role */
>                 RoleInfo roleInfo = new RoleInfo( roleId, orgId, calendarId );

>                 try {
>                    /* WLPI Public API Method */
>                    /* Add the new role to the organization */
>                    principal.addRole( roleInfo );

>                    /* Success (No exception trown) */
>                    System.out.println( "- Success" );
>                 }
>                 catch( Exception e ) {
>                    System.out.println( "*** Unable to add role\n" );
>                    System.err.println( e );
>                 }
>                  break;
>                 .
>                 .
>                 .

Adding a User to a Role

The following excerpt shows how to add a user to a role:

>              /* Assign a User to a Role */
>              case '2' :
>                 /* Get User ID for user to assign to role */
>                 if( ( userId = askQuestion(
>                    "\nEnter User ID to assign" ) ) == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 /* Get Role ID where to add user */
>                 if( ( roleId = askQuestion( "Enter Role ID" ) ) == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>              /* Get Organization ID where role belongs */
>                 if( ( orgId = askQuestion( "Enter Organization ID" ) ) == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 try {
>                    /* WLPI Public API Method */
>                    /* Add user to this role within this organization */
>                    principal.addUserToRole( userId, orgId, roleId );

>                    /* Success (No exception thrown) */
>                    System.out.println( "- Success" );
>                 }
>                 catch( Exception e ) {
>                    System.out.println( "*** Unable to add user to role\n" );
>                    System.err.println( e );
>                 }
>                 break;
>                 .
>                 .
>                 .

Deleting a Role

The following excerpt shows how to delete a role:

>              /* Delete a Role */
>              case '3' :
>                 /* Get Role ID for role to be removed */
>                 if( ( roleId = askQuestion(
>                    "\nEnter Role ID to delete" ) ) == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 /* Get Organization ID where role is to be removed */
>                 if( ( orgId = askQuestion( "Enter Organization ID" ) ) == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 try {
>                    /* WLPI Public API Method */
>                    /* Remove role from this organization */
>                    principal.deleteRole( orgId, roleId );

>                    /* Success (No exception trown) */
>                    System.out.println( "- Success" );
>                 }
>                 catch( Exception e ) {
>                    System.out.println( "*** Unable to delete role\n" );
>                    System.err.println( e );
>                 }
>                 break;
>                 .
>                 .
>                 .

Deleting a User from a Role

The following excerpt shows how to delete a user from a role:

>              /* Remove a User from a Role */
>              case '4' :
>                 /* Get User ID for user to be removed from role */
>                 if( ( userId = askQuestion(
>                    "\nEnter User ID to remove" ) ) == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 /* Get Role ID where to remove user */
>                 if( ( roleId = askQuestion( "Enter Role ID" ) ) == null ) {
>                 /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 /* Get Organization ID where role belongs */
>                 if( ( orgId = askQuestion( "Enter Organization ID" ) ) == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 try {
>                    /* WLPI Public API Method */
>                    /* Remove user from this role in this organization */
>                    principal.removeUserFromRole( userId, orgId, roleId);

>                    /* Success (No exception trown) */
>                    System.out.println( "- Success" );
>                 }
>                 catch( Exception e ) {
>                    System.out.println( "*** Unable to remove user from role\n" );
>                    System.err.println( e );
>                 }
>                 break;
>                 .
>                 .
>                 .

Setting Role Information

The following excerpt shows how to set role information:

>              /* Update Role Info */
>              case '5' :
>                 /* Get Role ID for role to be updated */
>                 if( ( roleId = askQuestion(
>                    "\nEnter Role ID to update" ) ) == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 /* Get Organization ID where role belongs */
>                 if( ( orgId = askQuestion(
>                    "Enter Organization ID" ) ) == null ) {
>                 /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 /* Get new Calendar ID to assign to this role; only role attribute
>                  * defined in WLPI v1.2.1 thus only attribute that can be updated */
>                 calendarId = askQuestion(
>                    "Enter Calendar ID (press enter for none)" );

>                 /* Create a RoleInfo object; required to update a role */
>                 roleInfo = new RoleInfo( roleId, orgId, calendarId );

>                 try {
>                    /* WLPI Public API Method */
>                    /* Update this role (read calendar) in this organization */
>                    principal.setRoleInfo( roleInfo );

>                    /* Success (No exception trown) */
>                    System.out.println( "- Success" );
>                 }
>                 catch( Exception e ) {
>                    System.out.println( "*** Unable to update role info\n" );
>                    System.err.println( e );
>                 }
>                 break;
>                 .
>                 .
>                 .

Getting Role Information

The following excerpt shows how to get information about a role:

>              /* List Role Info */
>              case '6' :
>                 /* Get Role ID for the role to display */
>                 if( ( roleId = askQuestion( "\nEnter Role ID" ) ) == null ) {
>                 /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                     break;
>                 }

>                 /* Get Organization ID where role belongs */
>                 if( ( orgId = askQuestion( "Enter Organization ID" ) ) == null ) {
>                 /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 try {
>                    /* WLPI Public API Method */
>                    /* Retrieve info on this role */
>                    roleInfo = principal.getRoleInfo( roleId, orgId );

>                    System.out.println( "\nRole Info:" );
>                    /* Retrieve and display role id */
>                    System.out.println( "- Role ID: " + roleInfo.getRoleId( ) );
>                    /* Retrieve and display org id where role belongs */
>                    System.out.println( "  Org ID: " + roleInfo.getOrgId( ) );

>                    /* Retrieve calendar id */
>                    if( ( calendarId = roleInfo.getCalendarId( ) ) == null )
>                    /* Assigned 'none' if none defined for this role */
>                       calendarId = "None";

>                    /* Display calendar id */
>                    System.out.println( "  Calendar ID: " + calendarId );
>                 }
>                 catch( Exception e ) {
>                    System.out.println( "*** Unable to retrieve role info\n" );
>                    System.err.println( e );
>                 }
>                 break;
>                 .
>                 .
>                 .

Getting Users Defined for a Role

The following excerpt shows how to get a list of all users defined for a role:

>              /* List Users in a Role */
>              case '7' :
>                 /* Get Role ID for role to query */
>                 if( ( roleId = askQuestion( "\nEnter Role ID" ) ) == null ) {
>                 /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 /* Get Organization ID where role belongs */
>                 if( ( orgId = askQuestion( "Enter Organization ID" ) ) == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 /* Prompt user to select if we need to display
>                  * the user attributes */
>                 if( ( answer = askQuestion(
>                    "List all attributes (y/n)?" ) ) == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 /* Parse the answer */
>                 boolean isGetAttributes = ( answer.equals( "y" ) ||
>                    answer.equals( "Y" ) );

>                 /* WLPI Public API Method */
>                 /* Retrieve all users assigned to this role */
>                 /* NOTE: Would be nice to add code to capture
>                  * any thrown exceptions */
>                 List userList =
>                    principal.getUsersInRole( roleId, orgId, isGetAttributes );

>                 /* Any users assigned ? */
>                 if( userList.size( ) == 0 )
>                    System.out.println( "\nNo users assigned" );
>                 else
>                    System.out.println( "\nAssigned Users:" );

>                 /* Process the list to display users and attributes */
>                 for( int i = 0; i < userList.size( ); i++ ) {
>                    /* Retrieve an element from the list */
>                    UserInfo userInfo = ( UserInfo )userList.get( i );
>                    /* Retrieve and display user id */
>                    System.out.println( "- User ID: " + userInfo.getUserId( ) );

>                    /* Display attributes ? */
>                    if( isGetAttributes ) {
>                       if( ( eMail = userInfo.getEMailAddress( ) ) == null )
>                          /* Assigned 'none' if none defined for this user */
>                          eMail = "None";

>                       if( ( defaultOrgId = userInfo.getDefaultOrgId( ) ) == null )
>                       /* Assigned 'none' if none defined for this user */
>                          defaultOrgId = "None";

>                       /* Retrieve calendar id */
>                       if( ( calendarId = userInfo.getCalendarId( ) ) == null )
>                       /* Assigned 'none' if none defined for this user */
>                          calendarId = "None";

>                       /* Display email address, default ord id and calendar id */
>                       System.out.println( "  Attributes:\n  - eMail: " + eMail );
>                       System.out.println( "  - Default ORG ID: " + defaultOrgId );
>                       System.out.println( "  - Calendar ID=" + calendarId + "\n" );
>                    }
>                 }
>                 break;
>                 .
>                 .
>                 .

Configuring Users

The following sections explain how to configure users:

- Adding a User

- Getting All Users

- Getting User Organizations

- Getting User Roles

- Getting User Information

- Setting User Information

- Deleting a User

- Example of Configuring Users

Adding a User

To create a new user and add it to the wlpiUsers group, use the following com.bea.wlpi.server.principal.WLPIPrincipal method:

>     public com.bea.wlpi.common.UserInfo createUser(
>       java.lang.String userId,
>       java.lang.String pswd
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

The following table describes the createUser() method parameters for which you must specify values.

Table 9-19 createUser() Method Parameters

Parameter | Description | Valid Values
--- | --- | ---
userId | ID of the user that you want to add. | String specifying a unique user ID.
pswd | Clear-text password for the specified user ID. | String specifying a password.

For example, the following code creates a user named sam with the password password within the wlpiUsers group. In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB.

>     UserInfo userInfo = principal.createUser("sam", "password")

For more information about the createUser() method, see the com.bea.wlpi.server.principal.WLPIPrincipal Javadoc.

Getting All Users

To obtain a list of all users, use the following com.bea.wlpi.server.principal.WLPIPrincipal method:

>     public java.util.List getAllUsers(
>        boolean obtainAttributes
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

The following table describes the getAllUsers() method parameter for which you must specify a value.

Table 9-20 getAllUsers() Method Parameter

Parameter | Description | Valid Values
--- | --- | ---
obtainAttributes | Flag specifying whether you want to get all attributes or only the user IDs. | true (all attributes) or false (user IDs only).

This method returns a list of com.bea.wlpi.common.UserInfo objects. To access information about each user, use the UserInfo object methods described in UserInfo Object.

For example, the following code gets the user IDs (the obtainAttributes parameter is set to false) and saves them to the list variable, userList. In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB.

>     List userList = principal.getAllUsers(false)

For more information about the getAllUsers() method, see the com.bea.wlpi.server.principal.WLPIPrincipal Javadoc.

Getting User Organizations

To get a list of the organizations to which a user belongs, use the following com.bea.wlpi.server.principal.WLPIPrincipal method:

>     public java.util.List getOrganizationsForUser(
>       java.lang.String userId,
>       boolean obtainAttributes
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

The following table describes the getOrganizationsForUser() method parameters for which you must specify values.

Table 9-21 getOrganizationsForUser() Method Parameters

Parameter | Description | Valid Values
--- | --- | ---
userId | ID of the user for which you want to get organizations. | String specifying a valid user ID. For information about getting a list of all organization IDs, see Getting All Users.
obtainAttributes | Flag specifying whether you want to get all attributes or only the organization IDs. | true (all attributes) or false (organization IDs only).

This method returns a list of com.bea.wlpi.common.OrganizationInfo objects. To access information about each organization, use the OrganizationInfo object methods described in OrganizationInfo Object.

For example, the following code gets a list of organizations for user1, returning all attributes (as the obtainAttributes parameter is set to true). In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB.

>     List roles = principal.getOrganizationsForUser("user1", true);

For more information about the getOrganizationsForUser() method, see the com.bea.wlpi.server.principal.WLPIPrincipal Javadoc.

Getting User Roles

To get a list of roles to which a user belongs, use the following com.bea.wlpi.server.principal.WLPIPrincipal method:

>     public java.util.List getRolesForUser(
>       java.lang.String orgId,
>       java.lang.String userId,
>       boolean obtainAttributes
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

The following table describes the getRolesForUser() method parameters for which you must specify values.

Table 9-22 getRolesForUser() Method Parameters

Parameter | Description | Valid Values
--- | --- | ---
orgId | ID of the organization associated with the user. | String specifying a valid organization ID. For information about getting a list of all organization IDs, see Getting All Organizations.
userId | ID of the user for which you want to get a list of roles. | String specifying a valid user ID. For information about getting a list of all organization IDs, see Getting All Users.
obtainAttributes | Flag specifying whether you want to get all attributes or only the role IDs. | true (all attributes) or false (organization IDs only).

This method returns a list of com.bea.wlpi.common.RoleInfo objects. To access information about each role, use the RoleInfo object methods described in RoleInfo Object.

For example, the following code gets a list of roles for user1 in the ORG1 organization, returning all attributes (as obtainAttributes parameter is set to true). In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB.

>     List roles = principal.getRolesForUser("ORG1", "user1", true);

For more information about the getRolesForUser() method, see the com.bea.wlpi.server.principal.WLPIPrincipal Javadoc.

Getting User Information

To get information about the user, use the following com.bea.wlpi.server.principal.WLPIPrincipal method:

>     public com.bea.wlpi.common.UserInfo getUserInfo(
>       java.lang.String userId
>     ) throws java.rmi.RemoteException

The following table describes the getUserInfo() method parameter for which you must specify a value.

Table 9-23 getUserInfo() Method Parameter

Parameter | Description | Valid Values
--- | --- | ---
userId | ID of the user for which you want to get information. | String specifying a valid user ID. For information about getting a list of users, see Getting All Users.

This method returns a com.bea.wlpi.common.UserInfo object. To access information about the user, use the UserInfo object methods described in UserInfo Object.

For example, the following code gets information for the user1 user. In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB.

>     UserInfo user = principal.getUserInfo("user1");

For more information about the getUserInfo() method, see the com.bea.wlpi.server.principal.WLPIPrincipal Javadoc.

Setting User Information

To set information about the user, use the following com.bea.wlpi.server.principal.WLPIPrincipal method:

>     public void setUserInfo(
>       com.bea.wlpi.common.UserInfo userInfo
>     ) throws java.rmi.RemoteException,

The following table describes the setUserInfo() method parameter for which you must specify a value.

Table 9-24 setUserInfo() Method Parameter

Parameter | Description | Valid Values
--- | --- | ---
userInfo | User information to be updated. | A UserInfo object. For information about getting a list of all UserInfo objects, see Getting a List of Users Defined for an Organization. (Be sure to set the Boolean parameter, obtainAttributes, to true to avoid inadvertently clearing any organization attributes.) For information about updating a UserInfo object, see UserInfo Object.

For example, the following code sets information about a user based on the contents of the specified userInfo object. In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB.

>     principal.setUserInfo(userInfo);

For more information about the setUserInfo() method, see the com.bea.wlpi.server.principal.WLPIPrincipal Javadoc.

Deleting a User

You can delete users from an organization, from a role, or from the configuration database using the methods described in this section.

Deleting a User from an Organization

For information about deleting a user from an organization, see Deleting a User from an Organization, within the section Configuring Organizations.

Deleting a User from a Role

For information about deleting a user from a role, see Deleting a User from a Role, within the section Configuring Roles.

Deleting a User from the Database

To delete a user from the configuration database, use the following com.bea.wlpi.server.principal.WLPIPrincipal method:

>     public void deleteUser(
>       java.lang.String userId
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

The following table describes the deleteUser() method parameter for which you must specify a value.

Table 9-25 deleteUser() Method Parameter

Parameter | Description | Valid Values
--- | --- | ---
userId | ID of the user that you want to delete. | String specifying a valid user ID. For information about getting a list of users, see Getting All Users.

For example, the following code removes the user1 user from the database. In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB.

>     principal.deleteUser("user1");

For more information about the deleteUser() method, see the com.bea.wlpi.server.principal.WLPIPrincipal Javadoc.

Example of Configuring Users

This section provides excerpts from the command-line administration example showing how to configure users.

Note: For more information about the command-line administration example, see Command-Line Administration Example.

In this example, an input stream is defined to communicate with the user, and the user is prompted to specify one of the following actions to be performed:

- Adding a User

- Deleting a User

- Setting User Information

- Getting All Users

- Getting User Information

- Getting User Organizations

- Getting User Roles

Important lines of code are highlighted in bold. In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB.

>     /* Create an input stream to communicate with the user */
>     stdIn = new BufferedReader( new InputStreamReader( System.in ) )

>     /* Display Tool Title */
>        System.out.print( "\n---  Command Line Administration v1.1  ---" );

>     /* Display the main menu and interact with user */
>     while( true ) {
>     /* Display the menu */
>        System.out.println( "\n---             Main Menu            ---" );
>        System.out.println( "\nEnter choice:" );
>        System.out.println( "1) Organizations" );
>        System.out.println( "2) Roles" );
>        System.out.println( "3) Users" );
>        System.out.println( "4) Security Realm" );
>        System.out.println( "5) Business Operations" );
>        System.out.println( "6) Event Keys" );
>        System.out.println( "7) Business Calendars" );
>        System.out.println( "8) EJB Catalog" );
>        System.out.println( "9) Server Properties" );
>        System.out.println( "Q) Quit" );
>        System.out.print( ">> " );
>           .
>           .
>           .

>        System.out.print( ">> " ); ...

The mngUsers() method illustrates how to manage users, interacting with the user to retrieve the information required:

>     public static void mngUsers( ) {
>        String answer;
>        String calendarId;
>        String orgId;
>        String userId;
>        String password;
>        String eMail;
>        String defaultOrgId;

>        /* Create an input stream to communicate with the user */
>        BufferedReader stdIn = new BufferedReader(
>           new InputStreamReader( System.in ) );

>        try {
>           /* WLPI Public API Method */
>           boolean isRealmManageable = principal.isManageableSecurityRealm( );

>           /* Display the menu and interact with user */
>           while( true ) {
>              /* Display the menu */
>              System.out.println( "\n\n---            WLPI Users            ---" );
>              System.out.println( "\nEnter choice:" );
>              /* Is the realm manageable ? */
>              if( isRealmManageable ) {
>                 /* The realm is manageable realm; Display menu options that
>                  * requires a manageable realm */
>                 System.out.println( "1) Add a new User" );
>                 System.out.println( "2) Delete a User" );
>                 System.out.println( "3) Update User Info" );
>              }
>              System.out.println( "4) List All Users" );
>              System.out.println( "5) List User Info" );
>              System.out.println( "6) List Organizations for a User" );
>              System.out.println( "7) List Roles for a User" );
>              System.out.println( "B) Back to previous menu" );
>              System.out.println( "Q) Quit" );
>              System.out.print( ">> " );

>              /* Get user's selection */
>              String line = stdIn.readLine( );

>              /* User pressed enter without making a selection ? */
>              if( line.equals( "" ) )
>                 continue;
>              /* User entered more than one char ? */
>              else if( line.length( ) > 1 ) {
>                 System.out.println( "*** Invalid selection" );
>                 continue;
>              }
>              /* Realm is not manageable and user entered a hidden selection ? */
>              else if( !isRealmManageable && line.charAt( 0 ) < '4' ) {
>                 System.out.println( "*** Invalid selection" );
>                 continue;
>              }

>              /* Convert to uppercase and to char */
>              char choice = line.toUpperCase( ).charAt( 0 );

>              /* Process user's selection */
>              switch( choice ) {
>                 .
>                 .
>                 .

Adding a User

The following excerpt shows how to add a user:

>              /* Add a new User */
>              case '1' :
>                 /* Get User ID for new user to create */
>                 if( ( userId = askQuestion( "\nEnter new User ID" ) ) == null ) {
>                 /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 /* Get new user's Password */
>                 if( ( password = askQuestion( "Enter Password" ) ) == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 try {
>                    /* WLPI Public API Method */
>                    /* Create the new user id using this password */
>                    principal.createUser( userId, password );

>                    /* Success (No exception thrown) */
>                    System.out.println( "- Success" );
>                 }
>                 catch( Exception e ) {
>                    System.out.println( "*** Unable to create user\n" );
>                    System.err.println( e );
>                 }
>                 break;
>                 .
>                 .
>                 .

Deleting a User

The following excerpt shows how to delete a user:

>              /* Delete a User */
>              case '2' :
>                 /* Get User ID for user to remove */
>                 if( ( userId = askQuestion( "\nEnter User ID to delete" ) )
>                    == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 try {
>                    /* WLPI Public API Method */
>                    /* Remove/delete user */
>                    principal.deleteUser( userId );

>                    /* Success (No exception trown) */
>                    System.out.println( "- Success" );
>                 }
>                 catch( Exception e ) {
>                    System.out.println( "*** Unable to delete user\n" );
>                    System.err.println( e );
>                 }

>                 break;
>                 .
>                 .
>                 .

Setting User Information

The following excerpt shows how to set information about a user:

>              /* Update User Info */
>              case '3' :
>                 /* Get User ID for user to update */
>                 if( ( userId = askQuestion( "\nEnter User ID to update" ) )
>                    == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 /* Get eMail address for this user (optional) */
>                 eMail = askQuestion(
>                    "Enter new eMail Address (press enter for none)" );

>                 /* Get Default Org ID to assign to this user (optional) */
>                 defaultOrgId = askQuestion(
>                    "Enter new default Org ID (press enter for none)" );

>                 /* Get Calendar ID to assign to this user (optional) */
>                 calendarId = askQuestion(
>                    "Enter new Calendar ID (press enter for none)" );

>                 /* Create an UserInfo object; required to update a user */
>                 UserInfo userInfo = new UserInfo(
>                    userId, eMail, defaultOrgId, calendarId );

>                 try {
>                    /* WLPI Public API Method */
>                    principal.setUserInfo( userInfo );

>                    /* Success (No exception trown) */
>                    System.out.println( "- Success" );
>                 }
>                 catch( Exception e ) {
>                    System.out.println( "*** Unable to update user\n" );
>                    System.err.println( e );
>                 }

>                 break;
>                 .
>                 .
>                 .

Getting All Users

The following excerpt shows how to get a list of all users:

>              /* List All Users */
>              case '4' :
>                 /* Prompt user to select if we need to display the
>                  * user attributes */
>                 if( ( answer = askQuestion(
>                    "\nList all attributes (y/n)?" ) ) == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 /* Parse the answer */
>                 boolean isGetAttributes = ( answer.equals( "y" ) ||
>                    answer.equals( "Y" ) );

>                 /* WLPI Public API Method */
>                 /* Retrieve all users */
>                 /* NOTE: Would be nice to add code to capture any
>                  * thrown exceptions */
>                 List userList = principal.getAllUsers( isGetAttributes );

>                 /* Any users defined ? */
>                 if( userList.size( ) == 0 )
>                    System.out.println( "\nNo user defined" );
>                 else
>                    System.out.println( "\nDefined Users:" );

>                 /* Process the list to display users and attributes */
>                 for( int i = 0; i < userList.size( ); i++ ) {
>                    /* Retrieve an element from the list */
>                    userInfo = ( UserInfo )userList.get( i );
>                    /* Retrieve and display user id */
>                    System.out.println( "- User ID: " + userInfo.getUserId( ) );

>                    /* Display attributes ? */
>                    if( isGetAttributes ) {
>                       /* Retrieve eMail address */
>                       if( ( eMail = userInfo.getEMailAddress( ) ) == null )
>                          /* Assigned 'none' if none defined for this user */
>                          eMail = "None";

>                       /* Retrieve default organization id */
>                       if( ( defaultOrgId = userInfo.getDefaultOrgId( ) ) == null )
>                          /* Assigned 'none' if none defined for this user */
>                          defaultOrgId = "None";

>                       /* Retrieve calendar id */
>                       if( ( calendarId = userInfo.getCalendarId( ) ) == null )
>                          /* Assigned 'none' if none defined for this user */
>                          calendarId = "None";

>                       /* Display email address, default ord id and calendar id */
>                       System.out.println( "  Attributes:\n  - eMail: " + eMail );
>                       System.out.println( "  - Default ORG ID: " + defaultOrgId );
>                       System.out.println( "  - Calendar ID=" + calendarId + "\n" );
>                    }
>                 }
>                 break;
>                 .
>                 .
>                 .

Getting User Information

The following excerpt shows how to get information about a user:

>              /* List User Info */
>              case '5' :
>                 /* Get User ID for the user to display */
>                 if( ( userId = askQuestion( "\nEnter User ID" ) ) == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 try {
>                    /* WLPI Public API Method */
>                    /* Retrieve info on this user */
>                    userInfo = principal.getUserInfo( userId );

>                    /* Retrieve and display user id */
>                    System.out.println( "- User ID: " + userInfo.getUserId( ) );

>                    /* Retrieve eMail address */
>                    if( ( eMail = userInfo.getEMailAddress( ) ) == null )
>                       /* Assigned 'none' if none defined for this user */
>                       eMail = "None";

>                    /* Retrieve default organization id */
>                    if( ( defaultOrgId = userInfo.getDefaultOrgId( ) ) == null )
>                       /* Assigned 'none' if none defined for this user */
>                       defaultOrgId = "None";

>                    /* Retrieve calendar id */
>                    if( ( calendarId = userInfo.getCalendarId( ) ) == null )
>                       /* Assigned 'none' if none defined for this user */
>                       calendarId = "None";

>                    /* Display email address, default ord id and calendar id */
>                    System.out.println( "  Attributes:\n  - eMail: " + eMail );
>                    System.out.println( "  - Default ORG ID: " + defaultOrgId );
>                    System.out.println( "  - Calendar ID=" + calendarId + "\n" );
>                 }
>                 catch( Exception e ) {
>                    System.out.println( "*** Unable to retrieve user info\n" );
>                    System.err.println( e );
>                 }
>                 break;
>                 .
>                 .
>                 .

Getting User Organizations

The following excerpt shows how to get a list of the user organizations:

>              /* List Organizations for a User */
>              case '6' :
>                 /* Get User ID for user to query for */
>                 if( ( userId = askQuestion( "\nEnter User ID" ) ) == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 /* Prompt user to select if we need to display the
>                  * organization attributes */
>                 if( ( answer = askQuestion(
>                    "List Organization attributes (y/n)?" ) ) == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 /* Parse the answer */
>                 isGetAttributes = ( answer.equals( "y" ) || answer.equals( "Y" ) );

>                 /* WLPI Public API Method */
>                 /* Retrieve all organizations where this user is assigned */
>                 /* NOTE: Would be nice to add code to capture any
>                  * thrown exceptions */
>                 List orgList = principal.getOrganizationsForUser(
>                    userId, isGetAttributes );

>                 /* Assigned to any organizations ? */
>                 if( orgList.size( ) == 0 )
>                    System.out.println( "\nNot assigned to any organization" );
>                 else
>                    System.out.println( "\nAssigned to organizations:" );

>                 /* Process the list to display organizations and attributes */
>                 for( int i = 0; i < orgList.size( ); i++ ) {
>                    /* Retrieve an element from the list */
>                    OrganizationInfo orgInfo = ( OrganizationInfo )orgList.get( i );
>                    /* Retrieve and display organization id */
>                    System.out.println( "- Org ID: " + orgInfo.getOrgId( ) );

>                    /* Display attributes ? */
>                    if( isGetAttributes ) {
>                       /* Retrieve calendar id */
>                       if( ( calendarId = orgInfo.getCalendarId( ) ) == null )
>                          /* Assigned 'none' if none defined for this organization */
>                          calendarId = "None";

>                       /* Display calendar id */
>                       System.out.println(
>                          "  Attributes: Calendar ID=" + calendarId + "\n" );
>                    }
>                 }
>                 break;
>                 .
>                 .
>                 .

Getting User Roles

The following excerpt shows how to get all roles to which a user is assigned:

>              /* List Roles for a User */
>              case '7' :
>                 /* Get User ID for user to query for */
>                 if( ( userId = askQuestion( "\nEnter User ID" ) ) == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 /* Get Organization ID to query */
>                 if( ( orgId = askQuestion( "Enter Organization ID" ) ) == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>     //           /* Prompt user to select if we need to display the role attributes */
>     //          if( ( answer = askQuestion(
>     //             "List Role attributes (y/n)?" ) ) == null ) {
>     //             /* User cancelled the operation */
>     //             System.out.println( "*** Cancelled" );
>     //             break;
>     //          }
>     //
>     //          /* Parse the answer */
>     //          isGetAttributes = ( answer.equals( "y" ) ||
>     //             answer.equals( "Y" ) );
>                 isGetAttributes = false;

>                 /* WLPI Public API Method */
>                 /* Retrieve all roles where this user is assigned */
>                 /* NOTE: Would be nice to add code to capture any
>                  * thrown exceptions */
>                 List roleList = principal.getRolesForUser(
>                    orgId, userId, isGetAttributes );

>                 /* Assigned to any role ? */
>                 if( roleList.size( ) == 0 )
>                    System.out.println( "\nNot assigned to any role" );
>                 else
>                    System.out.println( "\nAssigned to roles:" );

>                 /* Process the list to display roles and attributes */
>                 for( int i = 0; i < roleList.size( ); i++ ) {
>                    /* Retrieve an element from the list */
>                    RoleInfo roleInfo = ( RoleInfo )roleList.get( i );
>                    /* Retrieve and display role id */
>                    System.out.println( "- Role ID: " + roleInfo.getRoleId( ) );

>                    /* Display attributes ? */
>                    if( isGetAttributes ) {
>                       /* Retrieve calendar id */
>                       if( ( calendarId = roleInfo.getCalendarId( ) ) == null )
>                          /* Assigned 'none' if none defined for this role */
>                          calendarId = "None";

>                       /* Display calendar id */
>                       System.out.println(
>                          "  Attributes: Calendar ID=" + calendarId + "\n" );
>                    }
>                 }
>                 break;

>              /* Return to previous menu */
>              case 'B' :
>                 return;

>              /* Exit tool */
>              case 'Q' :
>                 /* Disconnect from the server */
>                 disconnect( );
>                 System.exit( 1 );

>                 default:
>                 System.out.println( "*** Invalid selection" );
>              }
>           }
>        }
>        /* "Unhandled" exceptions */
>        catch( Exception e ) {
>           System.err.println( e );
>        }
>        return;
>     }

Mapping Security Information

Once you have defined the users and roles, you must define the relationship between these users and roles and the users and groups defined for BEA WebLogic Server, respectively, by mapping roles to the BEA WebLogic Server security realms.

This section explains how to perform the tasks required for such mapping:

- Getting the Security Realm Groups

- Mapping a Role to a Group

- Mapping Multiple Roles to Groups

- Getting the Group Mapping for a Role

- Getting the Group Mappings for All Roles Defined for an Organization

Getting the Security Realm Groups

To get a list of BEA WebLogic Server security realm groups, use the following com.bea.wlpi.server.principal.WLPIPrincipal method:

>     public java.util.List getGroups(
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

This method returns a list of security realm group names.

For example, the following code gets the security realm group names and saves them to the groups list. In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB.

>     List groups = principal.getGroups();

For more information about the getGroups() method, see the com.bea.wlpi.server.principal.WLPIPrincipal Javadoc.

Mapping a Role to a Group

To map a BPM role to a BEA WebLogic Server security realm group, use the following com.bea.wlpi.server.principal.WLPIPrincipal method:

>     public void mapRoleToGroup(
>       java.lang.String roleId,
>       java.lang.String orgId,
>       java.lang.String groupId
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

The following table describes the mapRoleToGroup() method parameters for which you must specify values.

Table 9-26 mapRoleToGroup() Method Parameters

Parameter | Description | Valid Values
--- | --- | ---
roleId | ID of the role that you want to map. | String specifying a valid role ID. For information about getting a list of all role IDs, see Getting the Roles Defined for an Organization.
orgId | ID of the organization associated with the role. | String specifying a valid organization ID. For information about getting a list of all organization IDs, see Getting All Organizations.
groupId | ID of the security realm group to which you want to map the role. | String specifying a new or existing group ID. If the specified security realm group does not exist, this method creates it. For information about getting a list of group IDs, see Getting the Security Realm Groups.

For example, the following code maps the role1 role in the ORG1 organization to the admin security realm. In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB.

>     principal.mapRoleToGroup("role1", "ORG1", "admin");

For more information about the mapRoleToGroup() method, see the com.bea.wlpi.server.principal.WLPIPrincipal Javadoc.

Mapping Multiple Roles to Groups

To map multiple BPM roles to BEA WebLogic Server security realm groups, use the following com.bea.wlpi.server.principal.WLPIPrincipal method:

>     public void mapRolesToGroups(
>       java.lang.String orgId,
>       java.util.Map rolesToGroupMap
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

The following table describes the mapRoleToGroup() method parameters for which you must specify values.

Table 9-27 mapRoleToGroup() Method Parameters

Parameter | Description | Valid Values
--- | --- | ---
orgId | ID of the organization associated with the roles. | String specifying a valid organization ID. For information about getting a list of all organization IDs, see Getting All Organizations.
rolesToGroupMap | Map object specifying the role and group relationships. | Map object with key-value pairs, specifying the role ID as the key and the group ID as the value. If the specified security realm group does not exist, this method creates it.

For example, the following code maps roles to groups as defined in the map1 map for the ORG1 organization. In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB.

>     principal.mapRolesToGroups("ORG1", "map1");

For more information about the mapRolesToGroups() method, see the com.bea.wlpi.server.principal.WLPIPrincipal Javadoc.

Getting the Group Mapping for a Role

To get the name of the group to which a role is mapped, use the following com.bea.wlpi.server.principal.WLPIPrincipal method:

>     public java.lang.String getMappedGroup(
>       java.lang.String roleId,
>       java.lang.String orgId
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

The following table describes the getMappedGroup() method parameters for which you must specify values.

Table 9-28 getMappedGroup() Method Parameters

Parameter | Description | Valid Values
--- | --- | ---
roleId | ID of the role for which you want to get the mapped group. | String specifying a valid role ID. For information about getting a list of all organization IDs, see Getting the Roles Defined for an Organization.
orgId | ID of the organization associated with the role. | String specifying a valid organization ID. For information about getting a list of all organization IDs, see Getting All Organizations.

This method returns the security realm group to which the specified role is mapped, or null if no mapping exists.

For example, the following code returns the mapped group associated with the role1 role in the ORG1 organization. In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB.

>     principal.getMappedGroups("role1", "ORG1");

For more information about the getMappedGroups() method, see the com.bea.wlpi.server.principal.WLPIPrincipal Javadoc.

Getting the Group Mappings for All Roles Defined for an Organization

To get a list of the groups to which all roles defined for an organization are mapped, use the following com.bea.wlpi.server.principal.WLPIPrincipal method:

>     public java.util.Map getRoleMappingsInOrg(
>       java.lang.String orgId
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

The following table describes the getRoleMappingsInOrg() method parameter for which you must specify a value.

Table 9-29 getRoleMappingsInOrg() Method Parameters

Parameter | Description | Valid Values
--- | --- | ---
orgId | ID of the organization for which you want to get all role-to-group mappings. | String specifying a valid organization ID. For information about getting a list of all organization IDs, see Getting All Organizations.

This method returns a map of key-value pairs in which the role ID is specified as the key, and the group ID, as the value.

For example, the following code returns the role-to-group map for the ORG1 organization. In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB.

>     Map map = principal.getRoleMappingsInOrg("ORG1");

For more information about the getRoleMappingsInOrg() method, see the com.bea.wlpi.server.principal.WLPIPrincipal Javadoc.

Configuring Permissions

You can configure permissions for both roles and users as a means of protecting access to specific BPM functions.

This section describes the permissions and explains how to perform the tasks associated with configuring permissions:

- Permissions Overview

- Getting Permissions for All Roles

- Getting Permissions for a Role

- Getting Permissions for All Users

- Getting the Permissions for a User

- Determining Whether a Specific Permission Is Set

- Setting Role-Specific Permissions

- Setting User-Specific Permissions

Permissions Overview

The following table describes the permissions that can be set for each role and/or user, and the associated com.bea.wlpi.common.security.EnumPermission static value that can be used when setting permissions. For information about setting permissions for particular roles and users, see Setting Role-Specific Permissions and Setting User-Specific Permissions, respectively.

Table 9-30 Permissions

Permission | Description | EnumPermission Static Value
--- | --- | ---
Configure System | Update application configuration, for example, by adding, updating, or deleting business calendars. | P_Configure_System
Configure Components | Define, update, and delete business operations. Load and configure plug-ins. | P_Configure_Components
Administer User | Manage organizations, roles, and users. Specify levels of permission for roles and users. Update task routes. | P_Admininister_User
Monitor Instance | Monitor (but not edit) instances, business calendars, workload reports, and statistics reports. | P_Monitor_Instance
Create Template | Create templates. | P_Create_Template
Delete Template | Delete templates. | P_Delete_Template
Execute Template | Execute templates. | P_Execute_Template

For more information about permissions, see the com.bea.wlpi.common.security.EnumPermission Javadoc.

Getting Permissions for All Roles

To get all role permissions, use the following com.bea.wlpi.server.permission.Permission method:

>     public java.util.List getAllRolePermissions(
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

Note: Execution of the getAllRolePermissions() method may require a substantial amount of resources, and should not be executed during run-time operations.

This method returns a list of com.bea.wlpi.common.security.RolePermissionInfo objects. To access information about the permissions for a role, use the RolePermissionInfo object methods described in RolePermissionInfo Object.

For example, the following code returns all role permissions. In this example, principal represents the EJBObject reference to the WLPIPrincipal EJB.

>     List rolePermissions = principal.getAllRolePermissions();

For more information about the getAllRolePermissions() method, see the com.bea.wlpi.server.permission.Permission Javadoc.

Getting Permissions for a Role

To get a list of the permissions assigned to a role, use the following com.bea.wlpi.server.permission.Permission method:

>     public com.bea.wlpi.common.RolePermissionInfo getRolePermissions(
>       java.lang.String roleName,
>       java.lang.String orgId
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

The following table describes the getRolePermissions() method parameters for which you must specify values.

Table 9-31 getRolePermissions() Method Parameters

Parameter | Description | Valid Values
--- | --- | ---
roleName | Name of the role for which you want permissions to be returned. | String specifying a valid role name. For information about getting a list of roles, see Getting the Roles Defined for an Organization.
orgId | ID of the organization for which you want to get all role-to-group mappings. | String specifying a valid organization ID. For information about getting a list of all organization IDs, see Getting All Organizations.

This method returns a com.bea.wlpi.common.security.RolePermissionInfo object. To access information about a specific role, use the RolePermissionInfo object methods described in RolePermissionInfo Object.

For example, the following code returns the permissions for the role1 role in the ORG1 organization. In this example, permission represents the EJBObject reference to the Permission EJB.

>     RolePermissionInfo rolePermissions =
>       permission.getRolePermissions("role1", "ORG1");

For more information about the getRolePermissions() method, see the com.bea.wlpi.server.permission.Permission Javadoc.

Getting Permissions for All Users

To get all user permissions, use one of the following com.bea.wlpi.server.permission.Permission methods.

Method 1

>     public java.util.List getAllUserPermissions(
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

Method 2

>     public java.util.List getAllUserPermissions(
>       boolean getRoles
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

Note: Execution of the getAllUserPermissions() method may require a substantial amount of resources, and should not be executed during run-time operations.

The following table describes the getAllUserPermissions() method parameter for which you must specify a value.

Table 9-32 getAllUserPermissions() Method Parameter

Parameter | Description | Valid Values
--- | --- | ---
getRoles | Boolean flag specifying whether or not to include the permissions that are inherited from the roles to which the user belongs. | true (role permissions are returned) or false (role permissions are not returned).

Each method returns a list of com.bea.wlpi.common.security.UserPermissionInfo objects. The first method returns the permissions that are inherited from the roles to which the user is assigned, by default. The second method determines whether or not to return the inherited role permissions based on the value of the getRoles Boolean flag value. To access the information about user-specific permissions, use the UserPermissionInfo object methods described in UserPermissionInfo Object.

For example, the following code returns all the permissions set for a user (and the permissions that are inherited from the roles to which the user is assigned by default). In this example, permission represents the EJBObject reference to the Permission EJB.

>     List userPermissions = principal.getAllUserPermissions();

For more information about the getAllUserPermissions() method, see the com.bea.wlpi.server.permission.Permission Javadoc.

Getting the Permissions for a User

To get a list of permissions associated with a specific user, use one of the following com.bea.wlpi.server.permission.Permission methods.

Method 1

>     public com.bea.wlpi.common.UserPermissionInfo getUserPermissions(
>       java.lang.String userName
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

Method 2

>     public com.bea.wlpi.common.UserPermissionInfo getUserPermissions(
>       java.lang.String userName,
>       boolean getRoles
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

The following table describes the getUserPermissions() method parameters for which you must specify values.

Table 9-33 getUserPermissions() Method Parameters

Parameter | Description | Valid Values
--- | --- | ---
userName | Name of the user for whom you want permissions returned. | String specifying a valid user name. For information about getting a list of users, see Getting the Users Defined for an Organization.
getRoles | Boolean flag specifying whether or not the roles to which the user is assigned are also returned. | true (roles are returned) or false (roles are not returned).

Each method returns a com.bea.wlpi.common.security.UserPermissionInfo object. The first method also returns a list of the roles to which the user is assigned, by default. The second method determines whether or not to return the list of roles, based on the value of the getRoles Boolean flag. To access information about user-specific permissions, use the UserPermissionInfo object methods described in UserPermissionInfo Object.

For example, the following code returns all the permissions set for a user (and the roles to which the user is assigned, by default). In this example, permission represents the EJBObject reference to the Permission EJB.

>     List userPermissions = permission.getUserPermissions();

For more information about the getUserPermissions() method, see the com.bea.wlpi.server.permission.Permission Javadoc.

Determining Whether a Specific Permission Is Set

To determine whether a specific permission is set for a PermissionInfo object, use the following com.bea.wlpi.common.security.PermissionInfo method:

>     public boolean hasPermission(
>       com.bea.wlpi.common.security.EnumPermission permission
>     )

The following table describes the hasPermission() method parameter for which you must specify a value.

Table 9-34 hasPermission() Method Parameter

Parameter | Description | Valid Values
--- | --- | ---
permission | Name of the permission for which you want to check. | An EnumPermission object that specifies the permission for which you want to check. For more information about the permissions that can be set, see Permissions Overview.

This method returns a Boolean value indicating whether or not the specified permission exists as part of the object.

For example, the following code determines whether the specific permission is set. In this example, permissionInfo represents an object reference to the PermissionInfo class.

>     boolean hasPermission =
>       permissionInfo.hasPermission(P_Administer_User);

For more information about the hasPermission() method, see the com.bea.wlpi.server.permission.Permission Javadoc.

Setting Role-Specific Permissions

You can set a specific permission or a group of permissions for one or more roles using the methods described in this section.

Setting Permissions for a Specific Role

To set permissions for a specific role, use the following com.bea.wlpi.common.security.PermissionInfo method:

>     public void setPermission(
>       com.bea.wlpi.common.security.EnumPermission permission,
>       boolean value
>     )

The following table describes the setPermission() method parameter for which you must specify a value.

Table 9-35 setPermission() Method Parameters

Parameter | Description | Valid Values
--- | --- | ---
permission | Role-specific permission to be set. | Valid permission. For a list of valid permissions, see the table Permissions.

For example, the following code sets the Administer User permission for the PermissionInfo object. In this example, permissionInfo represents an object reference to the PermissionInfo class.

>     permissionInfo.setPermission(P_Administer_User);

For more information, see PermissionInfo Object.

Setting a Group of Permissions for Multiple Roles

To set a group of permissions for one or more roles, use the following com.bea.wlpi.server.permission.Permission method:

>     public void setRolePermissions(
>       java.util.List roleInfo
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

The following table describes the setRolePermissions() method parameter for which you must specify a value.

Table 9-36 setRolePermissions() Method Parameters

Parameter | Description | Valid Values
--- | --- | ---
roleInfo | Updated information about the permissions for a role. | A list of RolePermissionInfo objects. For information about getting a list of all RolePermissionInfo objects, see Getting Permissions for All Roles. For information about defining a RolePermissionInfo object, see RolePermissionInfo Object.

For example, the following code sets role-specific permissions according to the information defined within the roleInfo RolePermissionInfo object. In this example, permission represents the EJBObject reference to the Permission EJB.

>     permission.setRolePermissions(roleInfo);

For more information about the setRolePermissions() method, see the com.bea.wlpi.server.permission.Permission Javadoc.

Setting User-Specific Permissions

You can set a specific permission or a group of permissions for one or more users using the methods described in this section.

Setting a Single User-Specific Permission

To set a single permission for a specific user, use the following com.bea.wlpi.common.security.PermissionInfo method:

>     public void setPermission(
>       com.bea.wlpi.common.security.EnumPermission permission,
>       boolean value
>     )

The following table describes the setPermission() method parameter for which you must specify a value.

Table 9-37 setPermission() Method Parameters

Parameter | Description | Valid Values
--- | --- | ---
permission | User-specific permission to be set. | Valid permission. For a list of valid permissions, see the table Permissions.

For example, the following code sets the Administer User permission for the PermissionInfo object. In this example, permissionInfo represents an object reference to the PermissionInfo class.

>     permissionInfo.setPermission(P_Administer_User);

For more information, see PermissionInfo Object.

Setting a Group of Permissions for Multiple Users

To set a group of permissions for one or more users, use the following com.bea.wlpi.server.principal.WLPIPrincipal method:

>     public void setUserPermissions(
>       java.util.List userInfo
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

The following table describes the setUserPermissions() method parameter for which you must specify a value.

Table 9-38 setUserPermissions() Method Parameters

Parameter | Description | Valid Values
--- | --- | ---
userInfo | Updated information about user-specific permissions. | A list of UserPermissionInfo objects. For information about getting a list of all UserPermissionInfo objects, see Getting Permissions for All Users. For information about defining a UserPermissionInfo object, see UserPermissionInfo Object.

For example, the following code sets the user permissions according to the information defined within the userInfo UserPermissionInfo object. In this example, permission represents the EJBObject reference to the Permission EJB.

>     permission.setUserPermissions(userInfo);

For more information about the setUserPermissions() method, see the com.bea.wlpi.server.permission.Permission Javadoc.