com.prosyst.mbs.services.db
Interface DB

public interface DB

DB interface allows access to a tree database, where each bundle has its own branch. Bundles are prevented from accessing data, located in another branch. Operations over the database are storing and reading of String, Boolean, Integer, Long, Byte, Short, Character, Double, Float objects and all primitive arrays; searching an entity - a node in the tree with or without associated value.

Author:

Svetozar Dimov

Field Summary

static byte	ALL Defines ALL type.
static byte	BOOLEAN Defines Boolean or boolean type.
static byte	BYTE Defines Byte or byte type.
static byte	CHARACTER Defines Character or char type.
static byte	DAMAGED A write error has occured while writing this node FIXME: check usage, eclipse reports that it is not used anywhere
static byte	DOUBLE Defines Double or double type.
static byte	EMPTY Defines no type.
static byte	EXTERN Defines Externalizable value type.
static byte	FLOAT Defines Float or float type.
static byte	INT Defines Integer or int type.
static byte	KEY Defines KEY type.
static byte	LONG Defines Long or long type.
static byte	NODE Defines NODE type.
static byte	SHORT Defines Short or short type.
static byte	STRING Defines String type.

Method Summary

void	delete(java.lang.String[] name) Deletes the node name and all of its descendants from the DB.
double	getDoubleValue(java.lang.String[] name) This method is used to directly read a value of a node that is of type DOUBLE
int	getIntValue(java.lang.String[] name) This method is used to directly read a value of a node that is of type INT
long	getLongValue(java.lang.String[] name) This method is used to directly read a value of a node that is of type LONG
DBNode	getNode(java.lang.String[] name) Retrieves the node implementation.
byte	getType(java.lang.String[] name) Gets the type of the node.
java.lang.Object	getValue(java.lang.String[] name) Gets a value with key name.
int	getValue(java.lang.String[] name, byte[] byteArray, int off, int length) Reads length bytes from the value, associated with the key name and writes them at off position in the byteArray.
void	getValue(java.lang.String[] name, com.prosyst.util.io.Externalizable value) Reads an Externalizable value with key name.
boolean	isArray(java.lang.String[] name) Checks if the value associated with this name is an array or not.
boolean	isPresent(java.lang.String[] name) Checks if the key name is present in the DB.
java.lang.String[]	list(java.lang.String[] name, byte listWhat) Lists the private names of name node's children.
void	lock() Lock the DB and prevents other applications from writing some node information.
void	move(java.lang.String[] name, java.lang.String[] newParent) Moves a subtree starting from name to a new parent - newParent
void	save() Manually instructs the DB implementation to save its current state.
void	setValue(java.lang.String[] name, double value) Saves a double value, to the node with the specified name and automatically sets the node type to DOUBLE
void	setValue(java.lang.String[] name, int value) Saves an integer value, to the node with the specified name and automatically sets the node type to INT
void	setValue(java.lang.String[] name, long value) Saves a long value, to the node with the specified name and automatically sets the node type to LONG
void	setValue(java.lang.String[] name, java.lang.Object val, byte type) Saves the value, associating it with the name.
void	unlock() Unlock the DB and allows other threads to perform write operations.

Field Detail

EMPTY

static final byte EMPTY

Defines no type. Used when storing or getting a node with no value.

See Also:

Constant Field Values

STRING

static final byte STRING

Defines String type. Used when storing or getting a value.

See Also:

Constant Field Values

INT

static final byte INT

Defines Integer or int type. Used when storing or getting a value. When setValue is passed an array this type refers to int[].

See Also:

Constant Field Values

SHORT

static final byte SHORT

Defines Short or short type. Used when storing or getting a value. When setValue is passed an array this type refers to short[].

See Also:

Constant Field Values

LONG

static final byte LONG

Defines Long or long type. Used when storing or getting a value. When setValue is passed an array this type refers to long[].

See Also:

Constant Field Values

BOOLEAN

static final byte BOOLEAN

Defines Boolean or boolean type. Used when storing or getting a value. When setValue is passed an array this type refers to boolean[].

See Also:

Constant Field Values

BYTE

static final byte BYTE

Defines Byte or byte type. Used when storing or getting a value. When setValue is passed an array this type refers to byte[].

See Also:

