SQLJet Home

org.tmatesoft.sqljet.core.table
Class SqlJetDb

java.lang.Object
  extended by org.tmatesoft.sqljet.core.table.SqlJetDb

public class SqlJetDb
extends java.lang.Object

Connection to database. This class currently is main entry point in SQLJet API.

It allows to perform next tasks:

Author:
TMate Software Ltd., Sergey Scherbina (sergey.scherbina@gmail.com), Dmitry Stadnik (dtrace@seznam.cz)

Field Summary
static java.io.File IN_MEMORY
          File name for in memory database.
 
Constructor Summary
SqlJetDb(java.io.File file, boolean writable)
           Creates connection to database but not open it.
 
Method Summary
 ISqlJetTableDef alterTable(java.lang.String sql)
          Alters table.
 void beginTransaction(SqlJetTransactionMode mode)
          Begin transaction.
 void beginTransaction(org.tmatesoft.sqljet.core.internal.SqlJetTransactionMode mode)
          Deprecated. use {beginTransaction(SqlJetTransactionMode) instead.
 void close()
          Close connection to database.
 void commit()
          Commit transaction.
 ISqlJetIndexDef createIndex(java.lang.String sql)
          Create index from SQL clause.
 ISqlJetTableDef createTable(java.lang.String sql)
          Create table from SQL clause.
 ISqlJetVirtualTableDef createVirtualTable(java.lang.String sql)
          Create virtual table from SQL clause.
 void dropIndex(java.lang.String indexName)
          Drop index.
 void dropTable(java.lang.String tableName)
          Drop table.
protected  void finalize()
           
 ISqlJetBusyHandler getBusyHandler()
          Get busy handler.
 int getCacheSize()
          Get cache size (in count of pages).
 java.io.File getFile()
           
 ISqlJetMutex getMutex()
          Get threading synchronization mutex.
 ISqlJetOptions getOptions()
          Get database options.
 ISqlJetSchema getSchema()
          Get database schema.
 ISqlJetTable getTable(java.lang.String tableName)
          Open table.
 SqlJetTransactionMode getTransactionMode()
           
 boolean isInTransaction()
          Return true if a transaction is active.
 boolean isOpen()
          Checks is database open.
 boolean isWritable()
          Check write access to data base.
 void open()
           Opens connection to database.
static SqlJetDb open(java.io.File file, boolean write)
           Opens connection to data base.
 java.lang.Object pragma(java.lang.String sql)
          Executes pragma statement.
 void refreshSchema()
          Refresh database schema.
 void rollback()
          Rollback transaction.
 java.lang.Object runReadTransaction(ISqlJetTransaction op)
          Run read-only transaction.
 java.lang.Object runTransaction(ISqlJetTransaction op, SqlJetTransactionMode mode)
          Run transaction.
 java.lang.Object runTransaction(ISqlJetTransaction op, org.tmatesoft.sqljet.core.internal.SqlJetTransactionMode mode)
          Deprecated. use runTransaction(ISqlJetTransaction, SqlJetTransactionMode)
 java.lang.Object runWithLock(ISqlJetRunnableWithLock op)
          Do some actions with locking database's internal threads synchronization mutex.
 java.lang.Object runWriteTransaction(ISqlJetTransaction op)
          Run modifications in write transaction.
 void setBusyHandler(ISqlJetBusyHandler busyHandler)
          Set busy handler.
 void setCacheSize(int cacheSize)
          Set cache size (in count of pages).
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

IN_MEMORY

public static final java.io.File IN_MEMORY
File name for in memory database.

Constructor Detail

SqlJetDb

public SqlJetDb(java.io.File file,
                boolean writable)

Creates connection to database but not open it. Doesn't open database file until not called method open().

File could be null or have special value IN_MEMORY. If file is null then will be created temporary file which will be deleted at close. If file is IN_MEMORY then file doesn't created and instead database will placed in memory. If regular file is specified but doesn't exist then it will be tried to created.

Parameters:
file - path to data base. Could be null or IN_MEMORY.
writable - if true then will allow data modification.
Method Detail

open

public void open()
          throws SqlJetException

Opens connection to database. It does not create any locking on database. First lock will be created when be called any method which requires real access to options or schema.

Throws:
SqlJetException - if any trouble with access to file or database format.

open

public static SqlJetDb open(java.io.File file,
                            boolean write)
                     throws SqlJetException

Opens connection to data base. It does not create any locking on database. First lock will be created when be called any method which requires real access to options or schema.

File could be null or have special value IN_MEMORY. If file is null then will be created temporary file which will be deleted at close. If file is IN_MEMORY then file doesn't created and instead database will placed in memory. If regular file is specified but doesn't exist then it will be tried to created.

Parameters:
file - path to data base. Could be null or IN_MEMORY.
write - open for writing if true.
Throws:
SqlJetException - if any trouble with access to file or database format.

isOpen

public boolean isOpen()
Checks is database open.

Returns:
true if database is open.

close

public void close()
           throws SqlJetException
Close connection to database. It is safe to call this method if database connections is closed already.

Throws:
SqlJetException - it is possible to get exception if there is actvie transaction and rollback did not success.

finalize

protected void finalize()
                 throws java.lang.Throwable
Overrides:
finalize in class java.lang.Object
Throws:
java.lang.Throwable

setCacheSize

public void setCacheSize(int cacheSize)
                  throws SqlJetException
Set cache size (in count of pages).

Parameters:
cacheSize - the count of pages which can hold cache.
Throws:
SqlJetException

getCacheSize

public int getCacheSize()
                 throws SqlJetException
Get cache size (in count of pages).

Returns:
the count of pages which can hold cache.
Throws:
SqlJetException

runWithLock

public java.lang.Object runWithLock(ISqlJetRunnableWithLock op)
                             throws SqlJetException
Do some actions with locking database's internal threads synchronization mutex. It is related only with synchronization of access to one connection from multiple threads. It is not related with transactions and locks of database file. For concurrent access to database from threads or processes use transactions.

Parameters:
op - operation to run
Returns:
result of the ISqlJetRunnableWithLock.runWithLock(SqlJetDb) call.
Throws:
SqlJetException - in case operation fails to run.

getFile

public java.io.File getFile()

isWritable

public boolean isWritable()
                   throws SqlJetException
Check write access to data base.

Returns:
true if modification is allowed
Throws:
SqlJetException

getSchema

public ISqlJetSchema getSchema()
                        throws SqlJetException
Get database schema.

Returns:
database schema.
Throws:
SqlJetException

getTable

public ISqlJetTable getTable(java.lang.String tableName)
                      throws SqlJetException
Open table.

Parameters:
tableName - name of the table to open.
Returns:
opened table
Throws:
SqlJetException

runWriteTransaction

public java.lang.Object runWriteTransaction(ISqlJetTransaction op)
                                     throws SqlJetException
Run modifications in write transaction.

Parameters:
op - transaction to run.
Returns:
result of the ISqlJetTransaction.run(SqlJetDb) call.
Throws:
SqlJetException

runReadTransaction

public java.lang.Object runReadTransaction(ISqlJetTransaction op)
                                    throws SqlJetException
Run read-only transaction.

Parameters:
op - transaction to run.
Returns:
result of the ISqlJetTransaction.run(SqlJetDb) call.
Throws:
SqlJetException

runTransaction

public java.lang.Object runTransaction(ISqlJetTransaction op,
                                       SqlJetTransactionMode mode)
                                throws SqlJetException
Run transaction.

Parameters:
op - transaction's body (closure).
mode - transaction's mode.
Returns:
result of the ISqlJetTransaction.run(SqlJetDb) call.
Throws:
SqlJetException

runTransaction

public java.lang.Object runTransaction(ISqlJetTransaction op,
                                       org.tmatesoft.sqljet.core.internal.SqlJetTransactionMode mode)
                                throws SqlJetException
Deprecated. use runTransaction(ISqlJetTransaction, SqlJetTransactionMode)

Throws:
SqlJetException

beginTransaction

public void beginTransaction(SqlJetTransactionMode mode)
                      throws SqlJetException
Begin transaction.

Parameters:
mode - transaction's mode.
Throws:
SqlJetException

beginTransaction

public void beginTransaction(org.tmatesoft.sqljet.core.internal.SqlJetTransactionMode mode)
                      throws SqlJetException
Deprecated. use {beginTransaction(SqlJetTransactionMode) instead.

Throws:
SqlJetException

commit

public void commit()
            throws SqlJetException
Commit transaction.

Throws:
SqlJetException

rollback

public void rollback()
              throws SqlJetException
Rollback transaction.

Throws:
SqlJetException

getOptions

public ISqlJetOptions getOptions()
                          throws SqlJetException
Get database options.

Returns:
options of this database
Throws:
SqlJetException

pragma

public java.lang.Object pragma(java.lang.String sql)
                        throws SqlJetException
Executes pragma statement. If statement queries pragma value then pragma value will be returned.

Throws:
SqlJetException

createTable

public ISqlJetTableDef createTable(java.lang.String sql)
                            throws SqlJetException
Create table from SQL clause.

Parameters:
sql - CREATE TABLE ... sentence.
Returns:
definition of create table.
Throws:
SqlJetException

createIndex

public ISqlJetIndexDef createIndex(java.lang.String sql)
                            throws SqlJetException
Create index from SQL clause.

Parameters:
sql - CREATE INDEX ... sentence.
Returns:
definition of created index.
Throws:
SqlJetException

dropTable

public void dropTable(java.lang.String tableName)
               throws SqlJetException
Drop table.

Parameters:
tableName - name of table to drop.
Throws:
SqlJetException

dropIndex

public void dropIndex(java.lang.String indexName)
               throws SqlJetException
Drop index.

Parameters:
indexName - name of the index to drop.
Throws:
SqlJetException

alterTable

public ISqlJetTableDef alterTable(java.lang.String sql)
                           throws SqlJetException
Alters table.

Parameters:
sql - ALTER TABLE ... sentence.
Returns:
altered table schema definition.
Throws:
SqlJetException

createVirtualTable

public ISqlJetVirtualTableDef createVirtualTable(java.lang.String sql)
                                          throws SqlJetException
Create virtual table from SQL clause.

Parameters:
sql - CREATE VIRTUAL TABLE ... sentence.
Returns:
definition of create virtual table.
Throws:
SqlJetException

getBusyHandler

public ISqlJetBusyHandler getBusyHandler()
Get busy handler.

Returns:
the busy handler.

setBusyHandler

public void setBusyHandler(ISqlJetBusyHandler busyHandler)
Set busy handler. Busy handler treats situation when database is locked by other process or thread.

Parameters:
busyHandler - the busy handler.

refreshSchema

public void refreshSchema()
                   throws SqlJetException
Refresh database schema.

Throws:
SqlJetException

isInTransaction

public boolean isInTransaction()
Return true if a transaction is active.

Returns:
true if there is active running transaction in this database now.

getTransactionMode

public SqlJetTransactionMode getTransactionMode()

getMutex

public ISqlJetMutex getMutex()
Get threading synchronization mutex.

Returns:
Mutex semaphore instance used to synchronize access to this database from multiple threads.

SQLJet Home

Copyright © 2009-2010 TMate Software Ltd. All Rights Reserved.