Maatri 0.4 (Build 905)
Embeddable Database Engine

com.bittecsystems.maatri
Class Maatri

java.lang.Object
  extended by com.bittecsystems.maatri.Maatri

public class Maatri
extends java.lang.Object

Maatri class provides embeddable database engine context. Maatri class is implemented as a singleton. Primary application access static methods in this class. Maatri is thread-safe, hence primary application may access Maatri via multiple threads.


Field Summary
static java.lang.String AUTO_REORGANIZE
          Maatri instance property.
static int DUPLICATE_OBJECT
          Maatri Exception Type, raised when search finds a duplicate persisted object.
static java.lang.String EXCEPTION_LEVEL
          Maatri instance property.
static int FETCH_NEXT
          Maatri parameter passed to return the next object in query result.
static int FETCH_PREV
          Maatri parameter passed to return the previous object in query result.
static int ILLEGAL_STATE
          Maatri Exception Type, raised when data manipulation functions are called via Iterator based indexed access without making a prior call to next() or previous().
static int OBJECT_NOT_FOUND
          Maatri Exception Type, raised when search fails to find a persisted object.
static java.lang.String SYSTEM_OUT_ENABLE
          Maatri instance property.
static java.lang.String USERHOME
          Maatri helper property, declares the User's Home Directory.
 
Constructor Summary
protected Maatri()
           Constructor Maatri can be called from openConnection method only.
 
Method Summary
 java.lang.Object clone()
          Blocks cloning of Maatri object.
static void closeConnection(int con)
           Closes the connection specified by the con parameter.
static java.lang.Object fetch(int con, int dir, int qid)
          Return the next / previous object in query result.
static int get(int con, java.lang.Class classObj, java.lang.String where)
          Return a Query Id for the passed query string.
static int openConnection(java.lang.String path)
          Opens a connection to the database file in the location specified by the path parameter.
static void set(int con, java.lang.Object obj)
          Data manipulation function for inserting persistable object to the database.
static void set(int con, java.lang.Object objOri, java.lang.Object objNew)
           Data manipulation function providing one interface to either replace existing object or removing it from the database.
static void setProperty(int con, java.lang.String key, java.lang.String val)
          Customize the Maatri instance by setting properties.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SYSTEM_OUT_ENABLE

public static final java.lang.String SYSTEM_OUT_ENABLE
Maatri instance property. Control System.out on console.

Valid values:
"true" - Enable System.out on console.
"false" - Block System.out on console.

See Also:
Constant Field Values

EXCEPTION_LEVEL

public static final java.lang.String EXCEPTION_LEVEL
Maatri instance property. Control stack trace message logging.

Valid values:
"1" - Block all Stack trace messages.
"2" - Block Stack trace messages for MaatriException's of the types: OBJECT_NOT_FOUND, DUPLICATE_OBJECT and OBJECT_LOCKED.
"3" - Log all Stack trace messages.

See Also:
Constant Field Values

AUTO_REORGANIZE

public static final java.lang.String AUTO_REORGANIZE
Maatri instance property. Control database reorganization activity. Depending upon the value of the property, during database engine shutdown or startuup, it is determined if database needs reorganization. If so, then the database is reorganized.

Reorganization recovers blocked space from the database file that may have been generated due to removal or replacement of persistable objects.

Valid values:
"0" - Reorganization on shutdown.
"1" - Reorganization on startup. [Currently disabled]
" " - Reorganization is disabled.

See Also:
Constant Field Values

FETCH_NEXT

public static final int FETCH_NEXT
Maatri parameter passed to return the next object in query result.

See Also:
fetch, Constant Field Values

FETCH_PREV

public static final int FETCH_PREV
Maatri parameter passed to return the previous object in query result.

See Also:
fetch, Constant Field Values

OBJECT_NOT_FOUND

public static final int OBJECT_NOT_FOUND
Maatri Exception Type, raised when search fails to find a persisted object. Persisted objects are searched via indexes created in the memory based on their Primary Ids.

See Also:
Constant Field Values

DUPLICATE_OBJECT

public static final int DUPLICATE_OBJECT
Maatri Exception Type, raised when search finds a duplicate persisted object. Persisted objects are stated to be duplicates if their Primary Ids match.

See Also:
Constant Field Values

ILLEGAL_STATE

public static final int ILLEGAL_STATE
Maatri Exception Type, raised when data manipulation functions are called via Iterator based indexed access without making a prior call to next() or previous().

See Also:
Constant Field Values

USERHOME

public static java.lang.String USERHOME
Maatri helper property, declares the User's Home Directory.

Constructor Detail

Maatri

protected Maatri()
          throws MaatriException

Constructor Maatri can be called from openConnection method only. This implements the singleton design pattern. The constructor initializes database properties, starts logging services and announces start of database engine in the log file. The log file is named 'Maatri.log'. Log file is created in the path where database is created, pointed to by path parameter in openConnection method under the \log directory. It reports messages on database operations.

Maatri property EXCEPTION_LEVEL controls how much information is logged.
Maatri property SYSTEM_OUT_ENABLE controls if logged messages are sent to System.out also.

Throws:
MaatriException
See Also:
openConnection, SYSTEM_OUT_ENABLE, EXCEPTION_LEVEL
Method Detail

openConnection

public static int openConnection(java.lang.String path)
                          throws MaatriException
Opens a connection to the database file in the location specified by the path parameter.