Constant Field Values

CHARACTER

static final byte CHARACTER

Defines Character or char type. Used when storing or getting a value. When setValue is passed an array this type refers to char[].

See Also:

Constant Field Values

FLOAT

static final byte FLOAT

Defines Float or float type. Used when storing or getting a value. When setValue is passed an array this type refers to float[].

See Also:

Constant Field Values

DOUBLE

static final byte DOUBLE

Defines Double or double type. Used when storing or getting a value. When setValue is passed an array this type refers to double[].

See Also:

Constant Field Values

EXTERN

static final byte EXTERN

Defines Externalizable value type. Used when storing or getting a value.

See Also:

Constant Field Values

DAMAGED

static final byte DAMAGED

A write error has occured while writing this node FIXME: check usage, eclipse reports that it is not used anywhere

See Also:

Constant Field Values

NODE

static final byte NODE

Defines NODE type. Used when listing node names.

See Also:

Constant Field Values

KEY

static final byte KEY

Defines KEY type. Used when listing key names - nodes with value associated.

See Also:

Constant Field Values

ALL

static final byte ALL

Defines ALL type. Used when listing all node names - with or without value.

See Also:

Constant Field Values

Method Detail

setValue

void setValue(java.lang.String[] name,
              java.lang.Object val,
              byte type)
              throws java.io.IOException

Saves the value, associating it with the name. If the value to be saved is Externalizable, it must have implemented its writeObject method, so that DB will be able to call it in order to save its data.

Parameters:

name - key to associate the value with

val - value to save; may be: String, Integer, Long, Boolean, Byte, Short, Character, Double, Float, Externalizable, or the corresponding primitive arrays if available. Note that String[] and Externalizable[] types are not supported.

type - data type, may be: STRING, INT, LONG BOOLEAN, BYTE, SHORT, CHARACTER, DOUBLE, FLOAT, EXTERN or EMPTY

Throws:

java.io.IOException - If an IO error occurs.

java.lang.IllegalArgumentException - If the supplied type is not a valid one

java.lang.SecurityException - if Externalizable object creates ObjectOutputStream that requires SerializablePermission

setValue

void setValue(java.lang.String[] name,
              int value)
              throws java.io.IOException

Saves an integer value, to the node with the specified name and automatically sets the node type to INT

Parameters:

name - key to associate the value with

value - the value of the node

Throws:

java.io.IOException - If an IO error occurs.

Since:

6.2.0

setValue

void setValue(java.lang.String[] name,
              long value)
              throws java.io.IOException

Saves a long value, to the node with the specified name and automatically sets the node type to LONG

Parameters:

name - key to associate the value with

value - the value of the node

Throws:

java.io.IOException - If an IO error occurs.

Since:

6.2.0

setValue

void setValue(java.lang.String[] name,
              double value)
              throws java.io.IOException

Saves a double value, to the node with the specified name and automatically sets the node type to DOUBLE

Parameters:

name - key to associate the value with

value - the value of the node

Throws:

java.io.IOException - If an IO error occurs.

Since:

6.2.0

getValue

java.lang.Object getValue(java.lang.String[] name)
                          throws java.io.IOException

Gets a value with key name.

Parameters:

name - key with with the target value is associated with.

Returns:

The object associated with the key or null if there is no such node, or the node's type EMPTY.

Throws:

java.io.IOException - If an I/O error occurs.

java.lang.IllegalArgumentException - If the node's type is EXTERN

getValue

void getValue(java.lang.String[] name,
              com.prosyst.util.io.Externalizable value)
              throws java.io.IOException,
                     java.lang.IllegalArgumentException

Reads an Externalizable value with key name. To be able to read the data, DB needs an Externalizable object with readValue implemented.

Parameters:

name - key with with the target value is associated with

value - an empty Externalizable instance, whose data will be filled in by the DB, if it has properly implemented its Externalizable.readObject(java.io.InputStream) method.

Throws:

java.io.IOException - If an IO error occurs.

java.lang.IllegalArgumentException - if there is no such node, or the node's type is EMPTY

getValue

int getValue(java.lang.String[] name,
             byte[] byteArray,
             int off,
             int length)
             throws java.io.IOException

Reads length bytes from the value, associated with the key name and writes them at off position in the byteArray.

