ej.sp

Class ShieldedPlug

java.lang.Object

ej.sp.ShieldedPlug

public class ShieldedPlug
extends Object

A shielded plug is a database that contains several memory blocks.

A shielded plug can be created at runtime using createDatabase(int) or be created at startup and retrieved by getDatabase(int).

The list of memory blocks IDs can be retrieve using getIDs().
There are two sorts of shielded plugs:

1. The immutable ones (isImmutable()) that cannot be modified.
2. The mutable ones (!isImmutable()) can be modified by adding or removing blocks using create(int, int) or create(int, int, int) or delete(int).

Each block has fixed length (getLength(int) passing the block ID).
All access to a database is serialized by the implementation: there will be only one access (either read or write) at a time. Each access to a block is atomic, this avoids inconsistency:

• It can be read using one of the read methods that match its length.
• It can be written using one the write methods that match its length.

Each memory block has a flag that indicates that an update has occurred since the last read. It is possible to test this state: isPending(int). This flag is set to false when reading, and to true when writing.

A task can wait for the modification of a memory block by using waitFor(int). This method suspends the current task if and only if the method pending returns false on the specified memory block. A task can also wait on several memory blocks, the task is released when one of the blocks is modified waitFor(int[])).

Each memory block has a flag indicating if its data are available or not. It is possible to test this flag using isDataAvailable(int). This flag is initially false and is set to true when writing data. It can be set to false using the method reset(int).

Method Summary

Modifier and Type	Method and Description
void	create(int blockID, int length) Creates a block with the given ID.
void	create(int blockID, int length, int maxTasks) Creates a block with the given ID.
static ShieldedPlug	createDatabase(int ID) Creates a new empty database with the given ID.
void	delete(int blockID) Deletes the block with the given ID.
static ShieldedPlug	getDatabase(int ID) Returns the database defined at the given ID.
int	getID() Gets the ID of this database.
int[]	getIDs() Gets the list of IDs of the blocks available in this database.
int	getLength(int blockID) Returns the length of the block with the given ID.
int	getMaxTasks(int blockID) Gets the maximum number of tasks that can wait at the same time on the block defined with the given ID.
SPReader	getReader(int blockID) Gets the SPReader used to de-serialize objects from the block with the given ID. If no SPReader is defined for the block, null is returned.
int	getSize() Gets the number of blocks of this database.
SPWriter	getWriter(int blockID) Gets the SPWriter used to serialize objects into the block with the given ID. If no SPWriter is defined for the block, null is returned.
boolean	isDataAvailable(int blockID) Determines whether data in the block with the given ID are available or not. By default no data is available in a block.
boolean	isImmutable() Gets if this database is immutable or not.
boolean	isPending(int blockID) Gets if data has been written into the block since last read.
void	read(int blockID, byte[] data) Fills the given array with data from the block with the given ID.
void	read(int blockID, byte[] data, int destOffset) Fills the given array with block.length bytes from the block with the given ID.
double	readDouble(int blockID) Reads eight input bytes from the block with the given ID and returns a double value. The way the double is built from the eight bytes is platform dependent.
float	readFloat(int blockID) Reads four input bytes from the block with the given ID and returns a float value. The way the float is built from the four bytes is platform dependent.
int	readInt(int blockID) Reads four input bytes from the block with the given ID and returns an int value. The way the int is built from the four bytes is platform dependent.
long	readLong(int blockID) Reads eight input bytes from the block with the given ID and returns a long value. The way the long is built from the eight bytes is platform dependent.
Object	readObject(int blockID) Invokes the readObject method of the SPReader registered for the block with the given ID.
void	reset(int blockID) Resets data of the block with the given ID. After execution of this method, isDataAvailable(int) method would return false (unless data were written after calling reset(int) and before calling isDataAvailable(int)).
void	setReader(int blockID, SPReader reader) Registers the given SPReader to de-serialize objects from the block with the given ID. If an SPReader is already defined for the block, it is replaced by the given SPReader.
void	setWriter(int blockID, SPWriter writer) Registers the given SPWriter to serialize objects into the block with the given ID. If an SPWriter is already defined for the block, it is replaced by the given SPWriter.
void	waitFor(int blockID) Causes current thread to wait until another thread write data into the block with the given ID. If data has been written in the block since last read, this method returns immediately.
int[]	waitFor(int[] blockIDs) Causes current thread to wait until another thread write data into at least one block from the blocks with the given IDs. If data has been written in one block since last read from it, this method returns immediately.
void	write(int blockID, byte[] data) Writes block length bytes from the specified byte array to the block with the given ID. The write(blockID, data) method has the same effect as:
void	write(int blockID, byte[] data, int srcOffset) Writes block length bytes from the specified byte array to the block with the given ID. Element data[destOffset] is the first byte written to the block.
void	writeDouble(int blockID, double value) Writes a double value, which is comprised of eight bytes, to the block with the given ID. The way the double is written from the eight bytes is platform dependent.
void	writeFloat(int blockID, float value) Writes a float value, which is comprised of four bytes, to the block with the given ID. The way the float is written from the four bytes is platform dependent.
void	writeInt(int blockID, int value) Writes an int value, which is comprised of four bytes, to the block with the given ID. The way the int is written from the four bytes is platform dependent.
void	writeLong(int blockID, long value) Writes a long value, which is comprised of eight bytes, to the block with the given ID. The way the long is written from the eight bytes is platform dependent.
void	writeObject(int blockID, Object o) Invokes the writeObject method of the SPWriter registered for the block with the given ID.