This method delegates loading of the database. The delegated method searches for any open connections with the same path parameter. If a connection exists, the same connection id is returned. If the connection is not found then the database file (Maatri.db) is searched in the path location. If the file doesnot exist at the location, it is created. Once the database file is reached, it is opened, validated and database structures are loaded in memory.

Parameter path can be set to null. Maatri then creates the database file at the location specified by System.getProperty("user.home").

The function is thread-safe, hence multiple threads, from the primary application, can access this function and operate on a single database file or multiple database files located at different locations.

Returns a connection id.
Code example:
      try {
         connectID = Maatri.openConnection("C:\mydb");
         Maatri.setProperty(connectID,Maatri.SYSTEM_OUT_ENABLE,"false");
         Maatri.setProperty(connectID,Maatri.EXCEPTION_LEVEL,"2");
      } catch ... 

Parameters:
path - Path of the database file
Returns:
Connection Id
Throws:
MaatriException
See Also:
closeConnection

closeConnection

public static void closeConnection(int con)
                            throws MaatriException

Closes the connection specified by the con parameter. Closing connection does not necessarily shutdown the Maatri database engine. The database engine shutdown is attempted only if it is determined that there are no live connection(s) existing with the database file, even if existing connection(s) are from different threads. If live connection(s) are determined then this method removes the connection id, specified in con parameter, from the connection list and returns.

During shutdown, depending upon the setting of AUTO_REORGANIZE property, reorganization of the database may also be attempted.
Code example:
         try {
             Maatri.closeConnection(connectID);
         } catch ... 
The function is thread-safe.

Parameters:
con - Connection Id
Throws:
MaatriException
See Also:
openConnection, AUTO_REORGANIZE

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException
Blocks cloning of Maatri object.

Overrides:
clone in class java.lang.Object
Throws:
java.lang.CloneNotSupportedException

setProperty

public static void setProperty(int con,
                               java.lang.String key,
                               java.lang.String val)
Customize the Maatri instance by setting properties.
Code example:
    try {
       connectID = Maatri.openConnection(path);
       Maatri.setProperty(connectID,Maatri.SYSTEM_OUT_ENABLE,"false"); //stop System.out
       Maatri.setProperty(connectID,Maatri.EXCEPTION_LEVEL,"3"); //log everything
    } catch (MaatriException mex) {
       if (mex.getLevel()==MaatriException.CRITICAL_FAILURE) {
          throw mex;
       }//if
    }//try

Parameters:
con - Connection Id
key - Maatri Property
val - Value
See Also:
SYSTEM_OUT_ENABLE, EXCEPTION_LEVEL

set

public static void set(int con,
                       java.lang.Object obj)
                throws MaatriException
Data manipulation function for inserting persistable object to the database.
Code example:
            dataObject dataObj  = new dataObject();
            try {
               Maatri.set( connectID, dataObj );
            } catch ...

Parameters:
con - Connection Id
obj - Persistable object to be inserted in the database.
Throws:
MaatriException

set

public static void set(int con,
                       java.lang.Object objOri,
                       java.lang.Object objNew)
                throws MaatriException

Data manipulation function providing one interface to either replace existing object or removing it from the database. In case objNew is set to null, objOri is removed, else objOri is replaced with objNew.

Code example: Replace persistable object
            dataObject dataObj = new dataObject();
            dataObject newDataObj = new dataObject();
            try {
               Maatri.set( connectID, dataObj, newDataObj );
            } catch ...
Code example: Remove persistable object
            try {
               Maatri.set( connectID, dataObj, null);
            } catch ...

Parameters:
con - Connection Id
objOri - Persistable object, that needs to be replaced with objNew.
objNew - Persistable object, replacing objOri. To delete objOri from the database, set this to null.
Throws:
MaatriException

get

public static int get(int con,
                      java.lang.Class classObj,
                      java.lang.String where)
               throws MaatriException
Return a Query Id for the passed query string.
Code example:
      //search dataObject where dataObject.ID is between 11 and 13 and dataObject.Desc contains 'E'
      int queryID = Maatri.get(connectID, dataObject.class, "ID>='11' and ID<='13' and Desc='*E*'");
      if ( queryID > Maatri.OBJECT_NOT_FOUND ) {
          Object obj = null;
          try {
             if ( (obj = Maatri.fetch( connectID, Maatri.FETCH_NEXT, queryID )) != null ) {
                System.out.println( obj.toString() );
             }//if
          } catch ...
      }//if 

Parameters:
con - Connection Id
classObj - Class of the persistable Object.
where - "where" clause. Predicates expressed in SQL "where" clause like expressions.
Returns:
Query Id
Throws:
MaatriException
See Also:
fetch

fetch

public static java.lang.Object fetch(int con,
                                     int dir,
                                     int qid)
                              throws MaatriException
Return the next / previous object in query result.
Code example:
      try {
         while ( (obj = Maatri.fetch( connectID, Maatri.FETCH_NEXT, queryID )) != null ) {
           System.out.println( obj.toString() );
         }//while !null
      } catch (MaatriException mex) {
         if (mex.getExceptionType()==MaatriException.CRITICAL_FAILURE) {
            throw mex;
         }//if
      }//try 

Parameters:
con - Connection Id
dir - Maatri Property
qid - Query Id
Returns:
Object persisted in Maatri Embeddable Database
Throws:
MaatriException
See Also:
FETCH_NEXT, FETCH_PREV

Maatri 0.4 (Build 905)
Embeddable Database Engine

Copyright © 2008-2013 BitTec Systems. All Rights Reserved.