ToC path:

The Java Connection Class

Connection provides the interface for all threads interacting with a Database object.

For an overview see page Java Classes

Class Definition

    public class Connection implements java.io.Closeable
    {
        /* Constructors */
        public Connection(Database db) 
        {
            this.db = db;
            id = connect(db.name, null);
        }
        public Connection(Database db, byte[] context) 
        {
            this.db = db;
            id = connect(db.name, context);
        }
        protected Connection(Connection con) {
            db = con.db;
            id = con.id;
        }
        /* Close - disconnect methods */
        public void disconnect() 
        {
            if (id != 0) 
            {
                disconnect(id);
                id = 0;
            }
        }
        public void close() 
        {
            disconnect();
        }
        
        /* Transaction methods */
        public void startTransaction(Database.TransactionType type)
        {
            startTransaction(type, Database.TransactionPriority.Foreground, 
                        Database.IsolationLevel.Default);
        }

        public void startTransaction(Database.TransactionType type, 
                            Database.TransactionPriority pri, 
                            Database.IsolationLevel level) 
        {
            startTransaction(id, type.ordinal(), pri.ordinal(), level.ordinal());
        }
        public boolean commitTransaction() 
        {
            return commitTransaction(id);
        }
        public boolean commitTransaction(int phase) 
        {
            if (phase != 1 && phase != 2) 
            {
                throw new IllegalArgumentException("Invalid phase: " + phase);
            }
            return commitTransactionPhase(id, phase);
        }
        public void setCommitPolicy(Database.CommitPolicy policy) 
        {
            setCommitPolicy(id, policy.ordinal());
        }
        public void diskFlush() 
        {
            diskFlush(id);
        }
        public void rollbackTransaction() 
        {
            rollbackTransaction(id);
        }
        public boolean checkpointTransaction() 
        {
            return checkpointTransaction(id);
        }
        
        /* Database operation methods */
        public long insert(Object obj) 
        {
            ...
        }
        public long count(Class cls) 
        {
            return count(id, db.getClassDescriptor(cls).classNo);
        }
        public void removeAll(Class cls) 
        {
            removeAll(id, db.getClassDescriptor(cls).classNo);
        }
        public boolean saveSnapshot(String databaseSnapshotFilePath) 
        {
            return save(id, databaseSnapshotFilePath);
        }
        public boolean saveMetadata(String databaseMetadataFilePath, boolean saveDefaults) 
        {
            return saveMetadata(id, databaseMetadataFilePath, saveDefaults);
        }
        public boolean saveDictionary(String databaseDictionaryFilePath) 
        {
            return saveDictionary(id, databaseDictionaryFilePath);
        }
        public boolean saveClass(String filePath, Class cls) 
        {
            return saveClass(id, filePath, db.getClassDescriptor(cls).classNo);
        }
        public boolean loadClass(String filePath, Class cls, boolean doMerge) 
        {
            return loadClass(id, filePath, (cls != null) ? db.getClassDescriptor(cls).classNo : 0, doMerge);
        }
        public boolean loadClass(String filePath) 
        {
            return loadClass(id, filePath, 0, false);
        }
        
        /* Event methods */
        public void waitEvent(String name) 
        {
            waitEvent(id, db.findEvent(name));
        }
        public void releaseEvent(String name) 
        {
            releaseEvent(id, db.findEvent(name));
        }
        public void releaseAllEvents() 
        {
            releaseAllEvents(id);
        }
        
        /* Statistics methods */
        public int getFreePages() 
        {
            return getFreePages(id);
        }
        public int getTotalPages() 
        {
            return getTotalPages(id);
        }
        public short getDbPageSize() 
        {
            return getDbPageSize(id);
        }
        public Statistic.ClassStat getClassStat(int classCode) 
        {
            return getClassStat(id, classCode);
        }
        public short getIndexStatCount()
        {
            return getIndexStatCount(id);
        }
        public Statistic.IndexStat getIndexStat(short index)
        {
            ...
        }
        public Statistic.DiskInfo getDiskInfo() 
        {
            return getDiskInfo(id);
        }
        
        /* Incremental Backup methods */
        public void createBackup(String fileName, String label, Database.BackupType type) 
        {
            createBackup(id, fileName, label, type.ordinal(), 0, null);
        }
        public void createBackup(String fileName, String label, Database.BackupType type, 
                        int compressionLevel, String cipher)
        {
            createBackup(id, fileName, label, type.ordinal(), compressionLevel, cipher);
        }
        public void restoreBackup(String fileName, String label) 
        {
            restoreBackup(id, fileName, label, null);
        }
        public void restoreBackup(String fileName, String label, String cipher) 
        {
            restoreBackup(id, fileName, label, cipher);
        }
        public Database.BackupInfo [] listBackup(String fileName) 
        {
            return listBackup(id, fileName);
        }
    }

