org.biffle.cliff.pearl
Interface PearlConnection

All Known Implementing Classes:

PearlTCPConnection

public interface PearlConnection

Objects implementing PearlConnection provide a reasonably low-level interface to the Pearl protocol, with no caching. The next layer up should handle caching, logic, and exception and protocol error handling. Basically, if you treat the Pearl protocol as an RPC mechanism, this is the local proxy interface. Details this interface hides include: - The two steps of the authentication process. - Locking/unlocking

Method Summary

void	authenticate(java.lang.String password) Attempts to authenticate using a given password.
void	close() Closes a connection.
void	deleteFile(int fid) Removes a file from the device.
void	getAllFileInfo(FileInfoListener target) Retrieves all file information from the device using a callback mechanism.
DeviceInfo	getDeviceInfo() Returns an object encapsulating basic device information -- number of storage devices, system software name, and firmware version.
DeviceSettings	getDeviceSettings() Retrieves the Pearl device's settings as a DeviceSettings object.
FileInfo	getFileInfo(int fid) Retrieves information on a single file, by FID.
StorageInfo	getStorageInfo(int index) Retrieves information about a storage device in the Pearl device.
int[]	getVersion() Returns the version of the protocol being used as an array of two integers: the major and minor versions, respectively.
boolean	isAuthenticated() Checks to see if the underlying session has been successfully authenticated.
long	readFileChunk(int fid, long offset, long size, byte[] buffer) Retrieves a chunk of a file into a supplied buffer.
void	setFileInfo(int fid, FileInfo newInfo) Updates information for a file identified by FID.
void	writeFileChunk(int fid, int storageID, long offset, long size, byte[] buffer) Writes a chunk of a file from a supplied buffer.

Method Detail

getVersion

public int[] getVersion()
                 throws PearlException

Returns the version of the protocol being used as an array of two integers: the major and minor versions, respectively.

PearlException

isAuthenticated

public boolean isAuthenticated()

Checks to see if the underlying session has been successfully authenticated.

authenticate

public void authenticate(java.lang.String password)
                  throws PearlException

Attempts to authenticate using a given password.

PearlException

getDeviceInfo

public DeviceInfo getDeviceInfo()
                         throws PearlException

Returns an object encapsulating basic device information -- number of storage devices, system software name, and firmware version.

PearlException

getStorageInfo

public StorageInfo getStorageInfo(int index)
                           throws PearlException

Retrieves information about a storage device in the Pearl device.

PearlException

getDeviceSettings

public DeviceSettings getDeviceSettings()
                                 throws PearlException

Retrieves the Pearl device's settings as a DeviceSettings object.

PearlException

getAllFileInfo

public void getAllFileInfo(FileInfoListener target)
                    throws PearlException

Retrieves all file information from the device using a callback mechanism. As each file comes in, it is delivered as a FileInfo object to the target.

PearlException

getFileInfo

public FileInfo getFileInfo(int fid)
                     throws PearlException

Retrieves information on a single file, by FID.

PearlException

setFileInfo

public void setFileInfo(int fid,
                        FileInfo newInfo)
                 throws PearlException

Updates information for a file identified by FID.

PearlException

writeFileChunk

public void writeFileChunk(int fid,
                           int storageID,
                           long offset,
                           long size,
                           byte[] buffer)
                    throws PearlException

Writes a chunk of a file from a supplied buffer.

Parameters:

fid - The FID of the file to write.

storageID - The index of the storage device to write to.

offset - The offset within the file to begin writing.

size - The number of bytes to be written.

buffer - The buffer from which bytes are sent.

PearlException

readFileChunk

public long readFileChunk(int fid,
                          long offset,
                          long size,
                          byte[] buffer)
                   throws PearlException

Retrieves a chunk of a file into a supplied buffer.

Parameters:

fid - The FID of the file to read.

offset - The offset within the file to begin reading.

size - The number of bytes desired. If the end of the file is encountered, this will be fewer than were requested.

buffer - The buffer into which bytes are copied.

Returns:

The number of bytes read.

PearlException

deleteFile

public void deleteFile(int fid)
                throws PearlException

Removes a file from the device.

PearlException

close

public void close()

Closes a connection.