|
Maatri 0.4 (Build 905) Embeddable Database Engine |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.bittecsystems.maatri.Maatri
public class Maatri
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 |
---|
public static final java.lang.String SYSTEM_OUT_ENABLE
Maatri
instance property. Control System.out
on console.
"true"
- Enable System.out
on console."false"
- Block System.out
on console.
public static final java.lang.String EXCEPTION_LEVEL
Maatri
instance property. Control stack trace message logging.
"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.
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.
"0"
- Reorganization on shutdown."1"
- Reorganization on startup. [Currently disabled]" "
- Reorganization is disabled.
public static final int FETCH_NEXT
Maatri
parameter passed to return the next object in query result.
fetch
,
Constant Field Valuespublic static final int FETCH_PREV
Maatri
parameter passed to return the previous object in query result.
fetch
,
Constant Field Valuespublic 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.
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.
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()
.
public static java.lang.String USERHOME
Maatri
helper property, declares the User's Home Directory.
Constructor Detail |
---|
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.
MaatriException
openConnection
,
SYSTEM_OUT_ENABLE
,
EXCEPTION_LEVEL
Method Detail |
---|
public static int openConnection(java.lang.String path) throws MaatriException
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.
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.try { connectID = Maatri.openConnection("C:\mydb"); Maatri.setProperty(connectID,Maatri.SYSTEM_OUT_ENABLE,"false"); Maatri.setProperty(connectID,Maatri.EXCEPTION_LEVEL,"2"); } catch ...
path
- Path of the database file
MaatriException
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.
AUTO_REORGANIZE
property, reorganization of the database may also be attempted.
try { Maatri.closeConnection(connectID); } catch ...
con
- Connection Id
MaatriException
openConnection
,
AUTO_REORGANIZE
public java.lang.Object clone() throws java.lang.CloneNotSupportedException
Maatri
object.
clone
in class java.lang.Object
java.lang.CloneNotSupportedException
public static void setProperty(int con, java.lang.String key, java.lang.String val)
Maatri
instance by setting properties.
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
con
- Connection Idkey
- Maatri Propertyval
- ValueSYSTEM_OUT_ENABLE
,
EXCEPTION_LEVEL
public static void set(int con, java.lang.Object obj) throws MaatriException
dataObject dataObj = new dataObject(); try { Maatri.set( connectID, dataObj ); } catch ...
con
- Connection Idobj
- Persistable object to be inserted in the database.
MaatriException
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
.
dataObject dataObj = new dataObject(); dataObject newDataObj = new dataObject(); try { Maatri.set( connectID, dataObj, newDataObj ); } catch ...
try { Maatri.set( connectID, dataObj, null); } catch ...
con
- Connection IdobjOri
- Persistable object, that needs to be replaced with objNew
.objNew
- Persistable object, replacing objOri
. To delete objOri
from the database, set this to null
.
MaatriException
public static int get(int con, java.lang.Class classObj, java.lang.String where) throws MaatriException
//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
con
- Connection IdclassObj
- Class of the persistable Object.where
- "where" clause. Predicates expressed in SQL "where" clause like expressions.
MaatriException
fetch
public static java.lang.Object fetch(int con, int dir, int qid) throws MaatriException
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
con
- Connection Iddir
- Maatri Propertyqid
- Query Id
MaatriException
FETCH_NEXT
,
FETCH_PREV
|
Maatri 0.4 (Build 905) Embeddable Database Engine |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |