Java AFS Admin API v1.3

org.openafs.jafsadm
Class Key

java.lang.Object
  |
  +--org.openafs.jafsadm.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.jafsadm.Cell;
 import org.openafs.jafsadm.AFSAdminException;
 import org.openafs.jafsadm.Key;
 import org.openafs.jafsadm.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];
 
     cell    = new Cell(cellName, username, password);
     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] );
     }
   }
   ...
 }
 

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

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.
 
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.
 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.
 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.
 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.
 void refresh()
          Refreshes the properties of this Key object instance with values from the AFS key it represents.
 String toString()
          Returns the name of this Key
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Key

public Key(int version,
           Server server)
    throws AFSAdminException
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:
AFSAdminException - If an error occurs in the native code

Key

public Key(int version,
           Server server,
           boolean preloadAllMembers)
    throws AFSAdminException
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:
AFSAdminException - If an error occurs in the native code
See Also:
refresh()
Method Detail

refresh

public void refresh()
             throws AFSAdminException
Refreshes the properties of this 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:
AFSAdminException - If an error occurs in the native code

create

public void create(String keyString)
            throws AFSAdminException
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:
AFSAdminException - If an error occurs in the native code

delete

public void delete()
            throws AFSAdminException
Removes the key with this Key's version number from the server.
Throws:
AFSAdminException - 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 AFSAdminException
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:
AFSAdminException - If an error occurs in the native code

getCheckSum

public long getCheckSum()
                 throws AFSAdminException
Returns the check sum of this key.
Returns:
the check sum of this key
Throws:
AFSAdminException - If an error occurs in the native code

getLastModDate

public GregorianCalendar getLastModDate()
                                 throws AFSAdminException
Returns the last modification date of this key.
Returns:
the last modification date of this key
Throws:
AFSAdminException - If an error occurs in the native code

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

Java AFS Admin (jafsadm) API for OpenAFS

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