Java AFS Admin API v1.3

org.openafs.jafsadm
Class Cell

java.lang.Object
  |
  +--org.openafs.jafsadm.Cell
All Implemented Interfaces:
Serializable

public class Cell
extends Object
implements Serializable

An abstract representation of an AFS cell. It holds information about the cell, such as what users, groups, and servers exist in the cell.

Constructing a Cell object does not mean a new cell is created in the AFS file system -- on the contrary, a Cell object must be a representation of an already existing AFS cell. There is no way to create a new AFS cell through this API. See OpenAFS.org for information on how to create a new cell.

The construction of a Cell object acts as an entry point for authentication into the AFS system. Thus, when you construct a Cell, you must pass in the name of a user in the AFS cell that the Cell represents, as well as the password for that user. If the password is correct, you will be authenticated as that user and you will only be allowed to perform actions that the user is authorized to perform. You must construct a Cell before attempting to construct any other object in this package, since the other objects all require a Cell object on construction, either directly or indirectly.

Note that to successfully construct a Cell object, the code must be running on a machine with a running AFS client, and the cell this object is to represent must have an entry in the client's CellServDB file.

Each Cell object has its own individual set of Servers, Users, and Groups. This represents the properties and attributes of an actual AFS cell. If an error occurs during a method call, an AFSAdminException will be thrown. This class is the Java equivalent of errors thrown by AFS; see AFSAdminException for a complete description.

The following is a simple example of how to construct and use a Cell object. It shows how a Cell can be used to get an abstract representation of an AFS server, and how it can obtain an array of User objects, each of which is an abstract representation of an AFS user.

 import org.openafs.jafsadm.Cell;
 import org.openafs.jafsadm.AFSAdminException;
 import org.openafs.jafsadm.Partition;
 import org.openafs.jafsadm.Server;
 import org.openafs.jafsadm.User;
 ...
 public class ...
 {
   ...
   private Cell cell;
   private Server server;
   ...
   public static void main(String[] args) throws Exception
   {
     String username   = arg[0];
     String password   = arg[1];
     String cellName   = arg[2];
     String serverName = arg[3];
 
     cell   = new Cell(cellName, username, password);
     server = cell.getServer(serverName);

     User[] users = cell.getUsers();
     ...
   }
   ...
 }
 

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

Constructor Summary
Cell(String name, String username, String password)
          Constructs a new Cell object instance given the name of the AFS cell it represents and the username and password of the user to be authenticated for administrative access.
Cell(String name, String username, String password, boolean preloadAllMembers)
          Constructs a new Cell object instance given the name of the AFS cell it represents and the username and password of the user to be authenticated for administrative access.
 
Method Summary
 void close()
          Unauthenticates this Cell object and deletes all of its stored information.
 boolean equals(Cell otherCell)
          Tests whether two Cell objects are equal, based on their names.
 int getCellHandle()
          Returns the cell handle of this cell.
 Group getGroup(String name)
          Retrieves the Group object (which is an abstract representation of an actual AFS group) designated by name.
 int getGroupCount()
          Returns the total number of groups associated with this Cell.
 String[] getGroupNames()
          Retrieves an array containing all of the names of groups associated with this Cell.
 String[] getGroupNames(int startIndex, int length)
          Returns an array containing a subset of the names of groups associated with this Cell.
 Group[] getGroups()
          Retrieves an array containing all of the Group objects associated with this Cell, each of which are an abstract representation of an actual group of the AFS cell.
 Group[] getGroups(int startIndex, int length)
          Returns an array containing a subset of the Group objects associated with this Cell, each of which is an abstract representation of an actual AFS group of the AFS cell.
 int getMaxGroupID()
          Returns the maximum group ID that's been used within the cell.
 int getMaxUserID()
          Returns the maximum user ID that's been used within the cell.
 String getName()
          Returns the name of this cell.
 Server getServer(String name)
          Retrieves the Server object (which is an abstract representation of an actual AFS server) designated by name.
 int getServerCount()
          Returns the total number of servers associated with this Cell.
 String[] getServerNames()
          Retrieves an array containing all of the names of servers associated with this Cell.
 Server[] getServers()
          Retrieves an array containing all of the Server objects associated with this Cell, each of which are an abstract representation of an actual server of the AFS cell.
 GregorianCalendar getTokenExpiration()
          Returns the expiration time of the authentication token being used by this Cell object.
 User getUser(String name)
          Retrieves the User object (which is an abstract representation of an actual AFS user) designated by name.
 int getUserCount()
          Returns the total number of users who are registered with KAS and PTS, without duplicates.
 String[] getUserNames()
          Retrieves an array containing all of the names of users associated with this Cell.
 String[] getUserNames(int startIndex, int length)
          Returns an array containing a subset of the names of users associated with this Cell.
 User[] getUsers()
          Retrieves an array containing all of the User objects associated with this Cell, each of which are an abstract representation of an actual user of the AFS cell.
 User[] getUsers(int startIndex, int length)
          Returns an array containing a subset of the User objects associated with this Cell, each of which is an abstract representation of an actual AFS user of the AFS cell.
 void refresh()
          Refreshes the properties of this Cell object instance with values from the AFS cell it represents.
 void setMaxGroupID(int maxID)
          Sets the maximum group ID that's been used within the cell.
 void setMaxUserID(int maxID)
          Sets the maximum user ID that's been used within the cell.
 String toString()
          Returns the name of this Cell
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Cell

