# Concept of a BTR session.  Beware, this implementation is NOT thread safe!
class BtrieveSession
  include Btrieve
  attr_reader :client_id, :cache, :btrieve_schema
  attr_accessor :host, :data_share
  private_class_method :new
  @@instance=nil
  
  # Factory of BTR sessions. A block can be passed into it, or alternatively the factory returns 
  # the session instance to the caller, who then must call 'dispose' on it when done with it.
  # The 'host' argument can be a named server or its IP address.
  # The 'data_share' argument is typically the share name of the data folder. 
  # The 'data_share' argument can also be the database name when "IDS" is used on the client. 
  def BtrieveSession.create_session(host, data_share)
    raise "Cannot create more than one instance of session." if(@@instance != nil)
    @@instance = new(host, data_share)
    @@instance.set_schema(BtrieveSchema.new())
  end

  # Returns the session instance created.  
  def BtrieveSession.get_session()
    @@instance
  end
  
  # Disposes of the session object, releasing any and all resources consumed/locked on the server. 
  def BtrieveSession.destroy_session()
    @@instance.btr_op(RESET, NULL_BUFFER, NULL_BUFFER, NULL_BUFFER, NULL_KEY)
    @@instance=nil
  end

  # Wraps and executes the block passed in inside a transaction.
  # The transaction is aborted if the block raises an exception.
  def BtrieveSession.transaction(&block)
    begin
      begin_transaction
      yield
      end_transaction
    rescue Exception => exception
      # Oops! We must roll back the whole shebang!
      abort_transaction
      raise "PSQL TX ABORTED!!! - #{exception.message}\n#{exception.backtrace.join("\n\t")}"
    end
  end
  
  # Delineates the begining of a transaction boundary. If a client calls this method explicitely, 
  # the client also has the responsibility of explicitely ending the transaction once done, 
  # or abort the transaction if things did not go well.
  def BtrieveSession.begin_transaction()
    @@instance.btr_op(BEGIN_TRANSACTION, NULL_BUFFER, NULL_BUFFER, NULL_BUFFER, NULL_KEY)
  end
  
  # Delineates the end of a transaction boundary. The client has the responsibility of calling this method
  # when a transaction was started _without_ a block. 
  def BtrieveSession.end_transaction()
    @@instance.btr_op(END_TRANSACTION, NULL_BUFFER, NULL_BUFFER, NULL_BUFFER, NULL_KEY)
  end
  
  # Aborts a transaction when something goes wrong. The client has the responsibility of calling this method
  # when a transaction was started _without_ a block AND some unexpected event occured and the client wants
  # to prevent any changes to the persistence to be commited. 
  def BtrieveSession.abort_transaction()
    @@instance.btr_op(ABORT_TRANSACTION, NULL_BUFFER, NULL_BUFFER, NULL_BUFFER, NULL_KEY)
  end
  
  def set_schema(schema)
    @btrieve_schema=schema
  end
  
  private 
  
  def initialize(host, data_share)
    @host = host
    @data_share = data_share
    @client_id = "#{0.chr*12}#{[0x5257].pack('S')}#{rand(65535)}"
    @cache = {}
  end
end