Methods inherited from class java.lang.Object

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

Method Detail

create

public void create(int blockID,
                   int length)

Creates a block with the given ID. An unlimited number of tasks will be able to wait at the same time for a modification of the block.

Parameters:

blockID - the ID of the block to create

length - the length in bytes of the block to create

Throws:

IllegalArgumentException - if a block is already defined with the given ID

SecurityException - if this database is immutable

create

public void create(int blockID,
                   int length,
                   int maxTasks)

Creates a block with the given ID.

Parameters:

blockID - the ID of the block to create

length - the length in bytes of the block to create

maxTasks - maximum number of tasks that can wait at the same time for a modification of the block

Throws:

IllegalArgumentException - if a block is already defined with the given ID

SecurityException - if this database is immutable

createDatabase

public static ShieldedPlug createDatabase(int ID)

Creates a new empty database with the given ID.

Parameters:

ID - the identification number of the created database

Returns:

the created database

Throws:

IllegalArgumentException - if a database with the given ID already exists

SecurityException - if the platform cannot create dynamically databases

delete

public void delete(int blockID)

Deletes the block with the given ID.

Parameters:

blockID - the ID of the block to delete

Throws:

IllegalArgumentException - if no block is defined with the given ID

SecurityException - if this database is immutable

getDatabase

public static ShieldedPlug getDatabase(int ID)

Returns the database defined at the given ID.

Parameters:

ID - the identification number of the requested database

Returns:

the database with the given ID

Throws:

IllegalArgumentException - if no database is defined with the given ID

getID

public int getID()

Gets the ID of this database.

Returns:

the ID of this database

getIDs

public int[] getIDs()

Gets the list of IDs of the blocks available in this database.

Returns:

the list of the IDs of the blocks available in this database

getLength

public int getLength(int blockID)

Returns the length of the block with the given ID.

Parameters:

blockID - the ID of the block

Returns:

the length in bytes

Throws:

IllegalArgumentException - if no block is defined with the given ID

getMaxTasks

public int getMaxTasks(int blockID)

Gets the maximum number of tasks that can wait at the same time on the block defined with the given ID.

Parameters:

blockID - the ID of the block

Returns:

the maximum number of tasks that can wait at the same time on the block defined with the given ID, or -1 if infinite

Throws:

IllegalArgumentException - if no block is defined with the given ID

getReader

@Nullable
public SPReader getReader(int blockID)

Gets the SPReader used to de-serialize objects from the block with the given ID.
If no SPReader is defined for the block, null is returned.

Parameters:

blockID - the ID of the block

Returns:

the SPReader set or null if none

Throws:

IllegalArgumentException - if no block is defined with the given ID

getSize

public int getSize()

Gets the number of blocks of this database.

Returns:

the number of blocks in this database

getWriter

@Nullable
public SPWriter getWriter(int blockID)

Gets the SPWriter used to serialize objects into the block with the given ID.
If no SPWriter is defined for the block, null is returned.

Parameters:

blockID - the ID of the block

Returns:

the SPWriter set or null if none

Throws:

IllegalArgumentException - if no block is defined with the given ID

isDataAvailable

public boolean isDataAvailable(int blockID)

Determines whether data in the block with the given ID are available or not.
By default no data is available in a block. When data are written in a block, they remain available until method reset(int) is called.

Parameters:

blockID - the ID of the block

Returns:

true if data is available in the block false otherwise

Throws:

IllegalArgumentException - if no block is defined with the given ID

isImmutable

public boolean isImmutable()

Gets if this database is immutable or not.

Returns:

true if no block can be added or remove to this database, false otherwise

isPending

