Media Authoring
with Java API

tv.amwa.maj.iface
Interface RandomRawStorage

All Superinterfaces:
RawStorage

public interface RandomRawStorage
extends 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.

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

Objects that implement RandomRawStorage also implement the following interfaces:

Author:
Richard Cartwright

Method Summary
 long getExtent()
          Returns the number of bytes currently allocated to the storage.
 long getSize()
          Returns the highest byte position in the storage that has been written so far.
 boolean isExtendable()
          Returns true if the memory allocated to the storage can be dynamically extended; otherwise false.
 byte[] readAt(long position, int bufSize)
          Attempts to read and return the given number of bytes (bufSize) from the storage at the given position.
 void setExtent(long extent)
          Request the given capacity for the storage.
 int writeAt(long position, byte[] buffer)
          Writes the given data buffer into the stream of the raw storage at the given position.
 
Methods inherited from interface tv.amwa.maj.iface.RawStorage
isReadable, isWriteable, read, synchronize, write
 

Method Detail

readAt

@DataBuffer
byte[] readAt(@UInt64
                         long position,
                         @UInt32
                         int bufSize)
              throws NotReadableException

Attempts to read and return the given number of bytes (bufSize) from the storage at the given position. If the end of storage is encountered before the number of requested bytes can be read, the size of the array of bytes returned will be smaller than the one requested.

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:
position - Position in the storage from which data is read.
bufSize - Number of bytes to read from the storage.
Returns:
Array of bytes read from the storage stream at the given position and up to the given size.
Throws:
NotReadableException - The storage is not open for reading.

writeAt

@UInt32
int writeAt(@UInt64
                   long position,
                   @DataBuffer
                   byte[] buffer)
            throws NullPointerException,
                   OffsetSizeException,
                   NotWriteableException

Writes the given data buffer into the stream of the raw storage at the given position.

This call may fail if the capacity of this storage cannot be extended sufficiently to complete the request. The client can call setExtent(long) to attempt to reserve capacity for the storage. If the setExtent(long) call succeeds, subsequent write calls within requested that capacty are guaranteed to succeed.

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

Parameters:
position - Position in the storage into which the data is written.
buffer - Buffer from which the data is written to the storage.
Returns:
Number of bytes actually written.
Throws:
NullPointerException - Argument is null.
OffsetSizeException - It is not possible to extend the allocated size of this storage.
NotWriteableException - This storage is not open for writing.

getSize

@UInt64
long getSize()

Returns the highest byte position in the storage that has been written so far.

Returns:
Highest byte position in the storage that has been written so far.

isExtendable

@Bool
boolean isExtendable()

Returns true if the memory allocated to the storage can be dynamically extended; otherwise false.

Returns:
Can the memory allocated to the storage be dynamically extended?

getExtent

@UInt64
long getExtent()

Returns the number of bytes currently allocated to the storage.

Returns:
Number of bytes allocated to the storage.

setExtent

void setExtent(@UInt64
               long extent)
               throws OffsetSizeException

Request the given capacity for the storage. If successful, subequent calls to RawStorage.write(byte[]) and writeAt(long, byte[]) within the given capacity are gauranteed to succeed.

Parameters:
extent - Number of bytes capacity requested for the storage.
Throws:
OffsetSizeException - This storage has insufficient capacity to perform the write.

Media Authoring
with Java API

(c) 2007-2008 Richard Cartwright, all rights reserved. Subject to the terms of the AAF SDK Public Source License.