Java AFS API v1.4

org.openafs.jafs
Class Volume

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

public class Volume
extends Object
implements Serializable, Comparable

An abstract representation of an AFS volume. It holds information about the server, such as what its quota is.

Constructing an instance of a Volume does not mean an actual AFS partition is created on a partition -- usually a Volume object is a representation of an already existing AFS volume. If, however, the Volume is constructed with the name of a volume that does not exist in the cell to which the provided Partition belongs, a new AFS volume with that name can be created on that partition by calling the create(int) method. If such a volume 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 Volume object. This example obtains the list of Volume objects residing on a particular partition, and prints out the name and id of each one.

 import org.openafs.jafs.Cell;
 import org.openafs.jafs.AFSException;
 import org.openafs.jafs.Partition;
 import org.openafs.jafs.Server;
 import org.openafs.jafs.Volume;
 ...
 public class ...
 {
   ...
   private Cell cell;
   private Server server;
   private Partition partition;
   ...
   public static void main(String[] args) throws Exception
   {
     String username      = arg[0];
     String password      = arg[1];
     String cellName      = arg[2];
     String serverName    = arg[3];
     String partitionName = arg[4];
 
     token  = new Token(username, password, cellName);
     cell   = new Cell(token);
     server = cell.getServer(serverName);
     partition = cell.getPartition(partitionName);
 
     System.out.println("Volumes in Partition " + partition.getName() + ":");
     Volume[] volumes = partition.getVolumes();
     for (int i = 0; i < volumes.length; i++) {
       System.out.println(" -> " + volumes[i] + ": " + volumes[i].getID());
     }
   }
   ...
 }
 

See Also:
Serialized Form

Field Summary
static int VOLUME_BUSY
          Status/disposition busy
static int VOLUME_DISK_FULL
          Status/disposition disk full
static int VOLUME_MOVED
          Status/disposition moved
static int VOLUME_NO_SERVICE
          Status/disposition no service
static int VOLUME_NO_VNODE
          Status/disposition no vnode
static int VOLUME_NO_VOL
          Status/disposition no volume
static int VOLUME_OFFLINE
          Status/disposition offline
static int VOLUME_OK
          Status/disposition ok
static int VOLUME_ONLINE
          Status/disposition online
static int VOLUME_OVER_QUOTA
          Status/disposition over quota
static int VOLUME_SALVAGE
          Status/disposition salvage
static int VOLUME_TYPE_BACKUP
          Backup volume type
static int VOLUME_TYPE_READ_ONLY
          Read-only volume type
static int VOLUME_TYPE_READ_WRITE
          Read-write volume type
static int VOLUME_VOL_EXISTS
          Status/disposition volume exists
 
Constructor Summary
Volume(String name, Partition partition)
          Constructs a new Volume object instance given the name of the AFS volume and the AFS cell, represented by partition, to which it belongs.
Volume(String name, Partition partition, boolean preloadAllMembers)
          Constructs a new Volume object instance given the name of the AFS volume and the AFS partition, represented by partition, to which it belongs.
 
Method Summary
 int compareTo(Object obj)
          Comparable interface method.
 int compareTo(Volume volume)
          Compares two Volume objects respective to their names and does not factor any other attribute.
 void create(int quota)
          Creates a new volume on the server and partition given upon construction.
 Volume createBackup()
          Creates a backup volume for this volume.
 void createMountPoint(String directory)
          Creates a read-write mount point for this volume.
 void createMountPoint(String directory, boolean readWrite)
          Creates a mount point for this volume.
 Volume createReadOnly(Partition sitePartition)
          Creates a readonly site for this volume on the specified server and partition.
 void delete()
          Deletes the volume from the cell.
 void dump(String fileName)
          Dumps this volume to a file.
 void dump(String fileName, GregorianCalendar dumpSince)
          Dumps this volume to a file.
 boolean equals(Volume otherVolume)
          Tests whether two Volume objects are equal, based on their names and hosting partition.
 int getAccessesSinceMidnight()
          Returns the number of accesses since midnight.
 int getBackupID()
          Returns the backup ID of this volume
 GregorianCalendar getCopyCreationDate()
          Returns the date the volume was copied.
 GregorianCalendar getCreationDate()
          Returns the date the volume was created
 int getCurrentSize()
          Returns current volume size in K.
 int getDisposition()
          Returns volume disposition.
 int getFileCount()
          Returns file count.
 int getID()
          Returns the id of this volume.
 GregorianCalendar getLastUpdateDate()
          Returns the date the volume was last updated.
 String getName()
          Returns the name of this volume.
 Partition getPartition()
          Returns this volume's hosting partition.
 int getQuota()
          Returns this volume's quota, expressed in kilobyte blocks (1024 kilobyte blocks equal one megabyte).
 int getReadOnlyID()
          Returns the read-only ID of this volume
 int getReadWriteID()
          Returns the read-write ID of this volume
 int getStatus()
          Returns volume status.
 int getTotalFreeSpace()
          Returns the difference between quota and current volume size (in K).
 int getType()
          Returns volume type.
 boolean isQuotaUnlimited()
          Tests whether this volume's quota is configured as unlimited.
 void lock()
          Locks the VLDB enrty for this volume
 void mount()
          Mounts this volume, bringing it online and making it accessible.
 void moveTo(Partition newPartition)
          Moves this volume to the specified partition (which indirectly specifies a new server, as well).
 void refresh()
          Refreshes the properties of this Volume object instance with values from the AFS volume it represents.
 void release()
          Releases this volume, which updates the read-only copies of it.
 void release(boolean forceComplete)
          Releases this volume, which updates the read-only copies of it.
 void rename(String newName)
          Renames this volume.
 void restore(String fileName, boolean incremental)
          Restores a file to this volume.
 void restore(String fileName, boolean incremental, int id)
          Restores a file to this volume.
 void salvage()
          Salvages (restores consistency to) this volume.
 void setQuota(int quota)
          Sets quota of volume, 0 denotes an unlimited quota.
 String toString()
          Returns the name of this Volume
 void unlock()
          Unlocks the VLDB entry for this volume
 void unmount()
          Unmounts this volume, bringing it offline and making it inaccessible.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

