oracle.ifs.server

Interface RandomAccessDriver

public interface RandomAccessDriver

RandomAccessDriver provides random read/write access to content stored in a media.

A RandomAccessDriver instance is associated with a particular content id, in a particular session, and within the context of a specific writeable transaction. Changes to content made by write(long, byte[], int, int) and truncate(long) should be transactional. However, the effect of aborting a transaction in which write or truncate was called is unspecified, since some medias are non-transactional.

dispose() will be called to close the RandomAccessDriver. However this is not guaranteed to occur until the session is disconnected.

(Published)

Method Summary

Modifier and Type	Method and Description
void	dispose() Disposes this RandomAccessDriver.
boolean	isWriteable() Gets whether this RandomAccessDriver is writeable.
long	length() Gets the content length.
int	read(long pos, byte[] b, int off, int len) Reads bytes from content into a byte array.
void	truncate(long len) Truncates the content to exactly len bytes in length.
void	write(long pos, byte[] b, int off, int len) Writes bytes from a byte array.

Method Detail

read

int read(long pos,
         byte[] b,
         int off,
         int len)
  throws IfsException

Reads bytes from content into a byte array.

Reads from position pos in content, where 0 is the first byte in content, 1 is the second byte, and so forth.

Attempts to read as many as len bytes, but a smaller number of bytes may actually be read. Returns 0 if len is 0. Otherwise, blocks until at least one byte is read, the end of file is detected, or an error occurs. Returns the number of bytes actually read.

The bytes are read into b starting at index off. If r is the number of bytes actually read (as returned by the method), the bytes are read into elements b[off] through b[off+r-1]. Elements b[off+r] through b[off+len-1] are not changed. Additionally, elements b[0] through b[off-1] are never changed. Similarly, b[off+len] through b[b.length-1] are never changed.

An exception is thrown upon any of the following conditions:

• pos < 0
• pos >= length()
• b == null
• off < 0
• len < 0
• off + len > b.length

Parameters:

pos - the position in content from which to read

b - the buffer into which to read

off - the offset in the buffer

len - the maximum number of bytes to read

Returns:

the actual number of bytes read

Throws:

IfsException - 13600: if the operation fails

(Published)

isWriteable

boolean isWriteable()
             throws IfsException

Gets whether this RandomAccessDriver is writeable.

Returns:

whether writeable

Throws:

IfsException - 13601: if the operation fails

(Published)

write

void write(long pos,
           byte[] b,
           int off,
           int len)
    throws IfsException

Writes bytes from a byte array.

If len is 0, the content is unchanged. Otherwise, the content is changed as specified in the following two paragraphs.

The bytes b[off] through b[off+len-1] are written to positions pos through pos + len - 1 in the content, where 0 is the position of the first byte in content, 1 is the second byte, and so forth.

If, prior to the call, pos + len > length(), the method will extend the content so that pos + len == length().

When the method returns, the change must be visible within the session's transaction. Therefore, the method must not buffer unwritten changes beyond call duration.

An exception is thrown upon any of the following conditions:

• pos < 0
• b == null
• off < 0
• len < 0
• off + len > b.length
• this RandomAccessDriver is not writeable

Parameters:

pos - the position in content from which to write

b - the buffer from which to write

off - the offset in the buffer

len - the number of bytes to write

Throws:

IfsException - 13602: if the operation fails

(Published)

truncate

void truncate(long len)
       throws IfsException

Truncates the content to exactly len bytes in length.

If len > length(), the content at byte positions len through length() - 1 are dropped, where 0 is the position of the first byte in content, 1 the second byte, and so forth.

If len < length(), the content is resized by zero-filling positions length() through len - 1.

If len == length(), the method has no effect.

In all three cases, after the method returns, length() will return len.

When the method returns, the change must be visible within the session's transaction. Therefore, the method must not buffer unwritten changes beyond call duration.

An exception is thrown if len < 0 or this RandomAccessDriver is not writeable.

Parameters:

len - the desired content length

Throws:

IfsException - 13603: if the operation fails

(Published)

length

long length()
     throws IfsException

Gets the content length.

Returns:

the length, in bytes

Throws:

IfsException - 13604: if the operation fails

(Published)

dispose

void dispose()
      throws IfsException

Disposes this RandomAccessDriver.

This method will be called at some point before the session is disconnected. When dispose is called, the session may be in a different transaction and bound to a different database connection. Consequently, this method must not make database changes.

Throws:

IfsException - 13605: if the operation fails

(Published)