Public Interface

Constructors

public Connection(Database db)

Constructor.

db: An opened Database.

Returns: a Connection instance.

public Connection(Database db, byte[] context)

Constructor.

db: An opened Database.
context: A database context.

Returns: a Connection instance.

protected Connection(Connection con)

Constructor.

con: An existing Connection.

Returns: a Connection instance.

Close - Disconnect

public void disconnect()

Close this connection.

public void close()

Close this connection (Same as disconnect()).

Transaction Control

public void startTransaction(Database.TransactionType type)

Start a database transaction.

type: A valid transaction type.

(Note that nested transactions are supported.)

public void startTransaction(Database.TransactionType type, Database.TransactionPriority pri, Database.IsolationLevel level)

Start a database transaction.

type: A valid transaction type.
pri: A valid transaction priority.
level: A valid transaction isolation level.

(Note that nested transactions are supported.)

public boolean commitTransaction()

Commit a database transaction.

Returns: false in case of an MVCC error; otherwise true.

public boolean commitTransaction(int phase)

Commit phase 1 or 2 of a two-phase database transaction.

phase: A value of 1 or 2.

Returns: false in case of an MVCC error; otherwise true.

public void setCommitPolicy(Database.CommitPolicy policy)

Set the transaction commit policy for this connection.

policy: A valid transaction commit policy.

public void diskFlush()

Flush to the persistent storage all changes made by committed transactions. (This method can be used to flush changes when the MCO_COMMIT_BUFFERED transaction policy is used.)

public void rollbackTransaction()

Rollback a transaction. (Note that any nested transactions are aborted.)

public boolean checkpointTransaction()

Checkpoint the current transaction: insert all objects updated by the current transaction in indexes.

Returns: false in case of an MVCC error; otherwise true.

Database Operations

public long insert(Object obj)

Insert a new object into the database.

obj: An object of one of the classes enumerated in the Database.Parameters.classes list.

Returns: the AUTOID of the created object if the autoid attribute is set in the Persistent annotation for this class, or 0 if class has not associated AUTOID index.

public long count(Class cls)

Return the number of instances of this class stored in the database.

cls: The class for which the instances will be counted.

public void removeAll(Class cls)

Remove all instances of the specified class. (Note that class inheritance is not considered.)

cls: The class from which the instances will be removed.

public boolean saveSnapshot(String databaseSnapshotFilePath)

Save a database snapshot to the specified file. (This snapshot can later be loaded by the Database method open() if the corresponding file path is specified in Database.Parameters.databaseSnapshotFilePath).

databaseSnapshotFilePath: The path to the file where the snapshot will be saved.

Returns: true if the snapshot file was successfully saved; false if the specified file cannot be opened.

public boolean saveMetadata(String databaseMetadataFilePath, boolean saveDefaults)

Save database metadata to the specified file. (This metadata can later be loaded as an xSQL configuration file).

databaseMetadataFilePath: The path to the file where the metadata will be saved (a file is always created or overwritten if it exists).
saveDefaults: If true, save default values.

Returns: true if the metadata file was successfully saved; false if the specified file cannot be opened.

public boolean saveDictionary(String databaseDictionaryFilePath)

Save a database dictionary to the specified file.

databaseDictionaryFilePath: The path to the file where the dictionary will be saved (a file is always created or overwritten if it exists).

Returns: true if the dictionary file was successfully saved; false if the specified file cannot be opened.

public boolean saveClass(String filePath, Class cls)