VOLUME_TYPE_READ_WRITE

public static final int VOLUME_TYPE_READ_WRITE
Read-write volume type

See Also:
Constant Field Values

VOLUME_TYPE_READ_ONLY

public static final int VOLUME_TYPE_READ_ONLY
Read-only volume type

See Also:
Constant Field Values

VOLUME_TYPE_BACKUP

public static final int VOLUME_TYPE_BACKUP
Backup volume type

See Also:
Constant Field Values

VOLUME_OK

public static final int VOLUME_OK
Status/disposition ok

See Also:
Constant Field Values

VOLUME_SALVAGE

public static final int VOLUME_SALVAGE
Status/disposition salvage

See Also:
Constant Field Values

VOLUME_NO_VNODE

public static final int VOLUME_NO_VNODE
Status/disposition no vnode

See Also:
Constant Field Values

VOLUME_NO_VOL

public static final int VOLUME_NO_VOL
Status/disposition no volume

See Also:
Constant Field Values

VOLUME_VOL_EXISTS

public static final int VOLUME_VOL_EXISTS
Status/disposition volume exists

See Also:
Constant Field Values

VOLUME_NO_SERVICE

public static final int VOLUME_NO_SERVICE
Status/disposition no service

See Also:
Constant Field Values

VOLUME_OFFLINE

public static final int VOLUME_OFFLINE
Status/disposition offline

See Also:
Constant Field Values

VOLUME_ONLINE

public static final int VOLUME_ONLINE
Status/disposition online

See Also:
Constant Field Values

VOLUME_DISK_FULL

public static final int VOLUME_DISK_FULL
Status/disposition disk full

See Also:
Constant Field Values

VOLUME_OVER_QUOTA

public static final int VOLUME_OVER_QUOTA
Status/disposition over quota

See Also:
Constant Field Values

VOLUME_BUSY

public static final int VOLUME_BUSY
Status/disposition busy

See Also:
Constant Field Values

VOLUME_MOVED

public static final int VOLUME_MOVED
Status/disposition moved

See Also:
Constant Field Values
Constructor Detail

Volume

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

Parameters:
name - the name of the volume to represent
partition - the partition on which the volume resides
Throws:
AFSException - If an error occurs in the native code

Volume

public Volume(String name,
              Partition partition,
              boolean preloadAllMembers)
       throws AFSException
Constructs a new Volume object instance given the name of the AFS volume and the AFS partition, represented by partition, to which it belongs. This does not actually create a new AFS volume, it just represents one. If name is not an actual AFS volume, exceptions will be thrown during subsequent method invocations on this object, unless the create(int) method is explicitly called to create it. Note that if the volume doesn't 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:
name - the name of the volume to represent
partition - the partition on which the volume resides.
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()
Method Detail

refresh

public void refresh()
             throws AFSException
Refreshes the properties of this Volume object instance with values from the AFS volume it represents. All properties that have been initialized and/or accessed will be renewed according to the values of the AFS volume this Volume 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

create

public void create(int quota)
            throws AFSException
Creates a new volume on the server and partition given upon construction.

Parameters:
quota - the quota for the volume in K, 0 indicates an unlimited quota
Throws:
AFSException - If an error occurs in the native code

createBackup

public Volume createBackup()
                    throws AFSException
Creates a backup volume for this volume.

Returns:
the Volume object representation for the backup volume that was created
Throws:
AFSException - If an error occurs in the native code