public boolean isPending(int blockID)

Gets if data has been written into the block since last read.

Parameters:

blockID - the ID of the block

Returns:

true if data has been written into the block since last read, false otherwise

Throws:

IllegalArgumentException - if no block is defined with the given ID

read

public void read(int blockID,
                 byte[] data)
          throws EmptyBlockException

Fills the given array with data from the block with the given ID. The number of bytes read is equal to the length of the block.
The read(blockID, data) method has the same effect as:

  read(blockID, data, 0) 
 

Parameters:

blockID - the ID of the block

data - the buffer into which the data is read

Throws:

IllegalArgumentException - if no block is defined with the given ID

EmptyBlockException - if no data is available in the block

IndexOutOfBoundsException - if data.length is lower than block length

read

public void read(int blockID,
                 byte[] data,
                 int destOffset)
          throws EmptyBlockException

Fills the given array with block.length bytes from the block with the given ID. The first byte read is stored into element data[destOffset].

If destOffset is negative or destOffset + block length is greater than the length of the array data, then an IndexOutOfBoundsException is thrown.

Parameters:

blockID - the ID of the block

data - the buffer into which the data is read

destOffset - the start offset in array data at which the data is written

Throws:

IllegalArgumentException - if no block is defined with the given ID

EmptyBlockException - if no data is available in the block

IndexOutOfBoundsException - if destOffset is negative or if data.length is lower than destOffset + block length

readDouble

public double readDouble(int blockID)
                  throws EmptyBlockException

Reads eight input bytes from the block with the given ID and returns a double value.
The way the double is built from the eight bytes is platform dependent.

This method is suitable for reading bytes written by the writeDouble method.

Parameters:

blockID - the ID of the block

Returns:

the double value read

Throws:

IllegalArgumentException - if no block is defined with the given ID

EmptyBlockException - if no data is available in the block

IndexOutOfBoundsException - if block length is not height bytes

readFloat

public float readFloat(int blockID)
                throws EmptyBlockException

Reads four input bytes from the block with the given ID and returns a float value.
The way the float is built from the four bytes is platform dependent.

This method is suitable for reading bytes written by the writeFloat method.

Parameters:

blockID - the ID of the block

Returns:

the float value read

Throws:

IllegalArgumentException - if no block is defined with the given ID

EmptyBlockException - if no data is available in the block

IndexOutOfBoundsException - if block length is not four bytes

readInt

public int readInt(int blockID)
            throws EmptyBlockException

Reads four input bytes from the block with the given ID and returns an int value.
The way the int is built from the four bytes is platform dependent.

This method is suitable for reading bytes written by the writeInt method.

Parameters:

blockID - the ID of the block

Returns:

the int value read

Throws:

IllegalArgumentException - if no block is defined with the given ID

EmptyBlockException - if no data is available in the block

IndexOutOfBoundsException - if block length is not four bytes

readLong

public long readLong(int blockID)
              throws EmptyBlockException

Reads eight input bytes from the block with the given ID and returns a long value.
The way the long is built from the eight bytes is platform dependent.

This method is suitable for reading bytes written by the writeLong method.

Parameters:

blockID - the ID of the block

Returns:

the long value read

Throws:

IllegalArgumentException - if no block is defined with the given ID

EmptyBlockException - if no data is available in the block

IndexOutOfBoundsException - if block length is not height bytes

readObject

public Object readObject(int blockID)
                  throws EmptyBlockException

Invokes the readObject method of the SPReader registered for the block with the given ID.
The SPReader is responsible for the de-serialization of the object from the block.

Parameters:

blockID - the ID of the block

Returns:

the object read from the block

Throws:

IllegalArgumentException - if no block is defined with the given ID

EmptyBlockException - if no data is available in the block

NullPointerException - if no SPReader has been registered for the block

IndexOutOfBoundsException - if block length is lower than the size needed for object de-serialization

reset

public void reset(int blockID)

Resets data of the block with the given ID.
After execution of this method, isDataAvailable(int) method would return false (unless data were written after calling reset(int) and before calling isDataAvailable(int)).

Parameters:

blockID - the ID of the block

Throws:

IllegalArgumentException - if no block is defined with the given ID

setReader

public void setReader(int blockID,
                      SPReader reader)

Registers the given SPReader to de-serialize objects from the block with the given ID.
If an SPReader is already defined for the block, it is replaced by the given SPReader.

Parameters:

blockID - the ID of the block

reader - the SPReader

Throws:

IllegalArgumentException - if no block is defined with the given ID

setWriter

public void setWriter(int blockID,
                      SPWriter writer)

