Connection

Connection 为所有与数据库对象进行交互的线程提供接口。

类定义

    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 Connection(Database db)：
- 参数：
  - db：打开的Database
- 返回
  - Connection 实例
public Connection(Database db, byte[] context)：
- 参数：
  - db：打开的Database
  - context：数据库context
- 返回
  - Connection 实例
protected Connection(Connection con)：
- 参数：
  - con：现有的 Connection
- 返回
  - Connection 实例

关闭 - 断开连接

public void disconnect()：关闭此连接
public void close()：关闭此连接（与断开连接（disconnect()）相同）

事务控制

public void startTransaction(Database.TransactionType type)：启动数据库事务（支持嵌套事务）；
- 参数：
  - type：有效的事务类型
public void startTransaction(Database.TransactionType type, Database.TransactionPriority pri, Database.IsolationLevel level)：启动数据库事务（支持嵌套事务）；
- 参数：
  - type：有效的事务类型
  - pri：有效的事务优先级
  - level：有效的事务隔离级别
public boolean commitTransaction()：提交数据库事务。返回值：在 MVCC 错误的情况下返回 False；否则返回 True。
public boolean commitTransaction(int phase)：提交两阶段数据库事务的第一阶段或第二阶段；
- 参数：
  - phase：值为 1 或 2
- 返回：
  - 如果出现 MVCC 错误则为 False；否则为 True
public void setCommitPolicy(Database.CommitPolicy policy)：为该连接设置事务提交策略；
- 参数：
  - policy：有效的事务提交策略
public void diskFlush()：将已提交事务所做的所有更改刷新到持久存储中。（当使用 MCO_COMMIT_BUFFERED 事务策略时，可以使用此方法刷新更改。）
public void rollbackTransaction()：回滚事务。（请注意，任何嵌套事务都将被中止。）
public boolean checkpointTransaction()：检查当前事务：将当前事务更新的所有对象插入索引中
- 返回：
  - 如果出现 MVCC 错误则为 False；否则为 True

数据库操作

public long insert(Object obj)：向数据库中插入一个新对象；
- 参数：
  - obj：在Database.Parameters.classes列表中枚举的类之一的对象
- 返回：
  - 如果为该类设置了 Persistent 注解中的 autoid 属性，则返回所创建对象的 AUTOID；如果该类未关联 AUTOID 索引，则返回 0 。
public long count(Class cls)：返回存储在数据库中的此类实例的数量；
- 参数：
  - cls：将要计算其实例数量的类
public void removeAll(Class cls)：移除所有指定类的实例。（请注意，类继承关系不予考虑。）
- 参数：
  - cls：将要计算其实例数量的类
public boolean saveSnapshot(String databaseSnapshotFilePath)：将数据库快照保存到指定文件中。（如果在 Database.Parameters.databaseSnapshotFilePath 中指定了相应的文件路径，此快照稍后可通过 Database 方法 open() 加载）
- 参数：
  - databaseSnapshotFilePath：保存快照的文件路径
- 返回：
  - 如果快照文件成功保存则为 True；如果指定的文件无法打开则为 False。
public boolean saveMetadata(String databaseMetadataFilePath, boolean saveDefaults)：将数据库元数据保存到指定文件中。（此元数据稍后可作为 xSQL 配置文件加载）；
- 参数：
  - databaseSnapshotFilePath：保存快照的文件路径
  - saveDefaults：如果为True，保存默认值
- 返回：
  - 如果元数据文件成功保存则返回 True；如果指定的文件无法打开则返回 False
public boolean saveDictionary(String databaseDictionaryFilePath)：将数据库字典保存到指定文件；
- 参数：
  - databaseSnapshotFilePath：保存快照的文件路径
  - saveDefaults：如果为True，保存默认值
- 返回：
  - 如果元数据文件成功保存则返回 True；如果指定的文件无法打开则返回 False