createReadOnly

public Volume createReadOnly(Partition sitePartition)
                      throws AFSException
Creates a readonly site for this volume on the specified server and partition. Automatically releases the volume.

Parameters:
sitePartition - the partition on which the readonly volume is to reside
Returns:
the Volume representation for the read-only volume that was created
Throws:
AFSException - If an error occurs in the native code

delete

public void delete()
            throws AFSException
Deletes the volume from the cell.

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

release

public void release()
             throws AFSException
Releases this volume, which updates the read-only copies of it.

This method will force a complete release; a complete release updates all read-only sites even if the VLDB entry has a flag.

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

release

public void release(boolean forceComplete)
             throws AFSException
Releases this volume, which updates the read-only copies of it.

Parameters:
forceComplete - whether or not to force a complete release; a complete release updates all read-only sites even if the VLDB entry has a flag
Throws:
AFSException - If an error occurs in the native code

dump

public void dump(String fileName,
                 GregorianCalendar dumpSince)
          throws AFSException
Dumps this volume to a file. If you use the dumpSince argument you will create an incremental dump, but you can leave it null for a full dump.

Parameters:
fileName - the path name of the file on the client machine to which to dump this volume
dumpSince - dump only files that have been modified more recently than this date
Throws:
AFSException - If an error occurs in the native code

dump

public void dump(String fileName)
          throws AFSException
Dumps this volume to a file. Creates a full dump.

Parameters:
fileName - the path name of the file to which to dump this volume
Throws:
AFSException - If an error occurs in the native code

restore

public void restore(String fileName,
                    boolean incremental)
             throws AFSException
Restores a file to this volume. Note that this does not have to be an existing volume in order to be restored - you may create a Volume as a volume that doesn't yet exist and then restore a file to it. Or you can restore over an existing volume. If a new volume is being created with this method, the id will be automatically assigned.

Parameters:
fileName - the path name of the file on the client machine from which to restore this volume
incremental - if true, restores an incremental dump over an existing volume
Throws:
AFSException - If an error occurs in the native code

restore

public void restore(String fileName,
                    boolean incremental,
                    int id)
             throws AFSException
Restores a file to this volume. Note that this does not have to be an existing volume in order to be restored - you may create a Volume as a volume that doesn't yet exist and then restore a file to it. Or you can restore over an existing volume.

Parameters:
fileName - the path name of the file on the client machine from which to restore this volume
incremental - if true, restores an incremental dump over an existing volume
id - the id to assign this volume
Throws:
AFSException - If an error occurs in the native code

mount

public void mount()
           throws AFSException
Mounts this volume, bringing it online and making it accessible.

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

unmount

public void unmount()
             throws AFSException
Unmounts this volume, bringing it offline and making it inaccessible.

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

lock

public void lock()
          throws AFSException
Locks the VLDB enrty for this volume

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

unlock

public void unlock()
            throws AFSException
Unlocks the VLDB entry for this volume

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

moveTo

public void moveTo(Partition newPartition)
            throws AFSException
Moves this volume to the specified partition (which indirectly specifies a new server, as well). Caution: This will remove any backup volumes at the original site.

Parameters:
newPartition - the partition to which to move the volume
Throws:
AFSException - If an error occurs in the native code

rename

public void rename(String newName)
            throws AFSException
Renames this volume.

Parameters:
newName - the new name for this volume
Throws:
AFSException - If an error occurs in the native code

salvage

public void salvage()
             throws AFSException
Salvages (restores consistency to) this volume. Uses default values for most salvager options in order to simplify the API.

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

createMountPoint

public void createMountPoint(String directory)
                      throws AFSException
Creates a read-write mount point for this volume. Does not ensure the volume already exists.

Parameters:
directory - the name of the directory where this volume should be mounted
Throws:
AFSException - If an error occurs in the native code

createMountPoint

public void createMountPoint(String directory,
                             boolean readWrite)
                      throws AFSException
Creates a mount point for this volume. Does not ensure the volume already exists.

Parameters:
directory - the name of the directory where this volume should be mounted
readWrite - whether or not this mount point should be read-write
Throws:
AFSException - If an error occurs in the native code

getName

public String getName()
Returns the name of this volume.

Returns:
the name of this volume

getPartition

public Partition getPartition()
Returns this volume's hosting partition.

Returns:
this volume's partition

getID

public int getID()
          throws AFSException
Returns the id of this volume.

Returns:
the id of this volume
Throws:
AFSException - If an error occurs in the native code

getReadWriteID

public int getReadWriteID()
                   throws AFSException
Returns the read-write ID of this volume

Returns:
the read-write id
Throws:
AFSException - If an error occurs in the native code

getReadOnlyID

public int getReadOnlyID()
                  throws AFSException
