Back to Groups Project

Client API

All client programs will interact with the groups database using the following API.

This specification consists of five parts:

Data Items

The Groups database deals in three major items: entities, groups, and individuals. An entity is either a group or an individual. Groups contain entities. An individual represents a person.

Control Functions:

Data Queries:

Data Modifications:

Use Registration:

Examples

An example of some query functions:

use Group;

# create a new groups object
$grp = new Group("schedule manager");

# get some info about an individual
%indivInfo = $grp->getEntity('uwnetid' => 'mcrawfor');
print "Name: ". %indivInfo{'name'} . "\n";

# get a list of groups which mcrawfor belongs to
%groupList = $grp->groups($indivInfo{'entityid'});

# %groupList now contains a hash: keys are entityIDs for 
# the groups, values are entityHashes for the groups, so:

foreach $item (keys %groupList){
	print $groupList{$item}{'name'} . "\n";
}

# belongsTo provides boolean membership checking:
# Note that "3" is a groupID (found with groups)
if( $grp->belongsTo( $indivInfo{'entityid'}, 3){
	print "True";
}else{
	print "False";
}

# members gets a hash of entityHashes that belong to the
# given group. The optional second argument controls the
# depth to which the membership tree is traveled.
%members = %grp->members(3,1);

# %members now contains a hash like above, so:
foreach $item (keys %members){
	print $members{$item}{'name'} . "\n";
}

#disconnect
$grp->close();

Which prints:

Name: Miles Crawford
Student Staff
Leads
Routers
FaqMan Admins
True
Miles Crawford
Michal Guerquin

Some data modification examples:

## Create a new entityHash and add it to some groups:
%newEntity = (	'name'		=>	'Mr. Tux',
		'uwnetid'	=>	'tux',
		'email'		=>	'tux@cac.washington.edu',
		'is_group'	=>	0);

@initialGroups = ( 45, 12, 43 );

%errHash = $grp->addEntity(%newEntity, \@initialGroups);

if($errHash{'error'}){
  print "An error occurred: " . $errHash{'description'};
}else{
  $tuxID = $errHash{'description'};
  print "Success, entity $tuxID was added.\n";
}


## Add Tux to some new groups:
@moreGroups = ( 23, 34 );

%errHash = $grp->joinGroup($tuxID, @moreGroups);

if($errHash{'error'}){
  print "An error occurred: " . $errHash{'description'};
}else{
  print $errHash{'description'} . "\n";
}


## Tux leaves a group or two
@oldGroups = ( 23, 12 );

%errHash = $grp->leaveGroup($tuxID, @oldGroups);

if($errHash{'error'}){
  print "An error occurred: " . $errHash{'description'};
}else{
  print $errHash{'description'} . "\n";
}


## Delete a group
%errHash = $grp->deleteEntity(34); 
#error: Tux belongs to this group

if($errHash{'error'}){
  print "An error occurred: " . $errHash{'description'};
}else{
  print $errHash{'description'} . "\n";
}

Which prints:

Success, entity 94 was added.
Successfully joined groups.
Successfully left groups.
An error occurred: Entity '34' has current members. Can't Delete.

A use registry example:

## Register our use of Tux
%errHash = $grp->registerUse($tuxID);

if($errHash{'error'}){
  print "An error occurred: " . $errHash{'description'};
}else{
  print $errHash{'description'} . "\n";
}

## Delete Tux
%errHash = $grp->deleteEntity($tuxID); 
%#error: We've registered Tux

if($errHash{'error'}){
  print "An error occurred: " . $errHash{'description'};
}else{
  print $errHash{'description'} . "\n";
}

## Release our use of Tux
%errHash = $grp->releaseUse($tuxID);

if($errHash{'error'}){
  print "An error occurred: " . $errHash{'description'};
}else{
  print $errHash{'description'} . "\n";
}


## Try to delete that lovable penguin again
%errHash = $grp->deleteEntity($tuxID); #should work now

if($errHash{'error'}){
  print "An error occurred: " . $errHash{'description'};
}else{
  print "Success, tux is gone.";
}

Which prints:

Successful register.
An error occurred: Entity '94' is used by: schedule_manager. Can't delete.
Successful release.
Success, tux is gone.

Entity List Sorting:

Frequently the groups manager will return to you hashes full of entity hashes, and it may be useful to sort these lists by name or netid, etc. Here is an example subfunction for doing this by name: 

sub sort_entity_list{
  my %orig = @_;
  my @ordered;

  @ordered = 
  sort { 
    lc($orig{$a}{'name'}) cmp lc($orig{$b}{'name'}) 
  } keys %orig;

  return @ordered;
}

Then, you can iterate through your entities in name-order:

%big_list =  $grp->allIndivs();

@order = sort_entity_list(%big_list);

foreach my $key (@order){
  print $big_list{$key}{'name'} . "\n";
}

Which prints:

Aardvark
Amos
Andy
Bob
...
Back to Groups Project