Java AFS Admin API v1.3

org.openafs.jafsadm
Class Group

java.lang.Object
  |
  +--org.openafs.jafsadm.Group
All Implemented Interfaces:
Comparable, PTSEntry, Serializable

public class Group
extends Object
implements PTSEntry, Serializable, Comparable

An abstract representation of an AFS group. It holds information about the group, such as what groups it owns.

Constructing an instance of a Group does not mean an actual AFS group is created in a cell -- usually a Group object is a representation of an already existing AFS group. If, however, the Group is constructed with the name of a group that does not exist in the cell represented by the provided Cell, a new group with that name can be created in that cell by calling the create(String, int) or create(String) method. If such a group does already exist when one of these methods is called, an exception will be thrown.

Each Group object has its own individual set of Groups that it owns and Users that belong to it. These represents the properties and attributes of an actual AFS group.

Associated with an AFS group are many attributes, such as whether or not who is allowed to list the members of this group. The Group class has many "set" methods to indicate values for these attributes (i.e. setListMembership(int). However, in order for these values to be written to the actual AFS group, the flushInfo() method needs to be called. This writes all user attributes set through this API to AFS. This is done to minimize calls through JNI.

The following is a simple example of how to construct and use a Group object. It lists the name and owner of a specified group.

 import org.openafs.jafsadm.Cell;
 import org.openafs.jafsadm.AFSAdminException;
 import org.openafs.jafsadm.Partition;
 import org.openafs.jafsadm.Group;
 ...
 public class ...
 {
   ...
   private Cell cell;
   private Group group;
   ...
   public static void main(String[] args) throws Exception
   {
     String username   = arg[0];
     String password   = arg[1];
     String cellName   = arg[2];
     String groupName  = arg[3];
 
     cell  = new Cell(cellName, username, password);
     group = new Group(groupName, cell);
     
     System.out.println("Owner of group " + group.getName() + " is " 
                        + group.getOwnerName());
     ...
   }
   ...
 }
 

Version:
1.0, 2/15/02
See Also:
Serialized Form

Field Summary
static int GROUP_ANYUSER_ACCESS
          Any user has access
static int GROUP_GROUP_ACCESS
          Members of the group have access
static int GROUP_OWNER_ACCESS
          Only the owner of the group has access
 
Fields inherited from interface org.openafs.jafsadm.PTSEntry
PTS_GROUP, PTS_USER
 
Constructor Summary
Group(String name, Cell cell)
          Constructs a new Group object instance given the name of the AFS group and the AFS cell, represented by cell, to which it belongs.
Group(String name, Cell cell, boolean preloadAllMembers)
          Constructs a new Group object instance given the name of the AFS group and the AFS cell, represented by cell, to which it belongs.
 
Method Summary
 void addMember(User theUser)
          Add the specified member to this group.
 void changeOwner(Group theOwner)
          Change the owner of this group.
 void changeOwner(User theOwner)
          Change the owner of this group.
 int compareTo(Group group)
          Compares two Group objects respective to their names and does not factor any other attribute.
 int compareTo(Object obj)
          Comparable interface method.
 void create(String ownerName)
          Creates the PTS entry for a new group in this cell.
 void create(String ownerName, int gid)
          Creates the PTS entry for a new group in this cell.
 void delete()
          Deletes the PTS entry for a group in this cell.
 boolean equals(Group otherGroup)
          Tests whether two Group objects are equal, based on their names.
 void flushInfo()
          Flushes the current information of this Group object to disk.
 Cell getCell()
          Returns the Cell this group belongs to.
 PTSEntry getCreator()
          PTS: Returns the creator of this group in the form of a PTSEntry.
 Group[] getGroupsOwned()
          Returns an array of the Group objects this group owns.
 String[] getGroupsOwnedNames()
          Returns an array of the group names this group owns.
 int getListAdd()
          Returns who can add members (pts adduser) to this group.
 int getListDelete()
          Returns who can delete members (pts removemember) from this group.
 int getListGroupsOwned()
          Returns who can list the groups owned (pts listowned) by this group.
 int getListMembership()
          Returns who can list the users (pts membership) that belong to this group.
 int getListStatus()
          Returns who can list the status (pts examine) of this group.
 String[] getMemberNames()
          Returns an array of the member names of this group.
 User[] getMembers()
          Returns an array of the User object members of this group.
 int getMembershipCount()
          Returns the number of members of this group.
 String getName()
          Returns the name of this group.
 PTSEntry getOwner()
          PTS: Returns the owner of this group in the form of a PTSEntry.
 short getType()
          Returns the type of PTSEntry this object represents.
 int getUID()
          Returns the numeric AFS id of this group.
 void refresh()
          Refreshes the properties of this Group object instance with values from the AFS group it represents.
 void removeMember(User theUser)
          Remove the specified member from this group.
 void rename(String newName)
          Change the name of this group.
 void setListAdd(int value)
          Sets who can add members (pts adduser) to this group.
 void setListDelete(int value)
          Sets who can delete members (pts removemember) from this group.
 void setListGroupsOwned(int value)
          Sets who can list the groups owned (pts listowned) by this group.
 void setListMembership(int value)
          Sets who can list the users (pts membership) that belong to this group.
 void setListStatus(int value)
          Sets who can list the status (pts examine) of this group.
 String toString()
          Returns the name of this Group
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

GROUP_OWNER_ACCESS

public static final int GROUP_OWNER_ACCESS
Only the owner of the group has access

GROUP_GROUP_ACCESS

public static final int GROUP_GROUP_ACCESS
Members of the group have access

GROUP_ANYUSER_ACCESS

public static final int GROUP_ANYUSER_ACCESS
Any user has access
Constructor Detail

Group

public Group(String name,
             Cell cell)
      throws AFSAdminException
Constructs a new Group object instance given the name of the AFS group and the AFS cell, represented by cell, to which it belongs. This does not actually create a new AFS group, it just represents one. If name is not an actual AFS group, exceptions will be thrown during subsequent method invocations on this object, unless the create(String, int) or create(String) method is explicitly called to create it.
Parameters:
name - the name of the group to represent
cell - the cell to which the group belongs.
Throws:
AFSAdminException - If an error occurs in the native code

Group

public Group(String name,
             Cell cell,
             boolean preloadAllMembers)
      throws AFSAdminException
Constructs a new Group object instance given the name of the AFS group and the AFS cell, represented by cell, to which it belongs. This does not actually create a new AFS group, it just represents one. If name is not an actual AFS group, exceptions will be thrown during subsequent method invocations on this object, unless the create(String, int) or create(String) method is explicitly called to create it. Note that if the process doesn't exist and preloadAllMembers is true, an exception will be thrown.

This constructor is ideal for point-in-time representation and transient applications. It ensures all data member values are set and available without calling back to the filesystem at the first request for them. Use the refresh() method to address any coherency concerns.

Parameters:
name - the name of the group to represent
cell - the cell to which the group belongs.
preloadAllMembers - true will ensure all object members are set upon construction; otherwise members will be set upon access, which is the default behavior.
Throws:
AFSAdminException - If an error occurs in the native code
See Also:
refresh()
Method Detail

create

public void create(String ownerName)
            throws AFSAdminException
Creates the PTS entry for a new group in this cell. Automatically assigns a group id.
Parameters:
ownerName - the owner of this group

create

public void create(String ownerName,
                   int gid)
            throws AFSAdminException
Creates the PTS entry for a new group in this cell.
Parameters:
ownerName - the owner of this group
gid - the group id to assign to the new group
Throws:
AFSAdminException - If an error occurs in the native code

delete

public void delete()
            throws AFSAdminException
Deletes the PTS entry for a group in this cell. Deletes this group from the membership list of the user that belonged to it, but does not delete the groups owned by this group. Also nullifies the Java object.
Throws:
AFSAdminException - If an error occurs in the native code

flushInfo

public void flushInfo()
               throws AFSAdminException
Flushes the current information of this Group object to disk. This will update the information of the actual AFS group to match the settings that have been modified in this Group object. This function must be called before any changes made to the information fields of this group will be seen by the AFS system.
Throws:
AFSAdminException - If an error occurs in the native code

addMember

public void addMember(User theUser)
               throws AFSAdminException
Add the specified member to this group.
Parameters:
userName - the User object to add
Throws:
AFSAdminException - If an error occurs in the native code

removeMember

public void removeMember(User theUser)
                  throws AFSAdminException
Remove the specified member from this group.
Parameters:
userName - the User object to remove
Throws:
AFSAdminException - If an error occurs in the native code

changeOwner

public void changeOwner(User theOwner)
                 throws AFSAdminException
Change the owner of this group.
Parameters:
ownerName - the new owner User object
Throws:
AFSAdminException - If an error occurs in the native code

changeOwner

public void changeOwner(Group theOwner)
                 throws AFSAdminException
Change the owner of this group.
Parameters:
ownerName - the new owner Group object
Throws:
AFSAdminException - If an error occurs in the native code

rename

public void rename(String newName)
            throws AFSAdminException
Change the name of this group.
Parameters:
newName - the new name for this group
Throws:
AFSAdminException - If an error occurs in the native code

refresh

public void refresh()
             throws AFSAdminException
Refreshes the properties of this Group object instance with values from the AFS group it represents. All properties that have been initialized and/or accessed will be renewed according to the values of the AFS group this Group object instance represents.

Since in most environments administrative changes can be administered from an AFS command-line program or an alternate GUI application, this method provides a means to refresh the Java object representation and thereby ascertain any possible modifications that may have been made from such alternate administrative programs. Using this method before an associated instance accessor will ensure the highest level of representative accuracy, accommodating changes made external to the Java application space. If administrative changes to the underlying AFS system are only allowed via this API, then the use of this method is unnecessary.

Throws:
AFSAdminException - If an error occurs in the native code

getName

public String getName()
Returns the name of this group.
Specified by:
getName in interface PTSEntry
Returns:
the name of this group

getUID

public int getUID()
           throws AFSAdminException
Returns the numeric AFS id of this group.
Specified by:
getUID in interface PTSEntry
Returns:
the AFS id of this group
Throws:
AFSAdminException - If an error occurs in the native code

getCell

public Cell getCell()
Returns the Cell this group belongs to.
Specified by:
getCell in interface PTSEntry
Returns:
the Cell this group belongs to

getMembers

public User[] getMembers()
                  throws AFSAdminException
Returns an array of the User object members of this group.
Returns:
an array of the members of this group
Throws:
AFSAdminException - If an error occurs in the native code

getMemberNames

public String[] getMemberNames()
                        throws AFSAdminException
Returns an array of the member names of this group.
Returns:
an array of the member names of this group
Throws:
AFSAdminException - If an error occurs in the native code

getGroupsOwned

public Group[] getGroupsOwned()
                       throws AFSAdminException
Returns an array of the Group objects this group owns.
Returns:
an array of the Groups this group owns
Throws:
AFSAdminException - If an error occurs in the native code

getGroupsOwnedNames

public String[] getGroupsOwnedNames()
                             throws AFSAdminException
Returns an array of the group names this group owns. Contains String objects.
Returns:
an array of the group names this group owns
Throws:
AFSAdminException - If an error occurs in the native code

getMembershipCount

public int getMembershipCount()
                       throws AFSAdminException
Returns the number of members of this group.
Returns:
the membership count
Throws:
AFSAdminException - If an error occurs in the native code

getOwner

public PTSEntry getOwner()
                  throws AFSAdminException
PTS: Returns the owner of this group in the form of a PTSEntry.

The returning object could be either a User or Group; to determine what type of object the PTSEntry represents, call the PTSEntry.getType() method.

Specified by:
getOwner in interface PTSEntry
Returns:
the owner of this group
Throws:
AFSAdminException - If an error occurs in the native code
See Also:
PTSEntry, PTSEntry.getType(), refresh()

getCreator

public PTSEntry getCreator()
                    throws AFSAdminException
PTS: Returns the creator of this group in the form of a PTSEntry.

The returning object could be either a User or Group; to determine what type of object the PTSEntry represents, call the PTSEntry.getType() method.

Specified by:
getCreator in interface PTSEntry
Returns:
the creator of this group
Throws:
AFSAdminException - If an error occurs in the native code
See Also:
PTSEntry, PTSEntry.getType(), refresh()

getType

public short getType()
Returns the type of PTSEntry this object represents.

This method will always return PTSEntry.PTS_GROUP.

Specified by:
getType in interface PTSEntry
Returns:
the type of PTSEntry this object represents (will always return PTSEntry.PTS_GROUP)
See Also:
PTSEntry, PTSEntry.getType()

getListStatus

public int getListStatus()
                  throws AFSAdminException
Returns who can list the status (pts examine) of this group. Valid values are:
Returns:
the status listing permission
Throws:
AFSAdminException - If an error occurs in the native code

getListGroupsOwned

public int getListGroupsOwned()
                       throws AFSAdminException
Returns who can list the groups owned (pts listowned) by this group. Valid values are:
Returns:
the groups owned listing permission
Throws:
AFSAdminException - If an error occurs in the native code

getListMembership

public int getListMembership()
                      throws AFSAdminException
Returns who can list the users (pts membership) that belong to this group. Valid values are:
Returns:
the membership listing permission
Throws:
AFSAdminException - If an error occurs in the native code

getListAdd

public int getListAdd()
               throws AFSAdminException
Returns who can add members (pts adduser) to this group. Valid values are:
Returns:
the member adding permission
Throws:
AFSAdminException - If an error occurs in the native code

getListDelete

public int getListDelete()
                  throws AFSAdminException
Returns who can delete members (pts removemember) from this group. Valid values are:
Returns:
the member deleting permission
Throws:
AFSAdminException - If an error occurs in the native code

setListStatus

public void setListStatus(int value)
                   throws AFSAdminException
Sets who can list the status (pts examine) of this group. Valid values are:
Parameters:
value - the value of the new list membership permission
Throws:
AFSAdminException - if an error occurs in the native code
IllegalArgumentException - if an invalud argument is provided

setListGroupsOwned

public void setListGroupsOwned(int value)
                        throws AFSAdminException
Sets who can list the groups owned (pts listowned) by this group. Valid values are:
Parameters:
value - the value of the new list membership permission
Throws:
AFSAdminException - if an error occurs in the native code
IllegalArgumentException - if an invalud argument is provided

setListMembership

public void setListMembership(int value)
                       throws AFSAdminException
Sets who can list the users (pts membership) that belong to this group. Valid values are:
Parameters:
value - the value of the new list membership permission
Throws:
AFSAdminException - if an error occurs in the native code
IllegalArgumentException - if an invalud argument is provided

setListAdd

public void setListAdd(int value)
                throws AFSAdminException
Sets who can add members (pts adduser) to this group. Valid values are:
Parameters:
value - the value of the new list membership permission
Throws:
AFSAdminException - if an invalid value is provided

setListDelete

public void setListDelete(int value)
                   throws AFSAdminException
Sets who can delete members (pts removemember) from this group. Valid values are:
Parameters:
value - the value of the new list membership permission
Throws:
AFSAdminException - if an invalid value is provided

compareTo

public int compareTo(Group group)
Compares two Group objects respective to their names and does not factor any other attribute. Alphabetic case is significant in comparing names.
Parameters:
group - The Group object to be compared to this Group instance
Returns:
Zero if the argument is equal to this Group's name, a value less than zero if this Group's name is lexicographically less than the argument, or a value greater than zero if this Group's name is lexicographically greater than the argument

compareTo

public int compareTo(Object obj)
Comparable interface method.
Specified by:
compareTo in interface Comparable
See Also:
compareTo(Group)

equals

public boolean equals(Group otherGroup)
Tests whether two Group objects are equal, based on their names.
Parameters:
otherGroup - the Group to test
Returns:
whether the specifed Group is the same as this Group

toString

public String toString()
Returns the name of this Group
Overrides:
toString in class Object
Returns:
the name of this Group

Java AFS Admin (jafsadm) API for OpenAFS

Copyright (c) 2001-2002 International Business Machines Corp.
All rights reserved.
See copyright statement.