Returns the read-only ID of this volume

Returns:
the read-only id
Throws:
AFSException - If an error occurs in the native code

getBackupID

public int getBackupID()
                throws AFSException
Returns the backup ID of this volume

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

getCreationDate

public GregorianCalendar getCreationDate()
                                  throws AFSException
Returns the date the volume was created

Returns:
the date the volume was created
Throws:
AFSException - If an error occurs in the native code

getLastUpdateDate

public GregorianCalendar getLastUpdateDate()
                                    throws AFSException
Returns the date the volume was last updated. After this method is called once, it saves the date and returns that date on subsequent calls, until the refresh() method is called and a more current value is obtained.

Returns:
the date the volume was last updated
Throws:
AFSException - If an error occurs in the native code

getCopyCreationDate

public GregorianCalendar getCopyCreationDate()
                                      throws AFSException
Returns the date the volume was copied. After this method is called once, it saves the date and returns that date on subsequent calls, until the refresh() method is called and a more current value is obtained.

Returns:
the date the volume was copied
Throws:
AFSException - If an error occurs in the native code

getAccessesSinceMidnight

public int getAccessesSinceMidnight()
                             throws AFSException
Returns the number of accesses since midnight. After this method is called once, it saves the value and returns that value on subsequent calls, until the refresh() method is called and a more current value is obtained.

Returns:
the number of accesses since midnight
Throws:
AFSException - If an error occurs in the native code

getFileCount

public int getFileCount()
                 throws AFSException
Returns file count. After this method is called once, it saves the value and returns that value on subsequent calls, until the refresh() method is called and a more current value is obtained.

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

getCurrentSize

public int getCurrentSize()
                   throws AFSException
Returns current volume size in K. After this method is called once, it saves the value and returns that value on subsequent calls, until the refresh() method is called and a more current value is obtained.

Returns:
the current volume size in K
Throws:
AFSException - If an error occurs in the native code

getTotalFreeSpace

public int getTotalFreeSpace()
                      throws AFSException
Returns the difference between quota and current volume size (in K).

Please note: the product of this method is not saved.

Returns:
the current free space in K
Throws:
AFSException - If an error occurs in the native code

getQuota

public int getQuota()
             throws AFSException
Returns this volume's quota, expressed in kilobyte blocks (1024 kilobyte blocks equal one megabyte). After this method is called once, it saves the value and returns that value on subsequent calls, until the refresh() method is called and a more current value is obtained.

Note: A quota value of zero, "0", grants an unlimited quota in AFS. Consequently, to avoid delusion this method will throw an AFSException if the returning value is zero.

Returns:
the volume quota in K
Throws:
AFSException - If an error occurs in the native code or this volume's quota is configured as unlimited.
See Also:
isQuotaUnlimited()

isQuotaUnlimited

public boolean isQuotaUnlimited()
                         throws AFSException
Tests whether this volume's quota is configured as unlimited.

After this method is called once, it saves the value and returns that value on subsequent calls, until the refresh() method is called and a more current value is obtained.

Returns:
true if this volume's quota is configured as unlimited; otherwise false.
Throws:
AFSException - If an error occurs in the native code
See Also:
getQuota()

getStatus

public int getStatus()
              throws AFSException
Returns volume status. Possible values are: Typical value is VOLUME_OK. After this method is called once, it saves the value and returns that value on subsequent calls, until the refresh() method is called and a more current value is obtained.

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

getDisposition

public int getDisposition()
                   throws AFSException
Returns volume disposition. Possible values are: Typical value is VOLUME_ONLINE. After this method is called once, it saves the value and returns that value on subsequent calls, until the refresh() method is called and a more current value is obtained.

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

getType

public int getType()
            throws AFSException
Returns volume type. Possible values are:

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

setQuota

public void setQuota(int quota)
              throws AFSException
Sets quota of volume, 0 denotes an unlimited quota.

Parameters:
quota - the new volume quota in K (0 for unlimited)
Throws:
AFSException - If an error occurs in the native code

compareTo

public int compareTo(Volume volume)
Compares two Volume objects respective to their names and does not factor any other attribute. Alphabetic case is significant in comparing names.

Parameters:
volume - The Volume object to be compared to this Volume instance
Returns:
Zero if the argument is equal to this Volume's name, a value less than zero if this Volume's name is lexicographically less than the argument, or a value greater than zero if this Volume's name is lexicographically greater than the argument

compareTo

public int compareTo(Object obj)
Comparable interface method.

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

equals

public boolean equals(Volume otherVolume)
Tests whether two Volume objects are equal, based on their names and hosting partition.

Parameters:
otherVolume - the Volume to test
Returns:
whether the specifed Volume is the same as this Volume

toString

public String toString()
Returns the name of this Volume

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

Java AFS API (jafs) for OpenAFS

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