JAFS API v2

org.openafs.jafs
Class Cell

java.lang.Object
  |
  +--org.openafs.jafs.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 an authenticated Token of a user in the AFS cell that the Cell represents. You will be authenticated as the user represented by token 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 AFSException will be thrown. This class is the Java equivalent of errors thrown by AFS; see AFSException 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.jafs.AFSException;
 import org.openafs.jafs.Cell;
 import org.openafs.jafs.Partition;
 import org.openafs.jafs.Server;
 import org.openafs.jafs.Token;
 import org.openafs.jafs.User;
 ...
 public class ...
 {
   ...
   private Cell cell;
   private Server server;
   private Token token;
   ...
   public static void main(String[] args) throws Exception
   {
     String username   = arg[0];
     String password   = arg[1];
     String cellName   = arg[2];
     String serverName = arg[3];
 
     token = new Token(username, password, cellName);
     cell   = new Cell(token);
     server = cell.getServer(serverName);

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

See Also:
Serialized Form

Field Summary
protected  boolean cachedInfo
           
protected  int cellHandle
           
protected  ArrayList groupNames
           
protected  ArrayList groups
           
protected  int maxGroupID
           
protected  int maxUserID
           
protected  String name
           
protected  ArrayList serverNames
           
protected  ArrayList servers
           
protected  Token token
           
protected  GregorianCalendar tokenExpiration
           
protected  ArrayList userNames
           
protected  ArrayList users
           
 
Constructor Summary
Cell(Token token)
          Constructs a new Cell object instance given the Token that should represents an authenticated user with administrative access.
Cell(Token token, boolean preloadAllMembers)
          Constructs a new Cell object instance given the Token that should represents an authenticated user with administrative access.
 
Method Summary
 void close()
          Unauthenticates this Token object associated with this Cell and deletes all of its stored information.
protected static void closeCell(int cellHandle)
          Closes the given currently open cell handle.
protected static void createMountPoint(int cellHandle, String directory, String volumeName, boolean readWrite, boolean forceCheck)
          Creates a mount point for a volume within the file system.
 boolean equals(Cell otherCell)
          Tests whether two Cell objects are equal, based on their names.
 int getCellHandle()
          Returns the cell handle of this cell.
protected static int getCellHandle(String cellName, int tokenHandle)
          Opens a cell for administrative use, based on the token provided.
protected static String getCellName(int cellHandle)
          Returns the name of the 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.
protected static int getGroupCount(int cellHandle)
          Returns the total number of groups belonging to the cell denoted by cellHandle.
 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.
protected static int getGroupsBegin(int cellHandle)
          Begin the process of getting the groups that belong to the cell.
protected static int getGroupsBeginAt(int cellHandle, int startIndex)
          Begin the process of getting the groups that belong to the cell, starting with element index startIndex.
protected static void getGroupsDone(int iterationId)
          Signals that the iteration is complete and will not be accessed anymore.
protected static int getGroupsNext(int cellHandle, int iterationId, Group theGroup)
          Fills the next group object of the cell.
protected static String getGroupsNextString(int iterationId)
          Returns the next group of the cell.
protected  String getInfo()
          Returns a String representation of this Cell.
protected  String getInfoGroups()
          Returns a String containing the String representations of all the groups of this Cell.
protected  String getInfoServers()
          Returns a String containing the String representations of all the servers of this Cell.
protected  String getInfoUsers()
          Returns a String containing the String representations of all the users of this Cell.
protected static int getKasUserCount(int cellHandle)
          Returns the total number of KAS users belonging to the cell denoted by cellHandle.
protected static int getKasUsersBegin(int cellHandle)
          Begin the process of getting the kas users that belong to the cell.
protected static int getKasUsersBeginAt(int cellHandle, int startIndex)
          Begin the process of getting the KAS users, starting at startIndex, that belong to the cell.
protected static void getKasUsersDone(int iterationId)
          Signals that the iteration is complete and will not be accessed anymore.
protected static int getKasUsersNext(int cellHandle, int iterationId, User theUser)
          Fills the next kas user object of the cell.
protected static String getKasUsersNextString(int iterationId)
          Returns the next kas user of the cell.
 int getMaxGroupID()
          Returns the maximum group ID that's been used within the cell.
protected static int getMaxGroupID(int cellHandle)
          Gets the maximum group pts ID that's been used within a cell.
 int getMaxUserID()
          Returns the maximum user ID that's been used within the cell.
protected static int getMaxUserID(int cellHandle)
          Gets the maximum user pts ID that's been used within a cell.
 String getName()
          Returns the name of this cell.
protected static int getPtsOnlyUserCount(int cellHandle)
          Returns the total number of PTS users, belonging to the cell denoted by cellHandle, that are not in KAS.
protected static int getPtsOnlyUsersNext(int cellHandle, int iterationId, User theUser)
          Fills the next pts user (who does not have a kas entry) object of the cell.
protected static String getPtsOnlyUsersNextString(int iterationId, int cellHandle)
          Returns the next pts user (who is not a kas user) of the cell.
protected static int getPtsUserCount(int cellHandle)
          Returns the total number of PTS users belonging to the cell denoted by cellHandle.
protected static int getPtsUsersBegin(int cellHandle)
          Begin the process of getting the pts users that belong to the cell.
protected static void getPtsUsersDone(int iterationId)
          Signals that the iteration is complete and will not be accessed anymore.
protected static int getPtsUsersNext(int cellHandle, int iterationId, User theUser)
          Fills the next pts user object of the cell.
protected static String getPtsUsersNextString(int iterationId)
          Returns the next pts user of the 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.
protected static int getServerCount(int cellHandle)
          Returns the total number of servers belonging to the cell denoted by cellHandle.
 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.
protected static int getServersBegin(int cellHandle)
          Begin the process of getting the servers in the cell.
protected static void getServersDone(int iterationId)
          Signals that the iteration is complete and will not be accessed anymore.
protected static int getServersNext(int cellHandle, int iterationId, Server theServer)
          Fills the next server object of the cell.
protected static String getServersNextString(int iterationId)
          Returns the next server of the 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.
protected static void reclaimCellMemory()
          Reclaims all memory being saved by the cell portion of the native library.
 void refresh()
          Refreshes the properties of this Cell object instance with values from the AFS cell it represents.
protected  void refresh(boolean all)
          Refreshes the properties of this Cell object instance with values from the AFS cell it represents.
protected  void refreshGroupNames()
          Obtains the most current list of group names of this cell.
protected  void refreshGroups()
          Obtains the most current list of Group objects of this cell.
protected  void refreshInfo()
          Sets all the information fields of this Cell object, such as max group and user ids, to their most current values.
protected  void refreshServerNames()
          Obtains the most current list of server names of this cell.
protected  void refreshServers()
          Obtains the most current list of Server objects of this cell.
protected  void refreshUserNames()
          Obtains the most current list of user names of this cell.
protected  void refreshUsers()
          Obtains the most current list of User objects of this cell.
static void setACL(String directory, String username, boolean read, boolean write, boolean lookup, boolean delete, boolean insert, boolean lock, boolean admin)
           
 void setMaxGroupID(int maxID)
          Sets the maximum group ID that's been used within the cell.
protected static void setMaxGroupID(int cellHandle, int maxID)
          Sets the maximum group pts ID that's been used within a cell.
 void setMaxUserID(int maxID)
          Sets the maximum user ID that's been used within the cell.
protected static void setMaxUserID(int cellHandle, int maxID)
          Sets the maximum user pts ID that's been used within a cell.
 String toString()
          Returns the name of this Cell
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

users

protected ArrayList users

userNames

protected ArrayList userNames

groups

protected ArrayList groups

groupNames

protected ArrayList groupNames

servers

protected ArrayList servers

serverNames

protected ArrayList serverNames

name

protected String name

cellHandle

protected int cellHandle

token

protected Token token

maxGroupID

protected int maxGroupID

maxUserID

protected int maxUserID

tokenExpiration

protected GregorianCalendar tokenExpiration

cachedInfo

protected boolean cachedInfo
Constructor Detail

Cell

public Cell(Token token)
     throws AFSException
Constructs a new Cell object instance given the Token that should represents an authenticated user with administrative access. In order to get full access to the cell, it is best that the Token provided have administrative privileges.

Parameters:
token - the user's authenticated token
Throws:
AFSException - If an error occurs in the native code

Cell

public Cell(Token token,
            boolean preloadAllMembers)
     throws AFSException
Constructs a new Cell object instance given the Token that should represents an authenticated user with administrative access. In order to get full access to the cell, it is best that the Token provided have 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:
token - the user's authenticated token
preloadAllMembers - true will ensure all object members are set upon construction; otherwise members will be set upon access, which is the default behavior.
Throws:
AFSException - If an error occurs in the native code
See Also:
refresh()
Method Detail

refresh

public void refresh()
             throws AFSException
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:
AFSException - If an error occurs in the native code

refresh

protected void refresh(boolean all)
                throws AFSException
Refreshes the properties of this Cell object instance with values from the AFS cell it represents. If all is true then all of the properties of this Cell object instance will be set, or renewed, according to the values of the AFS cell it represents, disregarding any previously set properties.

Thus, if all is false then properties that are currently set will be refreshed and properties that are not set will remain uninitialized. See refresh() for more information.

Parameters:
all - if true set or renew all object properties; otherwise renew all set properties
Throws:
AFSException - If an error occurs in the native code
See Also:
refresh()

refreshInfo

protected void refreshInfo()
                    throws AFSException
Sets all the information fields of this Cell object, such as max group and user ids, to their most current values.

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

refreshUsers

protected void refreshUsers()
                     throws AFSException
Obtains the most current list of User objects of this cell. Finds all users that currently have a kas and/or pts entry for this cell.

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

refreshUserNames

protected void refreshUserNames()
                         throws AFSException
Obtains the most current list of user names of this cell. Finds all users that currently have a kas and/or pts entry for this cell.

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

refreshGroups

protected void refreshGroups()
                      throws AFSException
Obtains the most current list of Group objects of this cell.

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

refreshGroupNames

protected void refreshGroupNames()
                          throws AFSException
Obtains the most current list of group names of this cell.

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

refreshServers

protected void refreshServers()
                       throws AFSException
Obtains the most current list of Server objects of this cell.

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

refreshServerNames

protected void refreshServerNames()
                           throws AFSException
Obtains the most current list of server names of this cell.

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

close

public void close()
           throws AFSException
Unauthenticates this Token object associated with this Cell 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:
AFSException - If an error occurs in the native code

getUser

public User getUser(String name)
             throws AFSException
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 AFSException will be thrown.

Parameters:
name - the name of the user to retrieve
Returns:
User designated by name.
Throws:
AFSException - If an error occurs in the native code
NullPointerException - If name is null.

getUserCount

public int getUserCount()
                 throws AFSException
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:
AFSException - If an error occurs in the native code
See Also:
getUsers(), getUserNames()

getUsers

public User[] getUsers()
                throws AFSException
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:
AFSException - If an error occurs in the native code

getUsers

public User[] getUsers(int startIndex,
                       int length)
                throws AFSException
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:
AFSException - If an error occurs in the native code
See Also:
getUserCount(), getUserNames(int, int), getUsers()

getUserNames

public String[] getUserNames()
                      throws AFSException
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:
AFSException - If an error occurs in the native code

getUserNames

public String[] getUserNames(int startIndex,
                             int length)
                      throws AFSException
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:
AFSException - If an error occurs in the native code
See Also:
getUserCount(), getUserNames(), getUsers(int, int)

getGroup

public Group getGroup(String name)
               throws AFSException
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 AFSException will be thrown.

Parameters:
name - the name of the group to retrieve
Returns:
Group designated by name.
Throws:
AFSException - If an error occurs in the native code
NullPointerException - If name is null.

getGroupCount

public int getGroupCount()
                  throws AFSException
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:
AFSException - If an error occurs in the native code
See Also:
getGroups(), getGroupNames()

getGroups

public Group[] getGroups()
                  throws AFSException
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:
AFSException - If an error occurs in the native code

getGroups

public Group[] getGroups(int startIndex,
                         int length)
                  throws AFSException
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:
AFSException - If an error occurs in the native code
See Also:
getGroupCount(), getGroupNames(int, int), getGroups()

getGroupNames

public String[] getGroupNames()
                       throws AFSException
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:
AFSException - If an error occurs in the native code

getGroupNames

public String[] getGroupNames(int startIndex,
                              int length)
                       throws AFSException
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:
AFSException - If an error occurs in the native code
See Also:
getGroupCount(), getGroups(int, int), getGroupNames()

getServer

public Server getServer(String name)
                 throws AFSException
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 AFSException will be thrown.

Parameters:
name - the name of the server to retrieve
Returns:
Server designated by name.
Throws:
AFSException - If an error occurs in the native code
NullPointerException - If name is null.

getServerCount

public int getServerCount()
                   throws AFSException
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:
AFSException - If an error occurs in the native code
See Also:
getServers(), getServerNames()

getServers

public Server[] getServers()
                    throws AFSException
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:
AFSException - If an error occurs in the native code

getServerNames

public String[] getServerNames()
                        throws AFSException
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:
AFSException - If an error occurs in the native code

getMaxGroupID

public int getMaxGroupID()
                  throws AFSException
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:
AFSException - If an error occurs in the native code

getMaxUserID

public int getMaxUserID()
                 throws AFSException
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:
AFSException - If an error occurs in the native code

getTokenExpiration

public GregorianCalendar getTokenExpiration()
                                     throws AFSException
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:
AFSException - If an error occurs in the native code

getCellHandle

public int getCellHandle()
                  throws AFSException
Returns the cell handle of this cell.

Returns:
the cell handle
Throws:
AFSException - 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 AFSException
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:
AFSException - If an error occurs in the native code

setMaxUserID

public void setMaxUserID(int maxID)
                  throws AFSException
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:
AFSException - If an error occurs in the native code

getInfo

protected String getInfo()
Returns a String representation of this Cell. Contains the cell name followed by the names of its users and groups.

Returns:
a String representation of this Cell

getInfoUsers

protected String getInfoUsers()
                       throws AFSException
Returns a String containing the String representations of all the users of this Cell.

Returns:
a String representation of the users
AFSException
See Also:
User.getInfo()

getInfoGroups

protected String getInfoGroups()
                        throws AFSException
Returns a String containing the String representations of all the groups of this Cell.

Returns:
a String representation of the groups
AFSException
See Also:
Group.getInfo()

getInfoServers

protected String getInfoServers()
                         throws AFSException
Returns a String containing the String representations of all the servers of this Cell.

Returns:
a String representation of the servers
AFSException
See Also:
Server.getInfo()

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

getKasUserCount

protected static int getKasUserCount(int cellHandle)
                              throws AFSException
Returns the total number of KAS users belonging to the cell denoted by cellHandle.

Parameters:
cellHandle - the handle of the cell to which the users belong
Returns:
total count of KAS users
Throws:
AFSException - If an error occurs in the native code
See Also:
getCellHandle()

getKasUsersBegin

protected static int getKasUsersBegin(int cellHandle)
                               throws AFSException
Begin the process of getting the kas users that belong to the cell. Returns an iteration ID to be used by subsequent calls to getKasUsersNextString (or getKasUsersNext) and getKasUsersDone.

Parameters:
cellHandle - the handle of the cell to which the users belong
Returns:
an iteration ID
Throws:
AFSException - If an error occurs in the native code
See Also:
getCellHandle()

getKasUsersBeginAt

protected static int getKasUsersBeginAt(int cellHandle,
                                        int startIndex)
                                 throws AFSException
Begin the process of getting the KAS users, starting at startIndex, that belong to the cell. Returns an iteration ID to be used by subsequent calls to getKasUsersNextString (or getKasUsersNext) and getKasUsersDone.

Parameters:
cellHandle - the handle of the cell to which the users belong
startIndex - the starting base-zero index
Returns:
an iteration ID
Throws:
AFSException - If an error occurs in the native code
See Also:
getCellHandle()

getKasUsersNextString

protected static String getKasUsersNextString(int iterationId)
                                       throws AFSException
Returns the next kas user of the cell. Returns null if there are no more users. Appends instance names to principal names as follows: principal.instance

Parameters:
iterationId - the iteration ID of this iteration
Returns:
the name of the next user of the cell
Throws:
AFSException - If an error occurs in the native code
See Also:
getKasUsersBegin(int)

getKasUsersNext

protected static int getKasUsersNext(int cellHandle,
                                     int iterationId,
                                     User theUser)
                              throws AFSException
Fills the next kas user object of the cell. Returns 0 if there are no more users, != 0 otherwise.

Parameters:
cellHandle - the handle of the cell to which the users belong
iterationId - the iteration ID of this iteration
theUser - a User object to be populated with the values of the next kas user
Returns:
0 if there are no more users, != 0 otherwise
Throws:
AFSException - If an error occurs in the native code
See Also:
getCellHandle(), getKasUsersBegin(int)

getKasUsersDone

protected static void getKasUsersDone(int iterationId)
                               throws AFSException
Signals that the iteration is complete and will not be accessed anymore.

Parameters:
iterationId - the iteration ID of this iteration
Throws:
AFSException - If an error occurs in the native code
See Also:
getKasUsersBegin(int)

getPtsUserCount

protected static int getPtsUserCount(int cellHandle)
                              throws AFSException
Returns the total number of PTS users belonging to the cell denoted by cellHandle.

Parameters:
cellHandle - the handle of the cell to which the users belong
Returns:
total number of PTS users
Throws:
AFSException - If an error occurs in the native code
See Also:
getCellHandle()

getPtsOnlyUserCount

protected static int getPtsOnlyUserCount(int cellHandle)
                                  throws AFSException
Returns the total number of PTS users, belonging to the cell denoted by cellHandle, that are not in KAS.

Parameters:
cellHandle - the handle of the cell to which the users belong
Returns:
total number of users that are in PTS and not KAS
Throws:
AFSException - If an error occurs in the native code
See Also:
getCellHandle()

getPtsUsersBegin

protected static int getPtsUsersBegin(int cellHandle)
                               throws AFSException
Begin the process of getting the pts users that belong to the cell. Returns an iteration ID to be used by subsequent calls to getPtsUsersNextString (or getPtsUsersNext) and getPtsUsersDone.

Parameters:
cellHandle - the handle of the cell to which the users belong
Returns:
an iteration ID
Throws:
AFSException - If an error occurs in the native code
See Also:
getCellHandle()

getPtsUsersNextString

protected static String getPtsUsersNextString(int iterationId)
                                       throws AFSException
Returns the next pts user of the cell. Returns null if there are no more users.

Parameters:
iterationId - the iteration ID of this iteration
Returns:
the name of the next user of the cell
Throws:
AFSException - If an error occurs in the native code
See Also:
getPtsUsersBegin(int)

getPtsOnlyUsersNextString

protected static String getPtsOnlyUsersNextString(int iterationId,
                                                  int cellHandle)
                                           throws AFSException
Returns the next pts user (who is not a kas user) of the cell. Returns null if there are no more users.

Parameters:
iterationId - the iteration ID of this iteration
cellHandle - the cell handle to which these users will belong
Returns:
the name of the next pts user (not kas user) of the cell
Throws:
AFSException - If an error occurs in the native code
See Also:
getPtsUsersBegin(int)

getPtsUsersNext

protected static int getPtsUsersNext(int cellHandle,
                                     int iterationId,
                                     User theUser)
                              throws AFSException
Fills the next pts user object of the cell. Returns 0 if there are no more users, != 0 otherwise.

Parameters:
cellHandle - the handle of the cell to which the users belong
iterationId - the iteration ID of this iteration
theUser - a User object to be populated with the values of the next pts user
Returns:
0 if there are no more users, != 0 otherwise
Throws:
AFSException - If an error occurs in the native code
See Also:
getCellHandle(), getPtsUsersBegin(int)

getPtsOnlyUsersNext

protected static int getPtsOnlyUsersNext(int cellHandle,
                                         int iterationId,
                                         User theUser)
                                  throws AFSException
Fills the next pts user (who does not have a kas entry) object of the cell. Returns 0 if there are no more users, != 0 otherwise.

Parameters:
cellHandle - the handle of the cell to which the users belong
iterationId - the iteration ID of this iteration
theUser - a User object to be populated with the values of the next pts (with no kas) user
Returns:
0 if there are no more users, != 0 otherwise
Throws:
AFSException - If an error occurs in the native code
See Also:
getCellHandle(), getPtsUsersBegin(int)

getPtsUsersDone

protected static void getPtsUsersDone(int iterationId)
                               throws AFSException
Signals that the iteration is complete and will not be accessed anymore.

Parameters:
iterationId - the iteration ID of this iteration
Throws:
AFSException - If an error occurs in the native code
See Also:
getPtsUsersBegin(int)

getGroupCount

protected static int getGroupCount(int cellHandle)
                            throws AFSException
Returns the total number of groups belonging to the cell denoted by cellHandle.

Parameters:
cellHandle - the handle of the cell to which the groups belong
Returns:
total number of groups
Throws:
AFSException - If an error occurs in the native code
See Also:
getCellHandle()

getGroupsBegin

protected static int getGroupsBegin(int cellHandle)
                             throws AFSException
Begin the process of getting the groups that belong to the cell. Returns an iteration ID to be used by subsequent calls to getGroupsNextString (or getGroupsNext) and getGroupsDone.

Parameters:
cellHandle - the handle of the cell to which the groups belong
Returns:
an iteration ID
Throws:
AFSException - If an error occurs in the native code
See Also:
getCellHandle()

getGroupsBeginAt

protected static int getGroupsBeginAt(int cellHandle,
                                      int startIndex)
                               throws AFSException
Begin the process of getting the groups that belong to the cell, starting with element index startIndex. Returns an iteration ID to be used by subsequent calls to getGroupsNextString (or getGroupsNext) and getGroupsDone.

Parameters:
cellHandle - the handle of the cell to which the groups belong
startIndex - the starting base-zero index
Returns:
an iteration ID
Throws:
AFSException - If an error occurs in the native code
See Also:
getCellHandle()

getGroupsNextString

protected static String getGroupsNextString(int iterationId)
                                     throws AFSException
Returns the next group of the cell. Returns null if there are no more groups.

Parameters:
iterationId - the iteration ID of this iteration
Returns:
the name of the next user of the cell
Throws:
AFSException - If an error occurs in the native code
See Also:
getGroupsBegin(int)

getGroupsNext

protected static int getGroupsNext(int cellHandle,
                                   int iterationId,
                                   Group theGroup)
                            throws AFSException
Fills the next group object of the cell. Returns 0 if there are no more groups, != 0 otherwise.

Parameters:
cellHandle - the handle of the cell to which the users belong
iterationId - the iteration ID of this iteration
theGroup - a Group object to be populated with the values of the next group
Returns:
0 if there are no more users, != 0 otherwise
Throws:
AFSException - If an error occurs in the native code
See Also:
getCellHandle(), getGroupsBegin(int)

getGroupsDone

protected static void getGroupsDone(int iterationId)
                             throws AFSException
Signals that the iteration is complete and will not be accessed anymore.

Parameters:
iterationId - the iteration ID of this iteration
Throws:
AFSException - If an error occurs in the native code
See Also:
getGroupsBegin(int)

getServerCount

protected static int getServerCount(int cellHandle)
                             throws AFSException
Returns the total number of servers belonging to the cell denoted by cellHandle.

Parameters:
cellHandle - the handle of the cell to which the servers belong
Returns:
total number of servers
Throws:
AFSException - If an error occurs in the native code
See Also:
getCellHandle()

getServersBegin

protected static int getServersBegin(int cellHandle)
                              throws AFSException
Begin the process of getting the servers in the cell. Returns an iteration ID to be used by subsequent calls to getServersNextString and getServersDone.

Parameters:
cellHandle - the handle of the cell to which the servers belong
Returns:
an iteration ID
Throws:
AFSException - If an error occurs in the native code
See Also:
getCellHandle()

getServersNextString

protected static String getServersNextString(int iterationId)
                                      throws AFSException
Returns the next server of the cell. Returns null if there are no more servers.

Parameters:
iterationId - the iteration ID of this iteration
Returns:
the name of the next server of the cell
Throws:
AFSException - If an error occurs in the native code
See Also:
getServersBegin(int)

getServersNext

protected static int getServersNext(int cellHandle,
                                    int iterationId,
                                    Server theServer)
                             throws AFSException
Fills the next server object of the cell. Returns 0 if there are no more servers, != 0 otherwise.

Parameters:
cellHandle - the handle of the cell to which the users belong
iterationId - the iteration ID of this iteration
theServer - a Server object to be populated with the values of the next server
Returns:
0 if there are no more servers, != 0 otherwise
Throws:
AFSException - If an error occurs in the native code
See Also:
getCellHandle(), getServersBegin(int)

getServersDone

protected static void getServersDone(int iterationId)
                              throws AFSException
Signals that the iteration is complete and will not be accessed anymore.

Parameters:
iterationId - the iteration ID of this iteration
Throws:
AFSException - If an error occurs in the native code
See Also:
getServersBegin(int)

getCellName

protected static String getCellName(int cellHandle)
                             throws AFSException
Returns the name of the cell.

Parameters:
cellHandle - the handle of the cell to which the user belongs
Returns:
the name of the cell
Throws:
AFSException - If an error occurs in the native code
See Also:
getCellHandle()

createMountPoint

protected static void createMountPoint(int cellHandle,
                                       String directory,
                                       String volumeName,
                                       boolean readWrite,
                                       boolean forceCheck)
                                throws AFSException
Creates a mount point for a volume within the file system.

Parameters:
cellHandle - the handle of the cell to which the user belongs
directory - the full path of the place in the AFS file system at which to mount the volume
volumeName - the name of the volume to mount
readWrite - whether or not this is to be a readwrite mount point
forceCheck - whether or not to check if this volume name exists
Throws:
AFSException - If an error occurs in the native code
See Also:
getCellHandle()

setACL

public static void setACL(String directory,
                          String username,
                          boolean read,
                          boolean write,
                          boolean lookup,
                          boolean delete,
                          boolean insert,
                          boolean lock,
                          boolean admin)
                   throws AFSException
AFSException

getMaxGroupID

protected static int getMaxGroupID(int cellHandle)
                            throws AFSException
Gets the maximum group pts ID that's been used within a cell. The next auto-assigned group ID will be one less (more negative) than this value.

Parameters:
cellHandle - the handle of the cell to which the group belongs
Returns:
an integer reresenting the max group id in a cell
Throws:
AFSException - If an error occurs in the native code
See Also:
getCellHandle()

setMaxGroupID

protected static void setMaxGroupID(int cellHandle,
                                    int maxID)
                             throws AFSException
Sets the maximum group pts ID that's been used within a cell. The next auto-assigned group ID will be one less (more negative) than this value.

Parameters:
cellHandle - the handle of the cell to which the group belongs
maxID - an integer reresenting the new max group id in a cell
Throws:
AFSException - If an error occurs in the native code
See Also:
getCellHandle()

getMaxUserID

protected static int getMaxUserID(int cellHandle)
                           throws AFSException
Gets the maximum user pts ID that's been used within a cell. The next auto-assigned user ID will be one greater (more positive) than this value.

Parameters:
cellHandle - the handle of the cell to which the user belongs
Returns:
an integer reresenting the max user id in a cell
Throws:
AFSException - If an error occurs in the native code
See Also:
getCellHandle()

setMaxUserID

protected static void setMaxUserID(int cellHandle,
                                   int maxID)
                            throws AFSException
Sets the maximum user pts ID that's been used within a cell. The next auto-assigned user ID will be one greater (more positive) than this value.

Parameters:
cellHandle - the handle of the cell to which the user belongs
maxID - an integer reresenting the new max user id in a cell
Throws:
AFSException - If an error occurs in the native code
See Also:
getCellHandle()

reclaimCellMemory

protected static void reclaimCellMemory()
Reclaims all memory being saved by the cell portion of the native library. This method should be called when no more Cell objects are expected to be used.


getCellHandle

protected static int getCellHandle(String cellName,
                                   int tokenHandle)
                            throws AFSException
Opens a cell for administrative use, based on the token provided. Returns a cell handle to be used by other methods as a means of authentication.

Parameters:
cellName - the name of the cell for which to get the handle
tokenHandle - a token handle previously returned by a call to Token.getHandle()
Returns:
a handle to the open cell
Throws:
AFSException - If an error occurs in the native code
See Also:
Token.getHandle()

closeCell

protected static void closeCell(int cellHandle)
                         throws AFSException
Closes the given currently open cell handle.

Parameters:
cellHandle - the cell handle to close
Throws:
AFSException - If an error occurs in the native code

JAFS API v2