public Cell(String name,
            String username,
            String password)
     throws AFSAdminException
Constructs a new Cell object instance given the name of the AFS cell it represents and the username and password of the user to be authenticated for administrative access. In order to get full access to the cell, it is best that the username provided has administrative privileges.
Parameters:
name - the name of the cell to represent
username - the name of the user to authenticate with
password - the password of that user
Throws:
AFSAdminException - If an error occurs in the native code

Cell

public Cell(String name,
            String username,
            String password,
            boolean preloadAllMembers)
     throws AFSAdminException
Constructs a new Cell object instance given the name of the AFS cell it represents and the username and password of the user to be authenticated for administrative access. In order to get full access to the cell, it is best that the user name provided has administrative privileges.

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 AFS cell to represent
username - the username of the user to authenticate with
password - the password of that user
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

refresh

public void refresh()
             throws AFSAdminException
Refreshes the properties of this Cell object instance with values from the AFS cell it represents. All properties that have been initialized and/or accessed will be renewed according to the values of the AFS cell this Cell 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

close

public void close()
           throws AFSAdminException
Unauthenticates this Cell object and deletes all of its stored information. This method should only be called when this Cell or any of the objects constructed using this Cell will not be used anymore. Note that this does not delete the actual AFS cell that this Cell object represents; it merely closes the representation.
Throws:
AFSAdminException - If an error occurs in the native code

getUser

public User getUser(String name)
             throws AFSAdminException
Retrieves the User object (which is an abstract representation of an actual AFS user) designated by name. If a user by that name does not actually exist in AFS in the cell represented by this object, an AFSAdminException will be thrown.
Parameters:
name - the name of the user to retrieve
Returns:
User designated by name.
Throws:
AFSAdminException - If an error occurs in the native code
NullPointerException - If name is null.

getUserCount

public int getUserCount()
                 throws AFSAdminException
Returns the total number of users who are registered with KAS and PTS, without duplicates. If a user has a KAS entry and not a PTS entry, it will still be counted. Conversely, if a user has a PTS entry and not KAS, it too will be counted. Effectively it is a non-duplicate union of KAS and PTS user entries.

If the total list of users or user names have already been collected (see getUsers()), then the returning value will be calculated based upon the current list. Otherwise, KAS and PTS will be explicitly queried for the information.

Returns:
a User array of the users of the cell.
Throws:
AFSAdminException - If an error occurs in the native code
See Also:
getUsers(), getUserNames()

getUsers

public User[] getUsers()
                throws AFSAdminException
Retrieves an array containing all of the User objects associated with this Cell, each of which are an abstract representation of an actual user of the AFS cell. After this method is called once, it saves the array of Users and returns that saved array on subsequent calls, until the refresh() method is called and a more current list is obtained.
Returns:
a User array of the users of the cell.
Throws:
AFSAdminException - If an error occurs in the native code

getUsers

public User[] getUsers(int startIndex,
                       int length)
                throws AFSAdminException
