|
Java AFS Admin API v1.3 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--org.openafs.jafsadm.Cell
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
Server
s, User
s, and Group
s.
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(); ... } ... }
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 |
public Cell(String name, String username, String password) throws AFSAdminException
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.name
- the name of the cell to representusername
- the name of the user to authenticate withpassword
- the password of that userAFSAdminException
- If an error occurs in the native codepublic Cell(String name, String username, String password, boolean preloadAllMembers) throws AFSAdminException
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.
name
- the name of the AFS cell to representusername
- the username of the user to authenticate withpassword
- the password of that userpreloadAllMembers
- true will ensure all object members are
set upon construction; otherwise members
will be set upon access, which is the default
behavior.AFSAdminException
- If an error occurs in the native coderefresh()
Method Detail |
public void refresh() throws AFSAdminException
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.
AFSAdminException
- If an error occurs in the native codepublic void close() throws AFSAdminException
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.AFSAdminException
- If an error occurs in the native codepublic User getUser(String name) throws AFSAdminException
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.name
- the name of the user to retrieveUser
designated by name
.AFSAdminException
- If an error occurs in the native codeNullPointerException
- If name
is
null
.public int getUserCount() throws AFSAdminException
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.
User
array of the users of the cell.AFSAdminException
- If an error occurs in the native codegetUsers()
,
getUserNames()
public User[] getUsers() throws AFSAdminException
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 User
s and returns
that saved array on subsequent calls, until the refresh()
method
is called and a more current list is obtained.User
array of the users of the cell.AFSAdminException
- If an error occurs in the native codepublic User[] getUsers(int startIndex, int length) throws AFSAdminException
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++) { ... } } ...
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 containAFSAdminException
- If an error occurs in the native codegetUserCount()
,
getUserNames(int, int)
,
getUsers()
public String[] getUserNames() throws AFSAdminException
Cell
. After this method
is called once, it saves the array of String
s 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.
String
array of the user names of the cell.AFSAdminException
- If an error occurs in the native codepublic String[] getUserNames(int startIndex, int length) throws AFSAdminException
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++) { ... } } ...
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 containAFSAdminException
- If an error occurs in the native codegetUserCount()
,
getUserNames()
,
getUsers(int, int)
public Group getGroup(String name) throws AFSAdminException
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.name
- the name of the group to retrieveGroup
designated by name
.AFSAdminException
- If an error occurs in the native codeNullPointerException
- If name
is
null
.public int getGroupCount() throws AFSAdminException
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.
User
array of the users of the cell.AFSAdminException
- If an error occurs in the native codegetGroups()
,
getGroupNames()
public Group[] getGroups() throws AFSAdminException
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 Group
s and returns
that saved array on subsequent calls, until the refresh()
method
is called and a more current list is obtained.Group
array of the groups of the cell.AFSAdminException
- If an error occurs in the native codepublic Group[] getGroups(int startIndex, int length) throws AFSAdminException
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++) { ... } } ...
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 containAFSAdminException
- If an error occurs in the native codegetGroupCount()
,
getGroupNames(int, int)
,
getGroups()
public String[] getGroupNames() throws AFSAdminException
Cell
. After this method
is called once, it saves the array of String
s and returns
that saved array on subsequent calls, until the refresh()
method
is called and a more current list is obtained.String
array of the group names of the cell.AFSAdminException
- If an error occurs in the native codepublic String[] getGroupNames(int startIndex, int length) throws AFSAdminException
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++) { ... } } ...
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 containAFSAdminException
- If an error occurs in the native codegetGroupCount()
,
getGroups(int, int)
,
getGroupNames()
public Server getServer(String name) throws AFSAdminException
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.name
- the name of the server to retrieveServer
designated by name
.AFSAdminException
- If an error occurs in the native codeNullPointerException
- If name
is
null
.public int getServerCount() throws AFSAdminException
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.
User
array of the users of the cell.AFSAdminException
- If an error occurs in the native codegetServers()
,
getServerNames()
public Server[] getServers() throws AFSAdminException
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 Server
s and returns
that saved array on subsequent calls, until the refresh()
method
is called and a more current list is obtained.Server
array of the servers of the cell.AFSAdminException
- If an error occurs in the native codepublic String[] getServerNames() throws AFSAdminException
Cell
. After this method
is called once, it saves the array of String
s and returns
that saved array on subsequent calls, until the refresh()
method
is called and a more current list is obtained.String
array of the servers of the cell.AFSAdminException
- If an error occurs in the native codepublic int getMaxGroupID() throws AFSAdminException
refresh()
method is called and a more current id is obtained.AFSAdminException
- If an error occurs in the native codepublic int getMaxUserID() throws AFSAdminException
refresh()
method is called and a more current id is obtained.AFSAdminException
- If an error occurs in the native codepublic GregorianCalendar getTokenExpiration() throws AFSAdminException
Cell
object. After this time, this
Cell
object will no longer be authorized to perform
actions requiring administrative authority.AFSAdminException
- If an error occurs in the native codepublic int getCellHandle() throws AFSAdminException
AFSAdminException
- If an error occurs in the native codepublic String getName()
public void setMaxGroupID(int maxID) throws AFSAdminException
maxID
- an integer representing the maximum group IDAFSAdminException
- If an error occurs in the native codepublic void setMaxUserID(int maxID) throws AFSAdminException
maxID
- an integer representing the maximum user IDAFSAdminException
- If an error occurs in the native codepublic boolean equals(Cell otherCell)
Cell
objects are equal, based on their
names. Does not test whether the objects are actually the same
representational instance of the AFS cell.otherCell
- the Cell
to testpublic String toString()
Cell
toString
in class Object
Cell
|
Java AFS Admin (jafsadm) API for OpenAFS | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |