# Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
# License:   Apache License, Version 2.0

module RTM
  module Connections
    # Connects to a topic map engine using the specificed backend and configuration
    #
    # @example Connect to Ontopia backend (in memory)
    #   RTM.connect(:backend => :ontopia)
    # @example Connect to Ontopia backend (relational database), here: using the H2 adapter
    #   RTM.connect(:backend => :ontopia_rdbms, :config => { :adapter => 'jdbch2', :database => "db-rtm-ontopia"})
    # @example Connect to tinyTim backend (in memory)
    #   RTM.connect(:backend => :tinytim)
    # @example Connect to Active Record backend (relational database)
    #   RTM.connect(:backend => :activerecord)
    # @example Connect to SesameTM backend
    #   RTM.connect(:backend => :sesametm)
    # @example Connect to Hatana backend (in memory, with different stores)
    #   RTM.connect(:backend => :hatana)
    # @param [Hash] params the options to create the connection with.
    # @option params [Symbol] :backend (:ontopia) the backend
    # @option params [Symbol] :implementation @deprecated use :backend instead
    # @option params [Hash] :config (nil) the backend-specific configuration
    # @return [Engine] The connection object
    def connect(params = {}, *args)
      params ||= {} # this is needed to handle passing nil
      engine = Engine.load!(params[:backend] || params[:implementation])
      connection = engine.connect(params)
      connections[params[:identifier]] = connection if params[:identifier]
      connection
    end

    # Return all connections or a particular connection.
    # @overload connections
    #   Returns all registered connections, keyed by their identifiers.
    #   @return [Hash]
    # @overload connections(identifier)
    #   @param [Symbol] identifier of the registered connection
    #   @return [Engine] the connection object
    def connections(*args)
      @connections ||= {}
      if args.size > 0
        @connections[*args]
      else
        @connections
      end
    end

    RTM.extend(self)
  end
end