Returns an array containing a subset of the User objects associated with this Cell, each of which is an abstract representation of an actual AFS user of the AFS cell. The subset is a point-in-time list of users (User objects representing AFS users) starting at the complete array's index of startIndex and containing up to length elements. If length is larger than the number of remaining elements, respective to startIndex, then this method will ignore the remaining positions requested by length and return an array that contains the remaining number of elements found in this cell's complete array of users.

This method is especially useful when managing iterations of very large lists. getUserCount() can be used to determine if iteration management is practical.

This method does not save the resulting data and therefore queries AFS for each call.

Note: PTS-only users are collected before KAS users and therefore will always, if PTS-only users exist, be within the lowest range of this cell's complete list of users. PTS and KAS users are joined in a non-duplicating union and are consequently treated as a single list of users, thus startIndex does not necessarily indicate the first KAS user.

Example: If there are more than 50,000 users within this cell then only render them in increments of 10,000.

 ...
   User[] users;
   if (cell.getUserCount() > 50000) {
     int index = 0;
     int length = 10000;
     while (index < cell.getUserCount()) {
       users = cell.getUsers(index, length);
       for (int i = 0; i < users.length; i++) {
         ...
       }
       index += length;
       ...
     }
   } else {
     users = cell.getUsers();
     for (int i = 0; i < users.length; i++) {
       ...
     }
   }
 ...
 
Parameters:
startIndex - the base zero index position at which the subset array should start from, relative to the complete list of elements present in AFS.
length - the number of elements that the subset should contain
Returns:
a subset array of users in this cell
Throws:
AFSAdminException - If an error occurs in the native code
See Also:
getUserCount(), getUserNames(int, int), getUsers()

getUserNames

public String[] getUserNames()
                      throws AFSAdminException
Retrieves an array containing all of the names of users associated with this Cell. After this method is called once, it saves the array of Strings and returns that saved array on subsequent calls, until the refresh() method is called and a more current list is obtained.

This method is especially useful when managing iterations of large lists. getUserCount() can be used to determine if iteration management is practical. In comparison to getUsers(), this method has yielded an average performance advantage of approximately 82% at 10K users; this statistic, however, strictly compares the response time of each method and understands that the getUsers() method will return an array of populated User objects, whereas this method will return an array of String names.

Returns:
an String array of the user names of the cell.
Throws:
AFSAdminException - If an error occurs in the native code

getUserNames

public String[] getUserNames(int startIndex,
                             int length)
                      throws AFSAdminException
Returns an array containing a subset of the names of users associated with this Cell. The subset is a point-in-time list of users (String names of AFS users) starting at the complete array's index of startIndex and containing up to length elements. If length is larger than the number of remaining elements, respective to startIndex, then this method will ignore the remaining positions requested by length and return an array that contains the remaining number of elements found in this cell's complete array of users.

This method is especially useful when managing iterations of very large lists. getUserCount() can be used to determine if iteration management is practical.

This method does not save the resulting data and therefore queries AFS for each call.

Note: PTS-only users are collected before KAS users and therefore will always, if PTS-only users exist, be within the lowest range of this cell's complete list of users. PTS and KAS users are joined in a non-duplicating union and are consequently treated as a single list of users, thus startIndex does not necessarily indicate the first KAS user.

Example: If there are more than 50,000 users within this cell then only render them in increments of 10,000.

 ...
   String[] users;
   if (cell.getUserCount() > 50000) {
     int index = 0;
     int length = 10000;
     while (index < cell.getUserCount()) {
       users = cell.getUserNames(index, length);
       for (int i = 0; i < users.length; i++) {
         ...
       }
       index += length;
       ...
     }
   } else {
     users = cell.getUserNames();
     for (int i = 0; i < users.length; i++) {
       ...
     }
   }
 ...
 
Parameters:
startIndex - the base zero index position at which the subset array should start from, relative to the complete list of elements present in AFS.
length - the number of elements that the subset should contain
Returns:
a subset array of user names in this cell
Throws:
AFSAdminException - If an error occurs in the native code
See Also:
getUserCount(), getUserNames(), getUsers(int, int)

getGroup

public Group getGroup(String name)
               throws AFSAdminException
Retrieves the Group object (which is an abstract representation of an actual AFS group) designated by name. If a group by that name does not actually exist in AFS in the cell represented by this object, an AFSAdminException will be thrown.
Parameters:
name - the name of the group to retrieve
Returns:
Group designated by name.
Throws:
AFSAdminException - If an error occurs in the native code
NullPointerException - If name is null.

getGroupCount

public int getGroupCount()
                  throws AFSAdminException
Returns the total number of groups associated with this Cell.

If the total list of groups or group names have already been collected (see getGroups()), then the returning value will be calculated based upon the current list. Otherwise, PTS will be explicitly queried for the information.

Returns:
a User array of the users of the cell.
Throws:
AFSAdminException - If an error occurs in the native code
See Also:
getGroups(), getGroupNames()

getGroups

public Group[] getGroups()
                  throws AFSAdminException
Retrieves an array containing all of the Group objects associated with this Cell, each of which are an abstract representation of an actual group of the AFS cell. After this method is called once, it saves the array of Groups and returns that saved array on subsequent calls, until the refresh() method is called and a more current list is obtained.
Returns:
a Group array of the groups of the cell.
Throws:
AFSAdminException - If an error occurs in the native code

getGroups

public Group[] getGroups(int startIndex,
                         int length)
                  throws AFSAdminException
Returns an array containing a subset of the Group objects associated with this Cell, each of which is an abstract representation of an actual AFS group of the AFS cell. The subset is a point-in-time list of groups (Group objects representing AFS groups) starting at the complete array's index of startIndex and containing up to length elements. If length is larger than the number of remaining elements, respective to startIndex, then this method will ignore the remaining positions requested by length and return an array that contains the remaining number of elements found in this cell's complete array of groups.

This method is especially useful when managing iterations of very large lists. getGroupCount() can be used to determine if iteration management is practical.

This method does not save the resulting data and therefore queries AFS for each call.

Example: If there are more than 50,000 groups within this cell then only render them in increments of 10,000.

 ...
   Group[] groups;
   if (cell.getGroupCount() > 50000) {
     int index = 0;
     int length = 10000;
     while (index < cell.getGroupCount()) {
       groups = cell.getGroups(index, length);
       for (int i = 0; i < groups.length; i++) {
         ...
       }
       index += length;
       ...
     }
   } else {
     groups = cell.getGroups();
     for (int i = 0; i < groups.length; i++) {
       ...
     }
   }
 ...
 
Parameters:
startIndex - the base zero index position at which the subset array should start from, relative to the complete list of elements present in AFS.
length - the number of elements that the subset should contain
Returns:
a subset array of groups in this cell
Throws:
AFSAdminException - If an error occurs in the native code
See Also:
getGroupCount(), getGroupNames(int, int), getGroups()

getGroupNames

public String[] getGroupNames()
                       throws AFSAdminException
Retrieves an array containing all of the names of groups associated with this Cell. After this method is called once, it saves the array of Strings and returns that saved array on subsequent calls, until the refresh() method is called and a more current list is obtained.
Returns:
a String array of the group names of the cell.
Throws:
AFSAdminException - If an error occurs in the native code

getGroupNames

public String[] getGroupNames(int startIndex,
                              int length)
                       throws AFSAdminException
Returns an array containing a subset of the names of groups associated with this Cell. The subset is a point-in-time list of groups (String names of AFS groups) starting at the complete array's index of startIndex and containing up to length elements. If length is larger than the number of remaining elements, respective to startIndex, then this method will ignore the remaining positions requested by length and return an array that contains the remaining number of elements found in this cell's complete array of groups.

This method is especially useful when managing iterations of very large lists. getGroupCount() can be used to determine if iteration management is practical.

This method does not save the resulting data and therefore queries AFS for each call.

Example: If there are more than 50,000 groups within this cell then only render them in increments of 10,000.

 ...
   String[] groups;
   if (cell.getGroupCount() > 50000) {
     int index = 0;
     int length = 10000;
     while (index < cell.getGroupCount()) {
       groups = cell.getGroupNames(index, length);
       for (int i = 0; i < groups.length; i++) {
         ...
       }
       index += length;
       ...
     }
   } else {
     groups = cell.getGroupNames();
     for (int i = 0; i < groups.length; i++) {
       ...
     }
   }
 ...
 
Parameters:
startIndex - the base zero index position at which the subset array should start from, relative to the complete list of elements present in AFS.
length - the number of elements that the subset should contain
Returns:
a subset array of group names in this cell
Throws:
AFSAdminException - If an error occurs in the native code
See Also:
getGroupCount(), getGroups(int, int), getGroupNames()

getServer

public Server getServer(String name)
                 throws AFSAdminException
Retrieves the Server object (which is an abstract representation of an actual AFS server) designated by name. If a group by that name does not actually exist in AFS in the cell represented by this object, an AFSAdminException will be thrown.
Parameters:
name - the name of the server to retrieve
Returns:
Server designated by name.
Throws:
AFSAdminException - If an error occurs in the native code
NullPointerException - If name is null.

getServerCount

public int getServerCount()
                   throws AFSAdminException
Returns the total number of servers associated with this Cell.

If the total list of servers or server names have already been collected (see getServers()), then the returning value will be calculated based upon the current list. Otherwise, AFS will be explicitly queried for the information.

Returns:
a User array of the users of the cell.
Throws:
AFSAdminException - If an error occurs in the native code
See Also:
getServers(), getServerNames()

getServers

public Server[] getServers()
                    throws AFSAdminException
Retrieves an array containing all of the Server objects associated with this Cell, each of which are an abstract representation of an actual server of the AFS cell. After this method is called once, it saves the array of Servers and returns that saved array on subsequent calls, until the refresh() method is called and a more current list is obtained.
Returns:
an Server array of the servers of the cell.
Throws:
AFSAdminException - If an error occurs in the native code

getServerNames

public String[] getServerNames()
                        throws AFSAdminException
Retrieves an array containing all of the names of servers associated with this Cell. After this method is called once, it saves the array of Strings and returns that saved array on subsequent calls, until the refresh() method is called and a more current list is obtained.
Returns:
a String array of the servers of the cell.
Throws:
AFSAdminException - If an error occurs in the native code

getMaxGroupID

public int getMaxGroupID()
                  throws AFSAdminException
Returns the maximum group ID that's been used within the cell. The next auto-assigned group ID will be one less (more negative) than this amount. After this method is called once, it saves the max group id and returns that id on subsequent calls, until the refresh() method is called and a more current id is obtained.
Returns:
an integer representing the maximum group ID
Throws:
AFSAdminException - If an error occurs in the native code

getMaxUserID

public int getMaxUserID()
                 throws AFSAdminException
Returns the maximum user ID that's been used within the cell. The next auto-assigned user ID will be one greater (more positive) than this amount. After this method is called once, it saves the max user id and returns that id on subsequent calls, until the refresh() method is called and a more current id is obtained.
Returns:
an integer representing the maximum user ID
Throws:
AFSAdminException - If an error occurs in the native code

getTokenExpiration

public GregorianCalendar getTokenExpiration()
                                     throws AFSAdminException
Returns the expiration time of the authentication token being used by this Cell object. After this time, this Cell object will no longer be authorized to perform actions requiring administrative authority.
Returns:
expiration time of the token
Throws:
AFSAdminException - If an error occurs in the native code

getCellHandle

public int getCellHandle()
                  throws AFSAdminException
Returns the cell handle of this cell.
Returns:
the cell handle
Throws:
AFSAdminException - If an error occurs in the native code

getName

public String getName()
Returns the name of this cell.
Returns:
the cell name

setMaxGroupID

public void setMaxGroupID(int maxID)
                   throws AFSAdminException
Sets the maximum group ID that's been used within the cell. The next auto-assigned group ID will be one less (more negative) than this amount.
Parameters:
maxID - an integer representing the maximum group ID
Throws:
AFSAdminException - If an error occurs in the native code

setMaxUserID

public void setMaxUserID(int maxID)
                  throws AFSAdminException
Sets the maximum user ID that's been used within the cell. The next auto-assigned user ID will be one greater (more positive) than this amount.
Parameters:
maxID - an integer representing the maximum user ID
Throws:
AFSAdminException - If an error occurs in the native code

equals

public boolean equals(Cell otherCell)
Tests whether two Cell objects are equal, based on their names. Does not test whether the objects are actually the same representational instance of the AFS cell.
Parameters:
otherCell - the Cell to test
Returns:
whether the specifed user is the same as this user

toString

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

Java AFS Admin (jafsadm) API for OpenAFS

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