JAFS API v2

org.openafs.jafs
Class Key

java.lang.Object
  |
  +--org.openafs.jafs.Key
All Implemented Interfaces:
Comparable, Serializable

public class Key
extends Object
implements Serializable, Comparable

An abstract representation of an AFS key. It holds information about the key, such as what its version is.

Constructing an instance of a Key does not mean an actual AFS key is created on a server -- usually a Key object is a representation of an already existing AFS key. If, however, the Key is constructed with the version number of a key that does not exist on the server represented by the provided Server, a new key with that version number can be created on that server by calling the create(String) methods If such a key does already exist when this method is called, an exception will be thrown.

The following is a simple example of how to construct and use a Key object. It obtains the list of Keys from a specified server, and prints the string representation of each key.

 import org.openafs.jafs.Cell;
 import org.openafs.jafs.AFSException;
 import org.openafs.jafs.Key;
 import org.openafs.jafs.Server;
 ...
 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];
 
     token = new Token(username, password, cellName);
     cell   = new Cell(token);
     server  = new Server(serverName, cell);
 
     System.out.println("Keys in Server " + server.getName() + ":");
     Key[] keys = server.getKeys();
     for (int i = 0; i < keys.length; i++) {
       System.out.println(" -> " + keys[i] );
     }
   }
   ...
 }
 

See Also:
Serialized Form

Field Summary
protected  boolean cachedInfo
           
protected  long checkSum
           
protected  String encryptionKey
           
protected  int lastModDate
           
protected  GregorianCalendar lastModDateDate
           
protected  int lastModMs
           
protected  Server server
           
protected  int version
           
 
Constructor Summary
  Key(int version, Server server)
          Constructs a new Key object instance given the version of the AFS key and the AFS server, represented by server, to which it belongs.
  Key(int version, Server server, boolean preloadAllMembers)
          Constructs a new Key object instance given the version of the AFS key and the AFS server, represented by server, to which it belongs.
(package private) Key(Server server)
          Creates a blank Key given the server to which the key belongs.
 
Method Summary
 int compareTo(Key key)
          Compares two Key objects respective to their key version and does not factor any other attribute.
 int compareTo(Object obj)
          Comparable interface method.
protected static void create(int cellHandle, int serverHandle, int versionNumber, String keyString)
          Create a server key.
 void create(String keyString)
          Creates a key with this Key's version number at the server, using the specified String for the key.
 void delete()
          Removes the key with this Key's version number from the server.
protected static void delete(int serverHandle, int versionNumber)
          Delete a server key.
 boolean equals(Key otherKey)
          Tests whether two Key objects are equal, based on their encryption key, version, and associated Server.
 long getCheckSum()
          Returns the check sum of this key.
 String getEncryptionKey()
          Returns the encrypted key as a string in octal form.
protected  String getInfo()
          Returns a String representation of this Key.
protected static void getKeyInfo(int serverHandle, int version, Key key)
          Fills in the information fields of the provided Key.
 GregorianCalendar getLastModDate()
          Returns the last modification date of this key.
 Server getServer()
          Returns the server this key is associated with.
 int getVersion()
          Returns the version of this key in primitive form.
protected static void reclaimKeyMemory()
          Reclaims all memory being saved by the key portion of the native library.
 void refresh()
          Refreshes the properties of this Key object instance with values from the AFS key it represents.
protected  void refresh(boolean all)
          Refreshes the properties of this Key object instance with values from the AFS key it represents.
protected  void refreshInfo()
          Refreshes the information fields of this Key to reflect the current state of the AFS server key.
 String toString()
          Returns the name of this Key
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

server

protected Server server

version

protected int version

checkSum

protected long checkSum

encryptionKey

protected String encryptionKey

lastModDate

protected int lastModDate

lastModMs

protected int lastModMs

lastModDateDate

protected GregorianCalendar lastModDateDate

cachedInfo

protected boolean cachedInfo
Constructor Detail

Key

public Key(int version,
           Server server)
    throws AFSException
Constructs a new Key object instance given the version of the AFS key and the AFS server, represented by server, to which it belongs. This does not actually create a new AFS key, it just represents one. If version is not an actual AFS key, exceptions will be thrown during subsequent method invocations on this object, unless the create(String) method is explicitly called to create it.

Parameters:
version - the version of the key to represent
server - the server to which the key belongs.
Throws:
AFSException - If an error occurs in the native code

Key

public Key(int version,
           Server server,
           boolean preloadAllMembers)
    throws AFSException
