307 lines
12 KiB
Java
307 lines
12 KiB
Java
/*
|
|
* Copyright (c) 2008-2011 by Paul Seiferth, Zuse Institute Berlin
|
|
*
|
|
* Licensed under the BSD License, see LICENSE file for details.
|
|
*
|
|
*/
|
|
package org.xtreemfs.common.libxtreemfs;
|
|
|
|
import java.io.IOException;
|
|
|
|
import org.xtreemfs.common.libxtreemfs.exceptions.AddressToUUIDNotFoundException;
|
|
import org.xtreemfs.common.libxtreemfs.exceptions.PosixErrorException;
|
|
import org.xtreemfs.common.libxtreemfs.exceptions.UUIDNotInXlocSetException;
|
|
import org.xtreemfs.foundation.pbrpc.generatedinterfaces.RPC.UserCredentials;
|
|
import org.xtreemfs.pbrpc.generatedinterfaces.MRC.Stat;
|
|
import org.xtreemfs.pbrpc.generatedinterfaces.OSD.Lock;
|
|
|
|
/**
|
|
* FileHandle represents an open file.
|
|
*/
|
|
public interface FileHandle {
|
|
|
|
/**
|
|
* Read from a file 'count' bytes starting at 'offset' into 'buf'.
|
|
*
|
|
* @param userCredentials
|
|
* Name and Groups of the user.
|
|
* @param data
|
|
* [out] Byte array to be filled with read data.
|
|
* @param count
|
|
* Number of requested bytes.
|
|
* @param offset
|
|
* Offset in bytes.
|
|
*
|
|
* @throws AddressToUUIDNotFoundException
|
|
* @throws IOException
|
|
* @throws PosixErrorException
|
|
*
|
|
* @return Number of bytes read.
|
|
*/
|
|
public int read(UserCredentials userCredentials, byte[] data, int count, long offset)
|
|
throws IOException, PosixErrorException, AddressToUUIDNotFoundException;
|
|
|
|
/**
|
|
* Read from a file 'count' bytes starting at 'offset' into 'buf'.
|
|
*
|
|
* @param userCredentials
|
|
* Name and Groups of the user.
|
|
* @param data
|
|
* [out] Byte array to be filled with read data.
|
|
* @param dataOffset
|
|
* Offset in data array. This is the position of the first bytes in the data array that should
|
|
* be read.
|
|
* @param count
|
|
* Number of requested bytes.
|
|
* @param offset
|
|
* Offset in bytes. At this position in the file the data will be read.
|
|
*
|
|
* @throws AddressToUUIDNotFoundException
|
|
* @throws IOException
|
|
* @throws PosixErrorException
|
|
*
|
|
* @return Number of bytes read.
|
|
*/
|
|
public int read(UserCredentials userCredentials, byte[] data, int dataOffset, int count, long offset)
|
|
throws IOException, PosixErrorException, AddressToUUIDNotFoundException;
|
|
|
|
/**
|
|
* Write to a file 'count' bytes at file offset 'offset' from 'buf'.
|
|
*
|
|
* @attention If asynchronous writes are enabled (which is the default unless the file was opened with
|
|
* O_SYNC or async writes were disabled globally), no possible write errors can be returned as
|
|
* write() does return immediately after putting the write request into the send queue instead
|
|
* of waiting until the result was received. In this case, only after calling flush() or
|
|
* close() occurred write errors are returned to the user.
|
|
*
|
|
* @param userCredentials
|
|
* Name and Groups of the user.
|
|
* @param data
|
|
* [] [in] Byte array which contains data to be written.
|
|
* @param count
|
|
* Number of bytes to be written from buf.
|
|
* @param offset
|
|
* Offset in bytes.
|
|
*
|
|
*
|
|
* @throws AddressToUUIDNotFoundException
|
|
* @throws IOException
|
|
* @throws PosixErrorException
|
|
*
|
|
* @return Number of bytes written (see @attention above).
|
|
*/
|
|
public int write(UserCredentials userCredentials, byte[] data, int count, long offset)
|
|
throws IOException, PosixErrorException, AddressToUUIDNotFoundException;
|
|
|
|
/**
|
|
* Write to a file 'count' bytes at file offset 'offset' from 'buf'.
|
|
*
|
|
* @attention If asynchronous writes are enabled (which is the default unless the file was opened with
|
|
* O_SYNC or async writes were disabled globally), no possible write errors can be returned as
|
|
* write() does return immediately after putting the write request into the send queue instead
|
|
* of waiting until the result was received. In this case, only after calling flush() or
|
|
* close() occurred write errors are returned to the user.
|
|
*
|
|
* @param userCredentials
|
|
* Name and Groups of the user.
|
|
*
|
|
* @param data
|
|
* [] [in] Byte array which contains data to be written.
|
|
* @param dataOffset
|
|
* Offset in data array. This is the position of the first bytes in the data array that should
|
|
* be written.
|
|
* @param count
|
|
* Number of bytes to be written from buf.
|
|
* @param offset
|
|
* Offset in bytes. At this position in the file the data will be written.
|
|
*
|
|
* @throws AddressToUUIDNotFoundException
|
|
* @throws IOException
|
|
* @throws PosixErrorException
|
|
*
|
|
* @return Number of bytes written (see @attention above).
|
|
*/
|
|
public int write(UserCredentials userCredentials, byte[] data, int dataOffset, int count,
|
|
long offset) throws IOException, PosixErrorException, AddressToUUIDNotFoundException;
|
|
|
|
/**
|
|
* Flushes pending writes and file size updates (corresponds to a fsync() system call).
|
|
*
|
|
* @throws AddressToUUIDNotFoundException
|
|
* @throws IOException
|
|
* @throws PosixErrorException
|
|
*/
|
|
public void flush() throws IOException, PosixErrorException, AddressToUUIDNotFoundException;
|
|
|
|
/**
|
|
* Truncates the file to "newFileSize_ bytes".
|
|
*
|
|
* @param userCredentials
|
|
* Name and Groups of the user.
|
|
* @param newFileSize
|
|
* New size of the file.
|
|
*
|
|
* @throws AddressToUUIDNotFoundException
|
|
* @throws IOException
|
|
* @throws PosixErrorException
|
|
**/
|
|
public void truncate(UserCredentials userCredentials, long newFileSize) throws IOException,
|
|
PosixErrorException, AddressToUUIDNotFoundException;
|
|
|
|
/**
|
|
* Retrieve the attributes of this file and writes the result in "stat".
|
|
*
|
|
* @param userCredentials
|
|
* Name and Groups of the user.
|
|
*
|
|
* @throws AddressToUUIDNotFoundException
|
|
* @throws IOException
|
|
* @throws PosixErrorException
|
|
*/
|
|
public Stat getAttr(UserCredentials userCredentials) throws IOException, PosixErrorException,
|
|
AddressToUUIDNotFoundException;
|
|
|
|
/**
|
|
* Sets a lock on the specified file region and returns the resulting Lock object.
|
|
*
|
|
* If the acquisition of the lock fails, PosixErrorException will be thrown and posix_errno() will return
|
|
* POSIX_ERROR_EAGAIN.
|
|
*
|
|
* @param userCredentials
|
|
* Name and Groups of the user.
|
|
* @param processId
|
|
* ID of the process to which the lock belongs.
|
|
* @param offset
|
|
* Start of the region to be locked in the file.
|
|
* @param length
|
|
* Length of the region.
|
|
* @param exclusive
|
|
* shared/read lock (false) or write/exclusive (true)?
|
|
* @param waitForLock
|
|
* if true, blocks until lock acquired.
|
|
*
|
|
* @throws AddressToUUIDNotFoundException
|
|
* @throws IOException
|
|
* @throws PosixErrorException
|
|
*
|
|
* @remark Ownership is transferred to the caller.
|
|
*/
|
|
public Lock acquireLock(UserCredentials userCredentials, int processId, long offset,
|
|
long length, boolean exclusive, boolean waitForLock) throws IOException, PosixErrorException,
|
|
AddressToUUIDNotFoundException;
|
|
|
|
/**
|
|
* Checks if the requested lock does not result in conflicts. If true, the returned Lock object contains
|
|
* the requested 'process_id' in 'client_pid', otherwise the Lock object is a copy of the conflicting
|
|
* lock.
|
|
*
|
|
* @param userCredentials
|
|
* Name and Groups of the user.
|
|
* @param processId
|
|
* ID of the process to which the lock belongs.
|
|
* @param offset
|
|
* Start of the region to be locked in the file.
|
|
* @param length
|
|
* Length of the region.
|
|
* @param exclusive
|
|
* shared/read lock (false) or write/exclusive (true)?
|
|
*
|
|
* @throws AddressToUUIDNotFoundException
|
|
* @throws IOException
|
|
* @throws PosixErrorException
|
|
*
|
|
* @remark Ownership is transferred to the caller.
|
|
*/
|
|
public Lock checkLock(UserCredentials userCredentials, int processId, long offset, long length,
|
|
boolean exclusive) throws IOException, PosixErrorException, AddressToUUIDNotFoundException;
|
|
|
|
/**
|
|
* Releases "lock".
|
|
*
|
|
* @param userCredentials
|
|
* Name and Groups of the user.
|
|
* @param processId
|
|
* ID of the process to which the lock belongs.
|
|
* @param offset
|
|
* Start of the region to be locked in the file.
|
|
* @param length
|
|
* Length of the region.
|
|
* @param exclusive
|
|
* shared/read lock (false) or write/exclusive (true)?
|
|
*
|
|
* @throws AddressToUUIDNotFoundException
|
|
* @throws IOException
|
|
* @throws PosixErrorException
|
|
*/
|
|
public void releaseLock(UserCredentials userCredentials, int processId, long offset,
|
|
long length, boolean exclusive) throws IOException, PosixErrorException,
|
|
AddressToUUIDNotFoundException;
|
|
|
|
/**
|
|
* Releases "lock" (parameters given in Lock object).
|
|
*
|
|
* @param userCredentials
|
|
* Name and Groups of the user.
|
|
* @param lock
|
|
* Lock to be released.
|
|
*
|
|
* @throws AddressToUUIDNotFoundException
|
|
* @throws IOException
|
|
* @throws PosixErrorException
|
|
*/
|
|
public void releaseLock(UserCredentials userCredentials, Lock lock) throws IOException,
|
|
PosixErrorException, AddressToUUIDNotFoundException;
|
|
|
|
/**
|
|
* Releases the lock possibly hold by "processId". Use this before closing a file to ensure POSIX
|
|
* semantics:
|
|
*
|
|
* "All locks associated with a file for a given process shall be removed when a file descriptor for that
|
|
* file is closed by that process or the process holding that file descriptor terminates."
|
|
* (http://pubs.opengroup.org/onlinepubs/009695399/functions/fcntl.html)
|
|
*
|
|
* @param processId
|
|
* ID of the process whose lock shall be released.
|
|
*
|
|
*
|
|
* @throws AddressToUUIDNotFoundException
|
|
* @throws IOException
|
|
* @throws PosixErrorException
|
|
*/
|
|
public void releaseLockOfProcess(int processId) throws IOException, PosixErrorException,
|
|
AddressToUUIDNotFoundException;
|
|
|
|
/**
|
|
* Triggers the replication of the replica on the OSD with the UUID "osd_uuid" if the replica is a full
|
|
* replica (and not a partial one).
|
|
*
|
|
* The Replica had to be added beforehand and "osd_uuid" has to be included in the XlocSet of the file.
|
|
*
|
|
* @param userCredentials
|
|
* Name and Groups of the user.
|
|
* @param osdUuid
|
|
* UUID of the OSD where the replica is located.
|
|
*
|
|
* @throws AddressToUUIDNotFoundException
|
|
* @throws IOException
|
|
* @throws PosixErrorException
|
|
* @throws UUIDNotInXlocSetException
|
|
*/
|
|
public void pingReplica(UserCredentials userCredentials, String osdUuid) throws IOException,
|
|
AddressToUUIDNotFoundException;
|
|
|
|
/**
|
|
* Closes the open file handle (flushing any pending data).
|
|
*
|
|
* @attention Please execute ReleaseLockOfProcess() first if there're multiple open file handles for the
|
|
* same file and you want to ensure the POSIX semantics that with the close of a file handle
|
|
* the lock (XtreemFS allows only one per tuple (client UUID, Process ID)) of the process will
|
|
* be closed. If you do not care about this, you don't have to release any locks on your own as
|
|
* all locks will be automatically released if the last open file handle of a file will be
|
|
* closed.
|
|
*
|
|
* @throws IOException
|
|
*/
|
|
public void close() throws IOException;
|
|
}
|