org.openafs.jafs
Class Token

java.lang.Object
  |
  +--org.openafs.jafs.Token

All Implemented Interfaces:

Comparable, Serializable

public class Token

extends Object

implements Serializable, Comparable

An abstract representation of an AFS authentication token. It conveniently maintains the handle associated with token and the cell to which the token is authenticated.

Constructing a Token object results in an immediate attempt to authenticate the user within the specified cell. If this attempt fails, an AFSException will be thrown. Therefore, if the construction of the object succeeds without an exception, then the Token is considered authenticated. The construction of a Token object acts as an entry point for authentication into the AFS system. Thus, when you construct a Cell object, you must pass in an instance of a Token that has been authenticated within the AFS cell that Cell is intended to represent. You will only be allowed to perform actions that the user, used to authenticate Token, is authorized to perform. You must construct a Token object before constructing a Cell object, which is required by all other objects within this package either directly or indirectly.

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 Token object. It shows how to construct a Cell using a Token. See Cell for a more detailed example of constructing and using a Cell object.

 import org.openafs.jafs.AFSException;
 import org.openafs.jafs.Cell;
 import org.openafs.jafs.Token;
 ...
 public class ...
 {
   ...
   private Cell cell;
   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);
     ...
   }
   ...
 }
 

See Also:

Serialized Form

Field Summary

static int	ANYUSER_PAG_ID
protected String	cellName
protected int	errno
protected int	pagID
protected int	tokenHandle
protected String	username

Constructor Summary

	Token(String username, String password, String cellName) Constructs a new Token object instance given the name of the AFS cell it represents and the username and password of the user to be Tokend for administrative access.
protected	Token(String username, String password, String cellName, boolean automaticallyLogin) Constructs a new Token object instance given the name of the AFS cell it represents and the username and password of the user to be Tokend for administrative access.

Method Summary

void	close() Closes the given currently open token.
protected void	close(int tokenHandle) Closes the given currently open token.
int	compareTo(Object obj) Comparable interface method.
int	compareTo(Token token) Compares two ACL objects respective to their paths and does not factor any other attribute.
boolean	equals(Token token) Tests whether two Cell objects are equal, based on their names.
String	getCellName() Returns the name of the AFS cell that this Token was authenticated against.
long	getExpiration() Gets the expiration time for a given token.
protected long	getExpiration(int tokenHandle) Gets the expiration time for a given token.
protected int	getHandle() Returns a token handle that can be used to prove this authentication later.
protected int	getToken(String cellName, String username, String password) Returns a token handle that can be used to prove this authentication later.
String	getUsername() Returns the username of user to whom this token belongs.
protected static void	initializeAdminClient() Initialize the administrative library.
protected static void	initializeUserSpace() Initialize the user space AFS client (libjafs).
void	klog() Authenticates a user in kas, and binds that authentication to the current process.
protected int	klog(String username, String password, String cellName, int id) Authenticates a user in KAS, and binds that authentication to the current thread or native process.
void	login() Authenticates a user in KAS, and binds that authentication to the current process.
protected static void	reclaimAuthMemory() Reclaims all memory being saved by the authentication portion of the native library.
protected void	relog(int id) Authenticates a user in KAS by a previously acquired PAG ID, and binds that authentication to the current thread or native process.
protected static void	shutdown() Inform the native library that the application is shutting down and will be unloading.
String	toString() Returns the name of this Cell
void	unlog() Manually discards all AFS credentials associated with the bound user.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

ANYUSER_PAG_ID

public static int ANYUSER_PAG_ID

tokenHandle

protected int tokenHandle

pagID

protected int pagID

errno

protected int errno

cellName

protected String cellName

username

protected String username

Constructor Detail

Token

protected Token(String username,
                String password,
                String cellName,
                boolean automaticallyLogin)
         throws AFSException

Constructs a new Token object instance given the name of the AFS cell it represents and the username and password of the user to be Tokend for administrative access.

Parameters:

username - the name of the user to Token with

password - the password of that user

cellName - the name of the cell to Token into

Throws:

AFSException - If an error occurs in the native code

Token

public Token(String username,
             String password,
             String cellName)
      throws AFSException

Constructs a new Token object instance given the name of the AFS cell it represents and the username and password of the user to be Tokend for administrative access.

Parameters:

username - the name of the user to Token with

password - the password of that user

cellName - the name of the cell to Token into

Throws:

AFSException - If an error occurs in the native code

Method Detail

getCellName

public String getCellName()

