ch.javasoft.jbase
Class FixedWidthTable<E>

java.lang.Object
  ch.javasoft.jbase.FixedWidthTable<E>

All Implemented Interfaces:

Stateful, Table<E>

public class FixedWidthTable<E>
extends Object
implements Table<E>, Stateful

The FixedWidthTable stores entities of known, fixed size.

To store the data, a RandomAccessPersister is used, usually operating on a RandomAccessFile. If files are used for storage, a single file is created. Since entities have fixed width. offsets to any entity can be computed easily.

Note that fixed width tables are not thread safe. However, a thread safe table for concurrent use is possible by using this table together with ConcurrentTable.

Constructor Summary

protected

FixedWidthTable(RandomAccessPersister raPersister, FixedWidthMarshaller<E> marshaller, int size) Constructor for internal use and subclasses only, called from open(..) and create(..) methods.

Method Summary

int	add(E entity) Adds a new entity to the table.
protected long	byteOffset()
protected long	byteOffset(int index)
protected long	byteSizeData()
protected long	byteSizeTotal()
void	close(boolean erase) Closes this table.
static <En> FixedWidthTable<En>	create(File file, FixedWidthMarshaller<En> marshaller) Creates the given table for read and write, using no cache
static <En> FixedWidthTable<En>	create(File file, FixedWidthMarshaller<En> marshaller, int cacheTableSize, int cacheEntrySize) Creates the given table for read and write, using caching
static <En> FixedWidthTable<En>	create(RandomAccessPersister raPersister, FixedWidthMarshaller<En> marshaller) Creates the given table for read and write using the specified persister.
FixedWidthTable<E>	createReadCopy(ReadWriteLock lock) Returns a read copy of this stateful object.
protected void	finalize() Calls close(boolean) with false argument, i.e.
void	flush() Flush ensures that all write operations are persisted.
E	get(int index) Returns the entity at the given position.
int	getByteWidth()
FixedWidthMarshaller<E>	getEntityMarshaller()
static <En> FixedWidthTable<En>	open(File file, FixedWidthMarshaller<En> marshaller) Open the given table for read-only access, using no cache
static <En> FixedWidthTable<En>	open(File file, FixedWidthMarshaller<En> marshaller, int cacheTableSize, int cacheEntrySize) Open the given table for read-only access, using caching
static <En> FixedWidthTable<En>	open(RandomAccessPersister raPersister, FixedWidthMarshaller<En> marshaller) Open the given table for read and write, depending on the specified persister.
static int	readByteWidth(RandomAccessPersister raPersister) Reads the table byte width from file using the given persister.
protected void	readHeader()
static int	readSize(RandomAccessPersister raPersister) Reads the table size, that is, the number of entries, from file using the given persister.
void	remove(int index) Removes the entity at the given position from the table.
void	removeAll() Closes this table.
void	set(int index, E entity) Replaces the entity at the given position by the specified entity.
int	size() Returns the size of the table, i.e.
void	swap(int indexA, int indexB) Swaps the two entities specified by their index.
protected void	writeHeader()

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FixedWidthTable

protected FixedWidthTable(RandomAccessPersister raPersister,
                          FixedWidthMarshaller<E> marshaller,
                          int size)

Constructor for internal use and subclasses only, called from open(..) and create(..) methods.

Parameters:

raPersister - the persister to use

marshaller - the marshaller

size - the number of table entries

Method Detail

readByteWidth

public static int readByteWidth(RandomAccessPersister raPersister)
                         throws IOException

Reads the table byte width from file using the given persister. The byte with is saved at position 0L in the file.

Throws:

IOException

readSize

public static int readSize(RandomAccessPersister raPersister)
                    throws IOException

Reads the table size, that is, the number of entries, from file using the given persister. The table size is saved at position 4L in the file.

Throws:

IOException

open

public static <En> FixedWidthTable<En> open(File file,
                                            FixedWidthMarshaller<En> marshaller)
                                throws IOException

Open the given table for read-only access, using no cache

Type Parameters:

En - the entry type

Parameters:

file - the table file to open

marshaller - the marshaller

Returns:

the table without cache for reading only

Throws:

IOException - if an i/o exception occurs

open

public static <En> FixedWidthTable<En> open(File file,
                                            FixedWidthMarshaller<En> marshaller,
                                            int cacheTableSize,
                                            int cacheEntrySize)
                                throws IOException

Open the given table for read-only access, using caching

Type Parameters:

En - the entry type

Parameters:

file - the table file to open

marshaller - the marshaller

cacheTableSize - Table size for BufferedRandomAccessPersister, or 0 if no cache should be used

cacheEntrySize - Table entry size for BufferedRandomAccessPersister, or 0 if no cache should be used

Returns:

the table for reading only

Throws:

IOException - if an i/o exception occurs

open

public static <En> FixedWidthTable<En> open(RandomAccessPersister raPersister,
                                            FixedWidthMarshaller<En> marshaller)
                                throws IOException

Open the given table for read and write, depending on the specified persister.

Type Parameters:

En - the entry type

Parameters:

raPersister - the persister for file access

marshaller - the marshaller

Returns:

the table

Throws:

IOException - if an i/o exception occurs

create

public static <En> FixedWidthTable<En> create(File file,
                                              FixedWidthMarshaller<En> marshaller)
                                  throws IOException

Creates the given table for read and write, using no cache

Type Parameters:

En - the entry type

Parameters:

file - the table file to create

marshaller - the marshaller

Returns:

the table

Throws:

IOException - if an i/o exception occurs

create

public static <En> FixedWidthTable<En> create(File file,
                                              FixedWidthMarshaller<En> marshaller,
                                              int cacheTableSize,
                                              int cacheEntrySize)
                                  throws IOException

Creates the given table for read and write, using caching

Type Parameters:

En - the entry type

Parameters:

file - the table file to create

marshaller - the marshaller

cacheTableSize - Table size for BufferedRandomAccessPersister, or 0 if no cache should be used

cacheEntrySize - Table entry size for BufferedRandomAccessPersister, or 0 if no cache should be used

Returns:

the table

Throws:

IOException - if an i/o exception occurs

create

public static <En> FixedWidthTable<En> create(RandomAccessPersister raPersister,
                                              FixedWidthMarshaller<En> marshaller)
                                  throws IOException

Creates the given table for read and write using the specified persister.

Type Parameters:

En - the entry type

Parameters:

raPersister - the persister for file access

marshaller - the marshaller

Returns:

the table

Throws:

IOException - if an i/o exception occurs

readHeader

protected void readHeader()
                   throws IOException

Throws:

IOException

writeHeader

protected void writeHeader()
                    throws IOException

Throws:

IOException

getByteWidth

public int getByteWidth()

getEntityMarshaller

public FixedWidthMarshaller<E> getEntityMarshaller()

add

public int add(E entity)
        throws IOException

Description copied from interface: Table

Adds a new entity to the table. The index of the added entity is at end of table, i.e. size-1 after adding the new entity.

Specified by:

add in interface Table<E>

Returns:

the position of the added entity, i.e. size-1

Throws:

IOException

get

public E get(int index)
      throws IOException

Description copied from interface: Table

Returns the entity at the given position. Note that (row) indices might change if entities are added or removed.

Specified by:

get in interface Table<E>

Throws:

IOException

remove

public void remove(int index)
            throws IOException

Description copied from interface: Table

Removes the entity at the given position from the table. If this was the last entity, it is just removed. If it is another (not the last) row, the entity at the last row is moved to the specified position of the entity to remove.

Specified by:

remove in interface Table<E>

Throws:

IOException

set

public void set(int index,
                E entity)
         throws IOException

Description copied from interface: Table

Replaces the entity at the given position by the specified entity.

Specified by:

set in interface Table<E>

Throws:

IOException

swap

public void swap(int indexA,
                 int indexB)
          throws IOException

Description copied from interface: Table

Swaps the two entities specified by their index.

Specified by:

swap in interface Table<E>

Throws:

IOException

removeAll

public void removeAll()
               throws IOException

Description copied from interface: Table

Closes this table. Pending write operations are flushed, and underlying files are closed. Subsequent access to the table is not allowed and causes exceptions. Multiple calls to this close method do not cause any exceptions.

Specified by:

removeAll in interface Table<E>

Throws:

IOException

size

public int size()
         throws IOException

Description copied from interface: Table

Returns the size of the table, i.e. the number of rows or entities.

Specified by:

size in interface Table<E>

Throws:

IOException

flush

public void flush()
           throws IOException

Description copied from interface: Table

Flush ensures that all write operations are persisted. Writing to files ore databases might involve caches (operating system caches or application caches). Calling this method enforces that all cached data is written to the underlying layer(s).

Specified by:

flush in interface Table<E>

Throws:

IOException

close

public void close(boolean erase)
           throws IOException

Description copied from interface: Table

Closes this table. Pending write operations are flushed, and underlying files are closed. Subsequent access to the table is not allowed and causes exceptions. Multiple calls to this close method do not cause any exceptions.

Specified by:

close in interface Table<E>

Throws:

IOException

createReadCopy

public FixedWidthTable<E> createReadCopy(ReadWriteLock lock)
                                  throws IOException

Description copied from interface: Stateful

Returns a read copy of this stateful object. The returned read copy contains its own state compared to another read copy instance, i.e. read copies can be used by different threads without causing conflicts considering the state of the stateful object.

The submitted read/write lock can be used later on e.g. for lazy opening of additional files. When this method is invoked, the write lock of the submitted read/write lock is held.

Specified by:

createReadCopy in interface Stateful

Parameters:

lock - A read/write lock, the write lock is held. The lock, however, might also be used for other functionality of the returned read copy, for instance, if the read copy has to be put in sync with the main object.

Returns:

a new read copy instance, with copied state compared to other read copy instances

Throws:

IOException

finalize

protected void finalize()
                 throws Throwable

Calls close(boolean) with false argument, i.e. without erasing

Overrides:

finalize in class Object

Throws:

Throwable

byteOffset

protected long byteOffset()

byteOffset

protected long byteOffset(int index)

byteSizeTotal

protected long byteSizeTotal()

byteSizeData

protected long byteSizeData()