2 * @(#)Key.java 1.0 6/29/2001
4 * Copyright (c) 2001 International Business Machines Corp.
7 * This software has been released under the terms of the IBM Public
8 * License. For details, see the LICENSE file in the top-level source
9 * directory or online at http://www.openafs.org/dl/license10.html
11 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
12 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
13 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
14 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR
15 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
16 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
17 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
18 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
19 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
20 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
21 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
24 package org
.openafs
.jafs
;
26 import java
.util
.GregorianCalendar
;
27 import java
.util
.Date
;
28 import java
.io
.Serializable
;
31 * An abstract representation of an AFS key. It holds information about
32 * the key, such as what its version is.
35 * Constructing an instance of a <code>Key</code> does not mean an actual
36 * AFS key is created on a server -- usually a <code>Key</code>
37 * object is a representation of an already existing AFS key. If,
38 * however, the <code>Key</code> is constructed with the version number of a
39 * key that does not exist on the server represented by the provided
40 * <code>Server</code>, a new key with that version number can be
41 * created on that server by calling the {@link #create(String)} methods If
42 * such a key does already exist when this method is called,
43 * an exception will be thrown.<BR><BR>
45 * <!--Example of how to use class-->
46 * The following is a simple example of how to construct and use a
47 * <code>Key</code> object. It obtains the list of <code>Key</code>s from
48 * a specified server, and prints the string representation of each key.
50 * import org.openafs.jafs.Cell;
51 * import org.openafs.jafs.AFSException;
52 * import org.openafs.jafs.Key;
53 * import org.openafs.jafs.Server;
59 * private Server server;
61 * public static void main(String[] args) throws Exception
63 * String username = arg[0];
64 * String password = arg[1];
65 * String cellName = arg[2];
66 * String serverName = arg[3];
68 * token = new Token(username, password, cellName);
69 * cell = new Cell(token);
70 * server = new Server(serverName, cell);
72 * System.out.println("Keys in Server " + server.getName() + ":");
73 * Key[] keys = server.getKeys();
74 * for (int i = 0; i < keys.length; i++) {
75 * System.out.println(" -> " + keys[i] );
83 public class Key
implements Serializable
, Comparable
85 protected Server server
;
87 protected int version
;
88 protected long checkSum
;
89 protected String encryptionKey
;
90 protected int lastModDate
;
91 protected int lastModMs
;
93 protected GregorianCalendar lastModDateDate
;
95 protected boolean cachedInfo
;
98 * Constructs a new <CODE>Key</CODE> object instance given the version of
99 * the AFS key and the AFS server, represented by <CODE>server</CODE>,
100 * to which it belongs. This does not actually
101 * create a new AFS key, it just represents one.
102 * If <code>version</code> is not an actual AFS key, exceptions
103 * will be thrown during subsequent method invocations on this
104 * object, unless the {@link #create(String)}
105 * method is explicitly called to create it.
107 * @exception AFSException If an error occurs in the native code
108 * @param version the version of the key to represent
109 * @param server the server to which the key belongs.
111 public Key( int version
, Server server
) throws AFSException
113 this.server
= server
;
114 this.version
= version
;
116 lastModDateDate
= null;
122 * Constructs a new <CODE>Key</CODE> object instance given the version of
123 * the AFS key and the AFS server, represented by <CODE>server</CODE>,
124 * to which it belongs. This does not actually
125 * create a new AFS key, it just represents one.
126 * If <code>version</code> is not an actual AFS key, exceptions
127 * will be thrown during subsequent method invocations on this
128 * object, unless the {@link #create(String)}
129 * method is explicitly called to create it. Note that if the key does not
130 * exist and <code>preloadAllMembers</code> is true, an exception will
133 * <P> This constructor is ideal for point-in-time representation and
134 * transient applications. It ensures all data member values are set and
135 * available without calling back to the filesystem at the first request
136 * for them. Use the {@link #refresh()} method to address any coherency
139 * @param version the version of the key to represent
140 * @param server the server to which the key belongs.
141 * @param preloadAllMembers true will ensure all object members are set
142 * upon construction; otherwise members will be
143 * set upon access, which is the default behavior.
144 * @exception AFSException If an error occurs in the native code
147 public Key( int version
, Server server
, boolean preloadAllMembers
)
150 this(version
, server
);
151 if (preloadAllMembers
) refresh(true);
155 * Creates a blank <code>Key</code> given the server to which the key
156 * belongs. This blank object can then be passed into other methods to
157 * fill out its properties.
159 * @exception AFSException If an error occurs in the native code
160 * @param server the server to which the key belongs.
162 Key( Server server
) throws AFSException
167 /*-------------------------------------------------------------------------*/
170 * Refreshes the properties of this Key object instance with values from
171 * the AFS key it represents. All properties that have been initialized
172 * and/or accessed will be renewed according to the values of the AFS key
173 * this Key object instance represents.
175 * <P>Since in most environments administrative changes can be administered
176 * from an AFS command-line program or an alternate GUI application, this
177 * method provides a means to refresh the Java object representation and
178 * thereby ascertain any possible modifications that may have been made
179 * from such alternate administrative programs. Using this method before
180 * an associated instance accessor will ensure the highest level of
181 * representative accuracy, accommodating changes made external to the
182 * Java application space. If administrative changes to the underlying AFS
183 * system are only allowed via this API, then the use of this method is
186 * @exception AFSException If an error occurs in the native code
188 public void refresh() throws AFSException
194 * Refreshes the properties of this Key object instance with values from
195 * the AFS key it represents. If <CODE>all</CODE> is <CODE>true</CODE>
196 * then <U>all</U> of the properties of this Key object instance will be
197 * set, or renewed, according to the values of the AFS key it represents,
198 * disregarding any previously set properties.
200 * <P> Thus, if <CODE>all</CODE> is <CODE>false</CODE> then properties that
201 * are currently set will be refreshed and properties that are not set will
202 * remain uninitialized. See {@link #refresh()} for more information.
204 * @param all if true set or renew all object properties; otherwise renew
206 * @exception AFSException If an error occurs in the native code
209 protected void refresh(boolean all
) throws AFSException
211 if( all
|| cachedInfo
) {
217 * Refreshes the information fields of this <code>Key</code> to reflect the
218 * current state of the AFS server key. These inlclude the last
219 * modification time, etc.
221 * @exception AFSException If an error occurs in the native code
223 protected void refreshInfo() throws AFSException
225 getKeyInfo( server
.getBosHandle(), version
, this );
227 lastModDateDate
= null;
231 * Creates a key with this <code>Key's</code> version number at the server,
232 * using the specified <code>String</code> for the key.
234 * @param keyString the string to use for the encryption key
235 * @exception AFSException If an error occurs in the native code
237 public void create( String keyString
) throws AFSException
239 create( server
.getCell().getCellHandle(), server
.getBosHandle(), version
,
244 * Removes the key with this <code>Key's</code> version number from
247 * @exception AFSException If an error occurs in the native code
249 public void delete( ) throws AFSException
251 delete( server
.getBosHandle(), version
);
253 encryptionKey
= null;
257 //////////////// accessors: ////////////////////////
260 * Returns the version of this key in primitive form.
262 * @return the version number of this key
264 public int getVersion()
270 * Returns the server this key is associated with.
272 * @return this key's server
274 public Server
getServer()
280 * Returns the encrypted key as a string in octal form. This is how AFS
281 * prints it out on the command line. An example would be:
282 * '\040\205\211\241\345\002\023\211'.
284 * @return the encrypted key
285 * @exception AFSException If an error occurs in the native code
287 public String
getEncryptionKey() throws AFSException
289 if (!cachedInfo
) refreshInfo();
290 return encryptionKey
;
294 * Returns the check sum of this key.
296 * @return the check sum of this key
297 * @exception AFSException If an error occurs in the native code
299 public long getCheckSum() throws AFSException
301 if (!cachedInfo
) refreshInfo();
306 * Returns the last modification date of this key.
308 * @return the last modification date of this key
309 * @exception AFSException If an error occurs in the native code
311 public GregorianCalendar
getLastModDate() throws AFSException
313 if (!cachedInfo
) refreshInfo();
314 if ( lastModDateDate
== null && cachedInfo
) {
315 // make it into a date . . .
316 lastModDateDate
= new GregorianCalendar();
317 long longTime
= ((long) lastModDate
)*1000;
318 Date d
= new Date( longTime
);
319 lastModDateDate
.setTime( d
);
321 return lastModDateDate
;
324 /////////////// information methods ////////////////////
327 * Returns a <code>String</code> representation of this <code>Key</code>.
328 * Contains the information fields.
330 * @return a <code>String</code> representation of the <code>Key</code>
332 public String
getInfo()
336 r
= "Key version number: " + getVersion() + "\n";
337 r
+= "\tencrypted key: " + getEncryptionKey() + "\n";
338 r
+= "\tcheck sum: " + getCheckSum() + "\n";
339 r
+= "\tlast mod time: " + getLastModDate().getTime() + "\n";
340 } catch( Exception e
) {
346 /////////////// override methods ////////////////////
349 * Compares two Key objects respective to their key version and does not
350 * factor any other attribute.
352 * @param key The Key object to be compared to this Key instance
354 * @return Zero if the argument is equal to this Key's version, a
355 * value less than zero if this Key's version is less than
356 * the argument, or a value greater than zero if this Key's
357 * version is greater than the argument
359 public int compareTo(Key key
)
361 return (this.getVersion() - key
.getVersion());
365 * Comparable interface method.
367 * @see #compareTo(Key)
369 public int compareTo(Object obj
)
371 return compareTo((Key
)obj
);
375 * Tests whether two <code>Key</code> objects are equal, based on their
376 * encryption key, version, and associated Server.
378 * @param otherKey the Key to test
379 * @return whether the specifed Key is the same as this Key
381 public boolean equals( Key otherKey
)
384 return ( this.getEncryptionKey().equals(otherKey
.getEncryptionKey()) ) &&
385 ( this.getVersion() == otherKey
.getVersion() ) &&
386 ( this.getServer().equals(otherKey
.getServer()) );
387 } catch (Exception e
) {
393 * Returns the name of this <CODE>Key</CODE>
395 * @return the name of this <CODE>Key</CODE>
397 public String
toString()
400 return getVersion() + " - " + getEncryptionKey() + " - " + getCheckSum();
401 } catch (Exception e
) {
406 /////////////// native methods ////////////////////
409 * Fills in the information fields of the provided <code>Key</code>.
411 * @param serverHandle the bos handle of the server to which the key
413 * @see Server#getBosServerHandle
414 * @param version the version of the key for which to get the information
415 * @param key the <code>Key</code> object in which to fill in the
418 * @exception AFSException If an error occurs in the native code
420 protected static native void getKeyInfo( long serverHandle
, int version
,
425 * Create a server key.
427 * @param cellHandle the handle of the cell to which the server belongs
428 * @see Cell#getCellHandle
429 * @param serverHandle the bos handle of the server to which the key will
431 * @see Server#getBosServerHandle
432 * @param versionNumber the version number of the key to create (0 to 255)
433 * @param keyString the <code>String</code> version of the key that will
435 * @exception AFSException If an error occurs in the native code
437 protected static native void create( long cellHandle
, long serverHandle
, int versionNumber
, String keyString
)
441 * Delete a server key.
443 * @param serverHandle the bos handle of the server to which the key belongs
444 * @see Server#getBosServerHandle
445 * @param versionNumber the version number of the key to remove (0 to 255)
446 * @exception AFSException If an error occurs in the native code
448 protected static native void delete( long serverHandle
, int versionNumber
)
452 * Reclaims all memory being saved by the key portion of the native library.
453 * This method should be called when no more <code>Key</code> objects are
457 protected static native void reclaimKeyMemory();