Returns the name of the AFS cell that this Token was authenticated against.

Returns:

the name of the AFS cell associated with this Token.

Throws:

AFSException - If an error occurs in the native code

getUsername

public String getUsername()

Returns the username of user to whom this token belongs.

Returns:

the username of the user represented by this Token

Throws:

AFSException - If an error occurs in the native code

getHandle

protected int getHandle()

Returns a token handle that can be used to prove this authentication later.

Returns:

a token representing the authentication

Throws:

AFSException - If an error occurs in the native code

close

public void close()
           throws AFSException

Closes the given currently open token.

Throws:

AFSException - If an error occurs in the native code

getExpiration

public long getExpiration()
                   throws AFSException

Gets the expiration time for a given token.

Returns:

a long representing the UTC time for the token expiration

Throws:

AFSException - If an error occurs in the native code

klog

public void klog()
          throws AFSException

Authenticates a user in kas, and binds that authentication to the current process.

Throws:

AFSException - If an error occurs in the native code

login

public void login()
           throws AFSException

Authenticates a user in KAS, and binds that authentication to the current process.

Throws:

AFSException - If an error occurs in the native code

initializeUserSpace

protected static void initializeUserSpace()
                                   throws AFSException

Initialize the user space AFS client (libjafs).

The user space client must be initialized prior to any user space related methods, including: klog, unlog, relog, and shutdown.

Throws:

AFSException - If an error occurs in the native code

compareTo

public int compareTo(Token token)

Compares two ACL objects respective to their paths and does not factor any other attribute. Alphabetic case is significant in comparing names.

Returns:

Zero if the argument is equal to this ACL's path, a value less than zero if this ACL's path is lexicographically less than the argument, or a value greater than zero if this ACL's path is lexicographically greater than the argument

compareTo

public int compareTo(Object obj)

Comparable interface method.

Specified by:

compareTo in interface Comparable

See Also:

compareTo(Token)

equals

public boolean equals(Token token)

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.

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

initializeAdminClient

protected static void initializeAdminClient()
                                     throws AFSException

Initialize the administrative library.

Throws:

AFSException - If an error occurs in the native code

getToken

protected int getToken(String cellName,
                       String username,
                       String password)
                throws AFSException

Returns a token handle that can be used to prove this authentication later.

Parameters:

cellName - the name of the cell in which to Token this user

password - the password of the user

Returns:

a token representing the authentication

Throws:

AFSException - If an error occurs in the native code

close

protected void close(int tokenHandle)
              throws AFSException

Closes the given currently open token.

Parameters:

tokenHandle - the token to close

Throws:

AFSException - If an error occurs in the native code

getExpiration

protected long getExpiration(int tokenHandle)
                      throws AFSException

Gets the expiration time for a given token.

Parameters:

tokenHandle - a token handle previously returned by a call to getToken(java.lang.String, java.lang.String, java.lang.String)

Returns:

a long representing the UTC time for the token expiration

Throws:

AFSException - If an error occurs in the native code

See Also:

getToken(java.lang.String, java.lang.String, java.lang.String)

klog

protected int klog(String username,
                   String password,
                   String cellName,
                   int id)
            throws AFSException

Authenticates a user in KAS, and binds that authentication to the current thread or native process.

Parameters:

username - the login to authenticate (expected as username@cellname)

password - the password of the login

cellName - the name of the cell to authenticate into

id - the existing pag (or 0)

Returns:

the assigned pag

Throws:

AFSException - If an error occurs in the native code

relog

protected void relog(int id)
              throws AFSException

Authenticates a user in KAS by a previously acquired PAG ID, and binds that authentication to the current thread or native process.

This method does not require the user's username and password to fully authenticate their request. Rather it utilizes the user's PAG ID to recapture the user's existing credentials.

This method is called by the public klog method, which internally manages the PAG ID. Additionally, an application needs only call klog, this reduces the amount of complexity and ensures that relog is never called before a klog.

Throws:

AFSException - If an error occurs in the native code

unlog

public void unlog()
           throws AFSException

Manually discards all AFS credentials associated with the bound user.

Throws:

AFSException - If an error occurs in the native code

shutdown

protected static void shutdown()

Inform the native library that the application is shutting down and will be unloading.

The library will make a call informing the file server that it will no longer be available for callbacks.

reclaimAuthMemory

protected static void reclaimAuthMemory()

Reclaims all memory being saved by the authentication portion of the native library. This method should be called when no more authentications are expected.