Registers the given SPWriter to serialize objects into the block with the given ID.
If an SPWriter is already defined for the block, it is replaced by the given SPWriter.

Parameters:

blockID - the ID of the block

writer - the SPWriter

Throws:

IllegalArgumentException - if no block is defined with the given ID

waitFor

public void waitFor(int blockID)
             throws InterruptedException

Causes current thread to wait until another thread write data into the block with the given ID.
If data has been written in the block since last read, this method returns immediately.

Parameters:

blockID - the ID of the block

Throws:

InterruptedException - if another thread has interrupted the current thread The interrupted status of the current thread is cleared when this exception is thrown

IllegalArgumentException - if no block is defined with the given ID

TooManyWaitingThreadsException - if too many threads are waiting for new data

waitFor

public int[] waitFor(int[] blockIDs)
              throws InterruptedException

Causes current thread to wait until another thread write data into at least one block from the blocks with the given IDs.
If data has been written in one block since last read from it, this method returns immediately.

Parameters:

blockIDs - the list of block IDs

Returns:

the list of IDs of the blocks that has been written

Throws:

InterruptedException - if another thread has interrupted the current thread The interrupted status of the current thread is cleared when this exception is thrown

IllegalArgumentException - if one of the ID does not correspond to an existing block

TooManyWaitingThreadsException - if too many threads are waiting for new data

write

public void write(int blockID,
                  byte[] data)

Writes block length bytes from the specified byte array to the block with the given ID.
The write(blockID, data) method has the same effect as:

  write(blockID, data, 0) 
 

Parameters:

blockID - the ID of the block

data - the data to write

Throws:

IllegalArgumentException - if no block is defined with the given ID

IndexOutOfBoundsException - if data.length value is lower than block length

write

public void write(int blockID,
                  byte[] data,
                  int srcOffset)

Writes block length bytes from the specified byte array to the block with the given ID.
Element data[destOffset] is the first byte written to the block.

If destOffset is negative, or destOffset + block length is greater than the length of the array data, then an IndexOutOfBoundsException is thrown.

Parameters:

blockID - the ID of the block

data - the data to write

srcOffset - the start offset in the data

Throws:

IllegalArgumentException - if no block is defined with the given ID

IndexOutOfBoundsException - if destOffset is negative or if data.length is lower than offset + block length

writeDouble

public void writeDouble(int blockID,
                        double value)

Writes a double value, which is comprised of eight bytes, to the block with the given ID.
The way the double is written from the eight bytes is platform dependent.

The bytes written by this method may be read by the readDouble method, which will then return a double equal to value.

Parameters:

blockID - ID of the block

value - the double value to be written

Throws:

IllegalArgumentException - if no block is defined with the given ID

IndexOutOfBoundsException - if block length is not eight bytes

writeFloat

public void writeFloat(int blockID,
                       float value)

Writes a float value, which is comprised of four bytes, to the block with the given ID.
The way the float is written from the four bytes is platform dependent.

The bytes written by this method may be read by the readFloat method, which will then return a float equal to value.

Parameters:

blockID - the ID of the block

value - the float value to be written

Throws:

IllegalArgumentException - if no block is defined with the given ID

IndexOutOfBoundsException - if block length is not four bytes

writeInt

public void writeInt(int blockID,
                     int value)

Writes an int value, which is comprised of four bytes, to the block with the given ID.
The way the int is written from the four bytes is platform dependent.

The bytes written by this method may be read by the readInt method, which will then return an int equal to value.

Parameters:

blockID - the ID of the block

value - the int value to be written

Throws:

IllegalArgumentException - if no block is defined with the given ID

IndexOutOfBoundsException - if block length is not four bytes

writeLong

public void writeLong(int blockID,
                      long value)

Writes a long value, which is comprised of eight bytes, to the block with the given ID.
The way the long is written from the eight bytes is platform dependent.

The bytes written by this method may be read by the readLong method, which will then return a long equal to value.

Parameters:

blockID - the ID of the block

value - the long value to be written

Throws:

IllegalArgumentException - if no block is defined with the given ID

IndexOutOfBoundsException - if block length is not eight bytes

writeObject

public void writeObject(int blockID,
                        Object o)

Invokes the writeObject method of the SPWriter registered for the block with the given ID.
The SPWriter is responsible for the serialization of the object into the block.

Parameters:

blockID - the ID of the block

o - the object to be written

Throws:

IllegalArgumentException - if no block is defined with the given ID

NullPointerException - if no SPWriter has been registered for the block

IndexOutOfBoundsException - if block length is lower than the size needed for object serialization