jackcess-rb 0.1.0-java

data/lib/jackcess/database.rb

@@ -0,0 +1,440 @@
+# frozen_string_literal: true
+
+module Jackcess
+  # Represents a Microsoft Access database file (.mdb or .accdb).
+  #
+  # This class provides the main entry point for interacting with Access databases
+  # through the Jackcess library. It supports opening existing databases, creating
+  # new ones, and managing tables within the database.
+  #
+  # @example Open an existing database
+  #   db = Jackcess::Database.open('path/to/database.accdb')
+  #   db.table_names
+  #   # => ["Customers", "Orders", "Products"]
+  #   db.close
+  #
+  # @example Create a new database with block
+  #   Jackcess::Database.create('new.accdb', :v2007) do |db|
+  #     db.create_table('Users') do |t|
+  #       t.column 'ID', :long, auto_number: true
+  #       t.column 'Name', :text, length: 255
+  #       t.primary_key 'ID'
+  #     end
+  #   end # Database automatically closed
+  class Database
+    # The underlying Java database object from Jackcess
+    # @return [Java::ComHealthmarketscienceJackcess::Database]
+    attr_reader :java_database
+
+    # Creates a new Database instance wrapping a Java database object.
+    # This method is typically not called directly; use {.open} or {.create} instead.
+    #
+    # @param java_database [Java::ComHealthmarketscienceJackcess::Database] The Java database object
+    # @api private
+    def initialize(java_database)
+      @java_database = java_database
+      @closed = false
+    end
+
+    # Opens an existing Access database file.
+    #
+    # This method opens an existing Microsoft Access database file (.mdb or .accdb)
+    # for reading and/or writing. If a block is given, the database will be
+    # automatically closed when the block exits, even if an exception is raised.
+    #
+    # @param path [String] The file path to the database
+    # @param options [Hash] Optional configuration
+    # @option options [Boolean] :readonly (false) Open the database in read-only mode
+    # @option options [Boolean] :auto_sync (true) Automatically sync changes to disk
+    #
+    # @return [Database] A new Database instance (without block)
+    # @yield [db] Passes the database to the block
+    # @yieldparam db [Database] The opened database
+    # @yieldreturn [Object] The return value of the block (with block form)
+    #
+    # @raise [ArgumentError] If path is nil, empty, or not a String
+    # @raise [DatabaseError] If the file doesn't exist, is a directory, or cannot be opened
+    #
+    # @example Open database without block
+    #   db = Jackcess::Database.open('data/northwind.accdb')
+    #   # ... work with database ...
+    #   db.close
+    #
+    # @example Open database with block (auto-close)
+    #   Jackcess::Database.open('data/northwind.accdb') do |db|
+    #     puts db.table_names
+    #   end # Database automatically closed
+    #
+    # @example Open in read-only mode
+    #   db = Jackcess::Database.open('data/northwind.accdb', readonly: true)
+    def self.open(path, options = {})
+      raise ArgumentError, "Database path cannot be nil" if path.nil?
+      raise ArgumentError, "Database path must be a String" unless path.is_a?(String)
+      raise ArgumentError, "Database path cannot be empty" if path.empty?
+
+      path = File.expand_path(path)
+      raise DatabaseError, "Database file not found: #{path}" unless File.exist?(path)
+      raise DatabaseError, "Path is a directory, not a file: #{path}" if File.directory?(path)
+
+      begin
+        builder = DatabaseBuilder.new(java.io.File.new(path))
+        builder.set_read_only(options[:readonly]) if options.key?(:readonly)
+        builder.set_auto_sync(options[:auto_sync]) if options.key?(:auto_sync)
+
+        java_db = builder.open
+        db = new(java_db)
+
+        if block_given?
+          begin
+            yield db
+          ensure
+            db.close
+          end
+        else
+          db
+        end
+      rescue Java::JavaIo::IOException => e
+        raise DatabaseError, "Failed to open database '#{path}': #{e.message}"
+      rescue Java::JavaLang::Exception => e
+        raise DatabaseError, "Failed to open database '#{path}': #{e.message}"
+      end
+    end
+
+    # Creates a new Access database file.
+    #
+    # This method creates a new Microsoft Access database file in the specified format.
+    # If a block is given, the database will be automatically closed when the block exits.
+    #
+    # @param path [String] The file path for the new database
+    # @param format [Symbol] The Access file format (:v2000, :v2003, :v2007, or :v2010)
+    #
+    # @return [Database] A new Database instance (without block)
+    # @yield [db] Passes the database to the block
+    # @yieldparam db [Database] The created database
+    # @yieldreturn [Object] The return value of the block (with block form)
+    #
+    # @raise [ArgumentError] If path is nil, empty, not a String, or format is invalid
+    # @raise [DatabaseError] If the database cannot be created
+    #
+    # @example Create a database without block
+    #   db = Jackcess::Database.create('new.accdb', :v2007)
+    #   # ... work with database ...
+    #   db.close
+    #
+    # @example Create a database with block (auto-close)
+    #   Jackcess::Database.create('new.accdb', :v2007) do |db|
+    #     db.create_table('Products') do |t|
+    #       t.column 'ID', :long, auto_number: true
+    #       t.column 'Name', :text, length: 255
+    #       t.primary_key 'ID'
+    #     end
+    #   end # Database automatically closed
+    def self.create(path, format = :v2000)
+      raise ArgumentError, "Database path cannot be nil" if path.nil?
+      raise ArgumentError, "Database path must be a String" unless path.is_a?(String)
+      raise ArgumentError, "Database path cannot be empty" if path.empty?
+      raise ArgumentError, "Database format cannot be nil" if format.nil?
+
+      path = File.expand_path(path)
+
+      begin
+        file_format = case format
+                      when :v2000
+                        com.healthmarketscience.jackcess.Database::FileFormat::V2000
+                      when :v2003
+                        com.healthmarketscience.jackcess.Database::FileFormat::V2003
+                      when :v2007
+                        com.healthmarketscience.jackcess.Database::FileFormat::V2007
+                      when :v2010
+                        com.healthmarketscience.jackcess.Database::FileFormat::V2010
+                      else
+                        raise DatabaseError, "Unknown database format: #{format}. Valid formats are: :v2000, :v2003, :v2007, :v2010"
+                      end
+
+        java_db = DatabaseBuilder.create(file_format, java.io.File.new(path))
+        db = new(java_db)
+
+        if block_given?
+          begin
+            yield db
+          ensure
+            db.close
+          end
+        else
+          db
+        end
+      rescue Java::JavaIo::IOException => e
+        raise DatabaseError, "Failed to create database '#{path}': #{e.message}"
+      rescue Java::JavaLang::Exception => e
+        raise DatabaseError, "Failed to create database '#{path}': #{e.message}"
+      end
+    end
+
+    # Retrieves a table by name from the database.
+    #
+    # @param name [String, Symbol] The name of the table to retrieve
+    #
+    # @return [Table] The requested table
+    #
+    # @raise [ArgumentError] If name is nil or not a String/Symbol
+    # @raise [TableNotFoundError] If the table doesn't exist
+    # @raise [DatabaseError] If the database is closed or table cannot be accessed
+    #
+    # @example Get a table
+    #   table = db.table('Customers')
+    #   puts table.name # => "Customers"
+    def table(name)
+      check_closed!
+      raise ArgumentError, "Table name cannot be nil" if name.nil?
+      raise ArgumentError, "Table name must be a String or Symbol" unless name.is_a?(String) || name.is_a?(Symbol)
+
+      name = name.to_s
+      begin
+        java_table = @java_database.get_table(name)
+        raise TableNotFoundError, "Table not found: #{name}" if java_table.nil?
+
+        Table.new(java_table, self)
+      rescue Java::JavaIo::IOException => e
+        raise DatabaseError, "Failed to access table '#{name}': #{e.message}"
+      end
+    end
+
+    # Returns a sorted array of all table names in the database.
+    #
+    # @return [Array<String>] Sorted array of table names
+    #
+    # @raise [DatabaseError] If the database is closed or table names cannot be retrieved
+    #
+    # @example List all tables
+    #   db.table_names
+    #   # => ["Customers", "Orders", "Products"]
+    def table_names
+      check_closed!
+
+      begin
+        @java_database.get_table_names.to_a.sort
+      rescue Java::JavaIo::IOException => e
+        raise DatabaseError, "Failed to get table names: #{e.message}"
+      end
+    end
+
+    # Creates a new table in the database.
+    #
+    # This method uses a DSL (Domain-Specific Language) for defining the table schema.
+    # The block receives a table builder object that supports `column` and `primary_key` methods.
+    #
+    # @param name [String, Symbol] The name for the new table
+    #
+    # @return [Table] The newly created table
+    #
+    # @yield [t] Passes a table builder to the block for defining columns
+    # @yieldparam t [TableBuilderDSL] The table builder
+    #
+    # @raise [ArgumentError] If name is nil, empty, or not a String/Symbol
+    # @raise [DatabaseError] If the database is closed or table cannot be created
+    #
+    # @example Create a simple table
+    #   table = db.create_table('Users') do |t|
+    #     t.column 'ID', :long, auto_number: true
+    #     t.column 'Name', :text, length: 255
+    #     t.column 'Email', :text, length: 255
+    #     t.column 'CreatedAt', :date_time
+    #     t.primary_key 'ID'
+    #   end
+    #
+    # @see TableBuilderDSL
+    def create_table(name, &block)
+      check_closed!
+      raise ArgumentError, "Table name cannot be nil" if name.nil?
+      raise ArgumentError, "Table name must be a String or Symbol" unless name.is_a?(String) || name.is_a?(Symbol)
+      raise ArgumentError, "Table name cannot be empty" if name.to_s.empty?
+
+      begin
+        builder = TableBuilder.new(name)
+        table_builder = TableBuilderDSL.new(builder)
+        table_builder.instance_eval(&block) if block_given?
+
+        java_table = builder.to_table(@java_database)
+        Table.new(java_table, self)
+      rescue Java::JavaIo::IOException => e
+        raise DatabaseError, "Failed to create table '#{name}': #{e.message}"
+      rescue Java::JavaLang::Exception => e
+        raise DatabaseError, "Failed to create table '#{name}': #{e.message}"
+      end
+    end
+
+    # Executes a block within a transaction context.
+    #
+    # Note: Jackcess doesn't have explicit ACID transaction support like traditional
+    # databases. This method provides a semantic grouping for operations and will
+    # wrap exceptions in DatabaseError. For true atomicity, consider implementing
+    # checkpointing or using database-level features if available.
+    #
+    # @yield The block of operations to execute
+    #
+    # @raise [DatabaseError] If the database is closed or if an error occurs during the transaction
+    #
+    # @example Execute a transaction
+    #   db.transaction do
+    #     table = db.table('Accounts')
+    #     # Perform multiple operations
+    #   end
+    def transaction
+      check_closed!
+
+      # Note: Jackcess doesn't have explicit transaction support like traditional databases
+      # This is a placeholder for future enhancement
+      yield
+    rescue StandardError => e
+      raise DatabaseError, "Transaction failed: #{e.message}"
+    end
+
+    # Closes the database and flushes any pending changes to disk.
+    #
+    # After calling this method, the database cannot be used. Calling close on an
+    # already-closed database is safe and will not raise an error.
+    #
+    # @return [nil]
+    #
+    # @raise [DatabaseError] If an error occurs during the close operation
+    #
+    # @example Close a database
+    #   db = Jackcess::Database.open('data.accdb')
+    #   # ... work with database ...
+    #   db.close
+    def close
+      return if @closed
+
+      begin
+        @java_database.close
+        @closed = true
+      rescue Java::JavaIo::IOException => e
+        # Log the error but mark as closed to prevent further operations
+        @closed = true
+        raise DatabaseError, "Failed to close database cleanly: #{e.message}"
+      end
+    end
+
+    # Checks whether the database has been closed.
+    #
+    # @return [Boolean] true if the database is closed, false otherwise
+    #
+    # @example Check if database is closed
+    #   db = Jackcess::Database.open('data.accdb')
+    #   db.closed? # => false
+    #   db.close
+    #   db.closed? # => true
+    def closed?
+      @closed
+    end
+
+    # Flushes any pending changes to disk.
+    #
+    # This method forces all buffered changes to be written to the database file.
+    # It's generally not necessary to call this manually unless you need to ensure
+    # changes are persisted immediately.
+    #
+    # @return [nil]
+    #
+    # @raise [DatabaseError] If the database is closed or flush fails
+    #
+    # @example Flush changes
+    #   db = Jackcess::Database.open('data.accdb')
+    #   # ... make changes ...
+    #   db.flush # Ensure changes are written to disk
+    def flush
+      check_closed!
+
+      begin
+        @java_database.flush
+      rescue Java::JavaIo::IOException => e
+        raise DatabaseError, "Failed to flush database: #{e.message}"
+      end
+    end
+
+    private
+
+    def check_closed!
+      raise DatabaseError, "Database is closed" if @closed
+    end
+
+    # DSL (Domain-Specific Language) for building table schemas.
+    #
+    # This class provides a fluent interface for defining table columns and indexes
+    # when creating new tables. It's used internally by {Database#create_table}.
+    #
+    # @api private
+    class TableBuilderDSL
+      # Creates a new table builder DSL instance.
+      #
+      # @param builder [Java::ComHealthmarketscienceJackcess::TableBuilder] The underlying Java table builder
+      # @api private
+      def initialize(builder)
+        @builder = builder
+        @primary_key_column = nil
+      end
+
+      # Defines a column in the table.
+      #
+      # @param name [String, Symbol] The column name
+      # @param type [Symbol] The column data type (:text, :memo, :byte, :int, :long, :float, :double, :currency, :date_time, :boolean, :binary, :guid)
+      # @param options [Hash] Column options
+      # @option options [Integer] :length The maximum length for text columns
+      # @option options [Boolean] :auto_number (false) Whether this is an auto-incrementing column
+      #
+      # @return [void]
+      #
+      # @raise [ArgumentError] If name or type is invalid
+      #
+      # @example Define columns
+      #   db.create_table('Users') do |t|
+      #     t.column 'ID', :long, auto_number: true
+      #     t.column 'Name', :text, length: 255
+      #     t.column 'Email', :text, length: 255
+      #     t.column 'Age', :int
+      #     t.column 'Balance', :currency
+      #     t.column 'IsActive', :boolean
+      #     t.column 'CreatedAt', :date_time
+      #   end
+      def column(name, type, options = {})
+        raise ArgumentError, "Column name cannot be nil" if name.nil?
+        raise ArgumentError, "Column name must be a String or Symbol" unless name.is_a?(String) || name.is_a?(Symbol)
+        raise ArgumentError, "Column name cannot be empty" if name.to_s.empty?
+        raise ArgumentError, "Column type cannot be nil" if type.nil?
+
+        data_type = TypeConverter.ruby_type_to_data_type(type)
+        col_builder = ColumnBuilder.new(name, data_type)
+
+        col_builder.set_length(options[:length]) if options[:length]
+        col_builder.set_auto_number(options[:auto_number]) if options[:auto_number]
+
+        @builder.add_column(col_builder.to_column)
+      end
+
+      # Defines the primary key for the table.
+      #
+      # @param column_name [String, Symbol] The name of the column to use as primary key
+      #
+      # @return [void]
+      #
+      # @raise [ArgumentError] If column_name is nil
+      #
+      # @example Set primary key
+      #   db.create_table('Users') do |t|
+      #     t.column 'ID', :long, auto_number: true
+      #     t.column 'Name', :text, length: 255
+      #     t.primary_key 'ID'
+      #   end
+      def primary_key(column_name)
+        raise ArgumentError, "Primary key column name cannot be nil" if column_name.nil?
+
+        index_builder = com.healthmarketscience.jackcess.IndexBuilder.new(
+          com.healthmarketscience.jackcess.IndexBuilder::PRIMARY_KEY_NAME
+        )
+        index_builder.add_columns(column_name)
+        index_builder.set_primary_key
+        @builder.add_index(index_builder)
+      end
+    end
+  end
+end