Constructs a new Key object instance given the version of the AFS key and the AFS server, represented by server, to which it belongs. This does not actually create a new AFS key, it just represents one. If version is not an actual AFS key, exceptions will be thrown during subsequent method invocations on this object, unless the create(String) method is explicitly called to create it. Note that if the key does not exist and preloadAllMembers is true, an exception will be thrown.

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

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

Key

Key(Server server)
throws AFSException
Creates a blank Key given the server to which the key belongs. This blank object can then be passed into other methods to fill out its properties.

Parameters:
server - the server to which the key belongs.
Throws:
AFSException - If an error occurs in the native code
Method Detail

refresh

public void refresh()
             throws AFSException
Refreshes the properties of this Key object instance with values from the AFS key it represents. All properties that have been initialized and/or accessed will be renewed according to the values of the AFS key this Key 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 Key object instance with values from the AFS key it represents. If all is true then all of the properties of this Key object instance will be set, or renewed, according to the values of the AFS key 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
Refreshes the information fields of this Key to reflect the current state of the AFS server key. These inlclude the last modification time, etc.

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

create

public void create(String keyString)
            throws AFSException
Creates a key with this Key's version number at the server, using the specified String for the key.

Parameters:
keyString - the string to use for the encryption key
Throws:
AFSException - If an error occurs in the native code

delete

public void delete()
            throws AFSException
Removes the key with this Key's version number from the server.

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

getVersion

public int getVersion()
Returns the version of this key in primitive form.

Returns:
the version number of this key

getServer

public Server getServer()
Returns the server this key is associated with.

Returns:
this key's server

getEncryptionKey

public String getEncryptionKey()
                        throws AFSException
Returns the encrypted key as a string in octal form. This is how AFS prints it out on the command line. An example would be: '\040\205\211\241\345\002\023\211'.

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

getCheckSum

public long getCheckSum()
                 throws AFSException
Returns the check sum of this key.

Returns:
the check sum of this key
Throws:
AFSException - If an error occurs in the native code

getLastModDate

public GregorianCalendar getLastModDate()
                                 throws AFSException
Returns the last modification date of this key.

Returns:
the last modification date of this key
Throws:
AFSException - If an error occurs in the native code

getInfo

protected String getInfo()
Returns a String representation of this Key. Contains the information fields.

Returns:
a String representation of the Key

compareTo

public int compareTo(Key key)
Compares two Key objects respective to their key version and does not factor any other attribute.

Parameters:
key - The Key object to be compared to this Key instance
Returns:
Zero if the argument is equal to this Key's version, a value less than zero if this Key's version is less than the argument, or a value greater than zero if this Key's version is greater than the argument

compareTo

public int compareTo(Object obj)
Comparable interface method.

Specified by:
compareTo in interface Comparable
See Also:
compareTo(Key)

equals

public boolean equals(Key otherKey)
Tests whether two Key objects are equal, based on their encryption key, version, and associated Server.

Parameters:
otherKey - the Key to test
Returns:
whether the specifed Key is the same as this Key

toString

public String toString()
Returns the name of this Key

Overrides:
toString in class Object
Returns:
the name of this Key

getKeyInfo

protected static void getKeyInfo(int serverHandle,
                                 int version,
                                 Key key)
                          throws AFSException
Fills in the information fields of the provided Key.

Parameters:
serverHandle - the bos handle of the server to which the key belongs
version - the version of the key for which to get the information
key - the Key object in which to fill in the information
Throws:
AFSException - If an error occurs in the native code
See Also:
Server.getBosServerHandle(int, java.lang.String), Server

create

protected static void create(int cellHandle,
                             int serverHandle,
                             int versionNumber,
                             String keyString)
                      throws AFSException
Create a server key.

Parameters:
cellHandle - the handle of the cell to which the server belongs
serverHandle - the bos handle of the server to which the key will belong
versionNumber - the version number of the key to create (0 to 255)
keyString - the String version of the key that will be encrypted
Throws:
AFSException - If an error occurs in the native code
See Also:
Cell.getCellHandle(), Server.getBosServerHandle(int, java.lang.String)

delete

protected static void delete(int serverHandle,
                             int versionNumber)
                      throws AFSException
Delete a server key.

Parameters:
serverHandle - the bos handle of the server to which the key belongs
versionNumber - the version number of the key to remove (0 to 255)
Throws:
AFSException - If an error occurs in the native code
See Also:
Server.getBosServerHandle(int, java.lang.String)

reclaimKeyMemory

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


JAFS API v2