public boolean saveClass(String filePath, Class cls)：将数据库字典保存到指定文件；
- 参数：
  - filePath：保存表格内容的文件路径（如果文件已存在，则始终会创建新文件或覆盖原文件）
  - cls：将要保存内容的类
- 返回：
  - 如果元数据文件成功保存则返回 True；如果指定的文件无法打开则返回 False
public boolean loadClass(String filePath, Class cls, boolean doMerge)：从先前由 Connection 的 saveClass() 或 saveSnapshot() 方法创建的文件中加载表内容；
- 参数：
  - filePath：加载表格内容的文件路径
  - cls：将要加载内容的类
  - doMerge：如果为 False，则在从图像文件加载之前会清除表格中的内容；如果为 True，则加载的对象将“添加”到表格中。
- 返回：
  - 如果文件成功加载则为 True；如果指定的文件无法打开则为 False
public boolean loadClass(String filePath)：使用类标识符为 0 且 doMerge 参数为 False 从先前由 Connection 的 saveClass() 或 saveSnapshot() 方法创建的文件中加载表内容；
- 参数：
  - filePath：加载表格内容的文件路径
- 返回：
  - 如果文件成功加载则为 True；如果指定的文件无法打开则为 False

事件方法

public void waitEvent(String name)：等待指定异步事件的信号；
- 参数：
  - name：事件名称
public void releaseEvent(String name)：释放指定的异步事件；
- 参数：
  - name：事件名称
public void releaseAllEvents()：释放所有异步事件；

统计方法

public int getFreePages()：获取空闲页面总数；
public int getTotalPages()：返回可用（最初分配的）页面的总数；
public short getDbPageSize()：返回此数据库连接的当前页面大小；
public Statistic.ClassStat getClassStat(int classCode)：允许在运行时收集数据库的统计信息；
- 参数：
  - classCode：需要统计信息的类的类代码
- 返回：
  - 类的统计数据
public short getIndexStatCount()：返回数据库中的索引数量。（请注意，必须在只读事务的上下文中调用此方法，并且通常与 getIndexStat() 结合使用，以便在运行时获取索引统计信息）
public Statistic.IndexStat getIndexStat(short index)：在运行时获取索引统计信息；
- 参数：
  - index：从零开始的索引编号。（注意，索引的总数可通过调用 getIndexStatCount() 获取）
- 返回：
  - 索引统计信息数据
public Statistic.DiskInfo getDiskInfo()：返回有关数据库和日志文件当前状态的信息：日志文件的大小（以字节为单位）、数据库文件的大小（以字节为单位）以及数据库文件中实际使用的空间量。

增量备份方法

public void createBackup(String fileName, String label, Database.BackupType type)：创建数据库的备份记录；
- 参数：
  - fileName：将创建备份记录的备份文件的名称
  - label：备份的标签
  - type：备份记录的类型（详情请参阅 C API 页面 mco_backup_create()）
public void createBackup(String fileName, String label, Database.BackupType type, int compressionLevel level, String cipher)：使用压缩和/或加密方式创建数据库的备份记录；
- 参数：
  - fileName：将创建备份记录的备份文件的名称
  - label：备份的标签
  - type：备份记录的类型（详情请参阅 C API 页面 mco_backup_create()）
  - level：可选的备份压缩级别为 1 至 9；（1 表示速度最快，但压缩级别最低）
  - cipher：用于加密备份的可选密码算法
public void restoreBackup(String fileName, String label)：从指定文件中的最新快照记录开始恢复备份记录，直至指定标签；
- 参数：
  - fileName：用于恢复过程的备份文件的名称
  - label：备份的标签
public void restoreBackup(String fileName, String label, String cipher)
- 参数：
  - fileName：用于恢复过程的备份文件的名称
  - label：备份的标签
  - cipher：用于加密备份的可选密码算法
public Database.BackupInfo [] listBackup(String fileName)：列出备份文件的内容；
- 参数：
  - fileName：要列出的备份文件的名称