Save table content to the specified file. This snapshot can later be loaded by the Database open() or Connection loadClass().

filePath: The path to the file where the table content will be saved (a file is always created or overwritten if it exists).
cls: The class for which the contents will be saved.

Returns: true if the file was successfully saved; false if the specified file cannot be opened.

public boolean loadClass(String filePath, Class cls, boolean doMerge)

Load the table contents from the file previously created by Connection saveClass() or saveSnapshot().

filePath: The path to the file from which the table content will be loaded.
cls: The class for which the contents will be loaded.
doMerge: If false the content of the table is cleared before loading from image file; if true the loaded objects are "added" to the table.

Returns: true if the file was successfully loaded; false if the specified file cannot be opened.

public boolean loadClass(String filePath)

Load the table contents from the file previously created by Connection saveClass() or saveSnapshot() using the class id of 0 and doMerge of false.

filePath: The path to the file from which the table content will be loaded.

Returns: true if the file was successfully loaded; false if the specified file cannot be opened.

Event Methods

public void waitEvent(String name)

Wait for signaling of the specified asynchronous event.

name: The event name.

public void releaseEvent(String name)

Release the specified asynchronous event.

name: The event name.

public void releaseAllEvents()

Release all asynchronous events.

Statistics Methods

public int getFreePages()

Returns the total number of free pages.

public int getTotalPages()

Returns the total number of available (originally allocated) pages.

public short getDbPageSize()

Returns the current page size for this database connection.

public Statistic.ClassStat getClassStat(int classCode)

Allows collecting of statistics on the database at runtime.

classCode: The class code of the class for which the statistics are desired.

Returns: Statistics data for the class.

public short getIndexStatCount()

Returns the number of indexes in the database. (Note that it must be called in the context of a read-only transaction and is often used in conjunction with getIndexStat() to obtain index statistics at runtime).

public Statistic.IndexStat getIndexStat(short index)

Obtains index statistics at runtime.

index: The zero-based index number. (Note that the total count of indexes can be obtained by calling getIndexStatCount()).

Returns: Index statistics data.

public Statistic.DiskInfo getDiskInfo()

Returns information about the current state of the database and log file: the size of the log file in bytes, the size of the database file in bytes, and the amount of space that is actually used in the database file.

Incremental Backup Methods

public void createBackup(String fileName, String label, Database.BackupType type)

Create a backup record of the database.

fileName: The name of the backup file where the backup record will be created.
label: The backup's label.
type: The type of backup record (see the C API page mco_backup_create() for details).

public void createBackup(String fileName, String label, Database.BackupType type, int compressionLevel level, String cipher)

Create a backup record of the database using compression and/or encryption.

fileName: The name of the backup file where the backup record will be created.
label: The backup's label.
type: The type of backup record (see the C API page mco_backup_create() for details).
level: An optional backup compression level 1 to 9; (1 indicates the fastest, but the lowest compression level).
cipher: An optional cipher to encrypt the backup.

public void restoreBackup(String fileName, String label)

Restore backup records starting from the latest snapshot record in the specified file up to the specified label.

fileName: The name of the backup file where the backup record will be created.
label: The backup's label.

public void restoreBackup(String fileName, String label, String cipher)

Restore backup records starting from the latest snapshot record in the specified file up to the specified label using compression and/or encryption.

fileName: The name of the backup file to use for the restoration procedure.
label: The backup's label to restore.
cipher: An optional cipher to decrypt the backup.

public Database.BackupInfo [] listBackup(String fileName)

List the contents of a backup file.

fileName: The name of the backup file to list.

XML Export/Import

public boolean exportXML(String filePath)

Export the database to an XML file.

filePath: The path to the file where the database will be exported.

Returns: true if the database was successfully exported; false if the specified file cannot be opened.

public boolean importXML(String filePath, int transactionSize)

Import data from an XML file into the database.

filePath: The path to the XML file to import.
transactionSize: The number of records to process in each transaction.

Returns: true if the data was successfully imported; false if the specified file cannot be opened.

public boolean importXML(String filePath)

Import data from an XML file into the database.

filePath: The path to the XML file to import.

Returns: true if the data was successfully imported; false if the specified file cannot be opened.