tv.amwa.maj.iface
Interface RawStorage

All Known Subinterfaces:

RandomRawStorage

public interface RawStorage

This interface is used by the toolkit to access storage in which AAF files are to be read and written. It is typically implemented by clients of AAF file. Note that some implementations are provided as a convenience to AAF file clients.

When writing to a stream, clients should be aware that the stream's capacity may be limited. To insure that writes will not fail due to insufficient stream capacity, clients must implement RandomRawStorage and call RandomRawStorage.setExtent(long) to pre-allocate capacity in the stream. Writes done within the size specified to the most recent successful RandomRawStorage.setExtent(long) call are guaranteed to succeed.

This method assumes that the storage has at least sequential access capability.

Author:

Richard Cartwright

Method Summary

boolean	isReadable() Returns true if the storage is readable; otherwise false.
boolean	isWriteable() Returns true if this storage is writeable; otherwise false.
byte[]	read(int bufSize) Reads the given number of bytes from the stream of the raw storage and returns them as a byte array.
void	synchronize() Synchronizes any cached data of the raw storage object with the underlying storage.
int	write(byte[] buffer) Writes the given bytes into the stream of the raw storage.

Method Detail

isReadable

@Bool
boolean isReadable()

Returns true if the storage is readable; otherwise false.

Returns:

Is the storage readable?

read

@DataBuffer
byte[] read(@UInt32
                       int bufSize)
            throws NotReadableException

Reads the given number of bytes from the stream of the raw storage and returns them as a byte array. If the end of the stream is encountered before the given number of bytes can be read, the output array will contain fewer bytes than specified.

A call this method will advance the current position in the stream, as used by the next read operation, by the requested buffer size.

Parameters:

bufSize - Number of bytes to read from the raw storage stream.

Returns:

Buffer containing bytes read form raw storage stream.

Throws:

NotReadableException - The stream is not open for reading.

isWriteable

@Bool
boolean isWriteable()

Returns true if this storage is writeable; otherwise false.

Returns:

Is the raw storage writeable?

write

@UInt32
int write(@DataBuffer
                 byte[] buffer)
          throws NullPointerException,
                 NotWriteableException,
                 StreamFullException

Writes the given bytes into the stream of the raw storage.

This call may fail if the stream has insufficient capacity to complete the request. If this storage supports the random raw storage interface, the client can call RandomRawStorage.setExtent(long) to attempt to reserve capacity in the stream. If the call succeeds, subsequent calls to this method within that capacity are guaranteed to succeed.

This call will advance the current position by the length of the given array of bytes.

Parameters:

buffer - Bytes to write to the stream of the raw storage.

Returns:

Number of bytes actually written.

Throws:

NullPointerException - Argument is null.

NotWriteableException - The stream is not open for writing.

StreamFullException - The stream has insufficient capacity to perform the write.

synchronize

void synchronize()

Synchronizes any cached data of the raw storage object with the underlying storage.