edu.internet2.middleware.grouper.eg

Class Bootstrap

java.lang.Object

edu.internet2.middleware.grouper.eg.Bootstrap

public class Bootstrap
extends Object

EXAMPLE Bootstrap your Groups Registry by creating a sysadmin (wheel) group.

Running ant eg.bootstrap will run this example code.

Step 0: Import Required Packages

To begin using the Grouper API you will first need to import the Grouper API, located in the edu.internet2.middleware.grouper package. For many operations, including those in this example, you will also need to import the I2MI Subject API which is located in the edu.internet2.middleware.subject package.

 import edu.internet2.middleware.grouper.*; // Import Grouper API
 import edu.internet2.middleware.subject.*; // Import Subject API
 

Step 1: Find GrouperSystem Subject

The next step is to find the GrouperSystem subject. This subject is internal to the Grouper API and is the "root" user for your Groups Registry. As normal access and naming privileges do not apply to GrouperSystem you must as as this subject to bootstrap your registry for use by others.

 Subject grouperSystem = SubjectFinder.findRootSubject();
 

Step 2: Start Session

Almost all Grouper API operations take place within the context of a GrouperSession and each session has an associated subject. The privilegs of the session's subject determine what API actions can be performed. As this session will be acting as GrouperSystem there will be no restrictions.

 try {
  GrouperSession s = GrouperSession.start(grouperSystem);  
 }
 catch (SessionException eS) {
   // Error starting session
 }
 

Step 3: Find Root Stem

At the very base of the Groups Registry is the root stem. All other stems and groups in the registry descend from this stem.

 Stem root = StemFinder.findRootStem(s);
 

Step 4: Find Or Add Top-Level Stem "etc" (or whatever is configured in grouper.properties)

After retrieving the root stem you can create a new top-level stem, in this case named "etc", beneath the root stem.

 Stem   etc;
 String extn         = "etc";
 String displayExtn  = "Grouper Administration";
 // check to see if stem already exists
 try {
   etc = StemFinder.findByName(s, extn);
 }
 catch (StemNotFoundException eNSNF) {
   // create stem if it doesn't exist
   try {
     etc = root.addChildStem(extn, displayExtn);
   }
   catch (InsufficientPrivilegeException eIP) {
     // not privileged to create top-level stem
   }
   catch (StemAddException eNSA) {
     // error adding top-level stem
   }
 }
 

However, we are creating a dynamically named stem based on the wheel group named in grouper.properties:

    try {
      this.etc = Stem.saveStem(this.s, etcStem, null, etcStem, displayExtn, null, SaveMode.INSERT_OR_UPDATE, true);
      System.err.println("created top-level stem: " + this.etc);
    }
    catch (Exception eIP) {
      throw new GrouperRuntimeException( "error adding top-level stem: " + eIP.getMessage() + ", " + etcStem, eIP );
    }
 

Step 5: Find Or Add Sysadmin Group "etc:sysadmin" (or whatever is configured in grouper.properties)

After adding the top-level "etc" stem you can then create the wheel group ("etc:sysadmin") beneath it.

 Group   wheel;
 String  extn        = "wheel";
 String  displayExtn = "Wheel Group";
 // check to see if group exists
 try {
   wheel = GroupFinder.findByName( s, etc.getName() + ":" + extn );
 }
 catch (GroupNotFoundException eGNF) {
   try {
     // create group if it doesn't exist
     wheel = etc.addChildGroup(extn, displayExtn);
   }
   catch (GroupAddException eGA) {
     // error adding wheel group
   } 
   catch (InsufficientPrivilegeException eIP) {
     // not privileged to create wheel group
   }
 }
 

However, we are doing things more dynamically:

    try {
      // create group if it doesn't exist
      this.wheel = Group.saveGroup(this.s, wheelGroupName, null, wheelGroupName, displayExtn, null, SaveMode.INSERT_OR_UPDATE, true);
      System.err.println("created sysadmin (wheel) group: " + this.wheel);
    }
    catch (Exception eGA) {
      throw new GrouperRuntimeException( "error adding sysadmin group: " + eGA.getMessage() + ", " + wheelGroupName, eGA );
    }
 

Step 6: Find GrouperAll Subject

GrouperAll is another subject internal to Grouper. When you assign a membership or grant a privilege to GrouperAll it is the equivalent of performing that operation for *all subjects*..

 Subject grouperAll = SubjectFinder.findAllSubject();
 

Step 7: Add GrouperAll As Member Of The Wheel Group

Now that the wheel group exists you may add members to it. Provided you have enabled use of a wheel group in conf/grouper.properties all members added to this group will now have root-like privileges over the entire Groups Registry.

 // verify GrouperAll is not already a member before attempting to add it
 if ( !wheel.hasMember(grouperAll) ) {
   try {
     // this is *not* recommend for most grouper deployments as it will give every
     // subject root-like privileges over the entire groups registry. 
     wheel.addMember(grouperAll);
   }
   catch (InsufficientPrivilegeException eIP) {
     // not privileged to add GrouperAll as member to wheel group
   }
   catch (MemberAddException eMA) {
     // error adding GrouperAll as member to wheel group
   }
 }
 

Step 8: Stop Session

The final action after bootstrapping your Groups Registry is to stop the session you started at the beginning of the bootstrapping process.

 try {
  s.stop();
 }
 catch (SessionException eS) {
   // Error stopping session
 }
 

Since:

1.2.0

Version:

$Id: Bootstrap.java,v 1.6 2009-03-15 06:37:24 mchyzer Exp $

See Also:

Source

Method Summary

Modifier and Type	Method and Description
static void	main(String[] args) Run example code.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

main

public static void main(String[] args)

Run example code.

Since:

1.2.0