Parameters:

name - key, with which the target value is associated.

byteArray - where data is read to

off - start position to write in byteArray

length - count of bytes to read

Returns:

number of bytes read, or -1 if the node's type is EMPTY or there is no such node

Throws:

java.io.IOException - If an IO error occurs.

java.lang.IndexOutOfBoundsException - If length is not valid for the supplied byteArray and length

getIntValue

int getIntValue(java.lang.String[] name)
                throws java.io.IOException

This method is used to directly read a value of a node that is of type INT

Parameters:

name - the name of the node

Returns:

the integer value of the node

Throws:

java.io.IOException - on I/O error

java.lang.IllegalArgumentException - if there is no such node, or the node type is not INT

Since:

6.2.0

getLongValue

long getLongValue(java.lang.String[] name)
                  throws java.io.IOException

This method is used to directly read a value of a node that is of type LONG

Parameters:

name - the name of the node

Returns:

the long value of the node

Throws:

java.io.IOException - on I/O error

java.lang.IllegalArgumentException - if there is no such node, or the node type is not LONG

Since:

6.2.0

getDoubleValue

double getDoubleValue(java.lang.String[] name)
                      throws java.io.IOException

This method is used to directly read a value of a node that is of type DOUBLE

Parameters:

name - the name of the node

Returns:

the double value of the node

Throws:

java.io.IOException - on I/O error

java.lang.IllegalArgumentException - if there is no such node, or the node type is not DOUBLE

Since:

6.2.0

isPresent

boolean isPresent(java.lang.String[] name)
                  throws java.io.IOException

Checks if the key name is present in the DB.

Parameters:

name - node to check if present

Returns:

true if present, false otherwise.

Throws:

java.io.IOException - If an IO error occurs.

delete

void delete(java.lang.String[] name)
            throws java.io.IOException

Deletes the node name and all of its descendants from the DB.

Parameters:

name - node to be deleted

Throws:

java.io.IOException - If an IO error occurs.

list

java.lang.String[] list(java.lang.String[] name,
                        byte listWhat)
                        throws java.io.IOException

Lists the private names of name node's children. To get the nodes at the root use an empty String [] for name.

Parameters:

name - node to list children of.

listWhat - filter, may be: NODE, KEY, ALL

Returns:

all children's private names; e.g. if we are looking for {LogService} children then the returned array should be: {ThresholdLevel, Store, FileLength,...}; If the node has no children nodes, or there is no such node, an empty array is returned.

Throws:

java.io.IOException - If an IO error occurs.

getType

byte getType(java.lang.String[] name)
             throws java.io.IOException

Gets the type of the node.

Parameters:

name - key of node.

Returns:

data type, may be: STRING, INT, LONG BOOLEAN, BYTE, SHORT, CHARACTER, DOUBLE, FLOAT, EXTERN or EMPTY

Throws:

java.io.IOException - If such node does not exist, or an IO error occurs.

isArray

boolean isArray(java.lang.String[] name)
                throws java.io.IOException

Checks if the value associated with this name is an array or not.

Parameters:

name - key of node

Returns:

true if the value is a primitive array, otherwise false

Throws:

java.io.IOException - if node does not exist or an IO error occurs.

move

void move(java.lang.String[] name,
          java.lang.String[] newParent)
          throws java.io.IOException

Moves a subtree starting from name to a new parent - newParent

Parameters:

name - The name of the root of the subtree to move

newParent - The name of the node, under which the subtree will be moved

Throws:

java.io.IOException - If the target name node or the newParent node is not present, or if the target name node is the DB root note, or if an IO error occurs.

getNode

DBNode getNode(java.lang.String[] name)
               throws java.io.IOException

Retrieves the node implementation. This an object oriented representation of a node. It can be used to query the node type and value, and to navigate to children nodes and its parent.

Parameters:

name - the node name

Returns:

the object-oriented representation of the node.

Throws:

java.io.IOException - on I/O error

lock

void lock()

Lock the DB and prevents other applications from writing some node information.

unlock

void unlock()

Unlock the DB and allows other threads to perform write operations.

save

void save()
          throws java.io.IOException

Manually instructs the DB implementation to save its current state.

Throws:

java.io.IOException