data/lib/jackcess/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Jackcess
+  class Error < StandardError; end
+  class DatabaseError < Error; end
+  class TableNotFoundError < Error; end
+  class ColumnNotFoundError < Error; end
+  class InvalidTypeError < Error; end
+end

data/lib/jackcess/index.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Jackcess
+  # Represents an index on a table in an Access database.
+  #
+  # Indexes provide fast lookups and enforce uniqueness constraints.
+  # This class wraps Jackcess's Index object to provide a Ruby-friendly interface.
+  #
+  # @example Inspect table indexes
+  #   table = db.table('Users')
+  #   table.indexes.each do |index|
+  #     puts "#{index.name}: #{index.columns.join(', ')}"
+  #     puts "Primary key: #{index.primary_key?}"
+  #     puts "Unique: #{index.unique?}"
+  #   end
+  class Index
+    # The underlying Java index object from Jackcess
+    # @return [Java::ComHealthmarketscienceJackcess::Index]
+    attr_reader :java_index
+
+    # Creates a new Index instance wrapping a Java index object.
+    #
+    # @param java_index [Java::ComHealthmarketscienceJackcess::Index] The Java index object
+    # @api private
+    def initialize(java_index)
+      @java_index = java_index
+    end
+
+    # Returns the name of the index.
+    #
+    # @return [String] The index name
+    #
+    # @example Get index name
+    #   index.name # => "PrimaryKey"
+    def name
+      @java_index.get_name
+    end
+
+    # Returns an array of column names that comprise this index.
+    #
+    # @return [Array<String>] Array of column names in the index
+    #
+    # @example Get index columns
+    #   index.columns # => ["UserID", "Email"]
+    def columns
+      @java_index.get_columns.map(&:get_name)
+    end
+
+    # Checks whether this index is the table's primary key.
+    #
+    # @return [Boolean] true if this is a primary key index, false otherwise
+    #
+    # @example Check if primary key
+    #   index.primary_key? # => true
+    def primary_key?
+      @java_index.is_primary_key
+    end
+
+    # Checks whether this index enforces uniqueness.
+    #
+    # @return [Boolean] true if values in this index must be unique, false otherwise
+    #
+    # @example Check if unique
+    #   index.unique? # => true
+    def unique?
+      @java_index.is_unique
+    end
+
+    # Checks whether this index ignores null values.
+    #
+    # When true, null values in indexed columns are not included in the index.
+    #
+    # @return [Boolean] true if null values are ignored, false otherwise
+    #
+    # @example Check if nulls are ignored
+    #   index.ignore_nulls? # => false
+    def ignore_nulls?
+      @java_index.should_ignore_nulls
+    end
+
+    def inspect
+      "#<Jackcess::Index name=#{name.inspect} columns=#{columns.inspect} primary_key=#{primary_key?}>"
+    end
+
+    def to_s
+      "#{name}: #{columns.join(', ')}"
+    end
+  end
+end