indexing
     status: "See notice at end of class"
     date: "$Date$"
     revision: "$Revision$"
     access: perform_select, search, retrieve
     product: eiffelstore
     database: all_bases

class interface
     DB_SELECTION

create

     make
                 -- Create an interface objet to query active base.

feature -- Initialization

     make
                 -- Create an interface objet to query active base.
     
feature -- Access

     last_parsed_query: STRING
                 -- Last parsed SQL query
     
feature -- Status report

     after: BOOLEAN
                 -- Is the container after?
           require
                 container_exists: container /= void

     container: LIST [DB_RESULT]
                 -- Stored cursors.

     cursor: DB_RESULT
                 -- Cursor pointing to last fetched query result

     immediate_execution: BOOLEAN
                 -- Are requests immediately executed?
                 -- (default is no).
                 -- (from DB_EXEC_USE)

     is_allocatable: BOOLEAN
                 -- Can Current be added to other concurrently opened selections?

     is_exiting: BOOLEAN
                 -- Is exit condition of load_result iteration loop met?
           ensure
                 Result implies (not is_ok or else exhausted or else (stop_condition /= void and then stop_condition.found))

     is_mapped (key: STRING): BOOLEAN
                 -- Is key mapped to an Eiffel entity?
                 -- (from STRING_HDL)
           require -- from STRING_HDL
                 keys_exists: key /= void

     is_tracing: BOOLEAN
                 -- Is trace option for SQL queries on?
                 -- (from DB_EXEC_USE)

     last_query: STRING
                 -- Last SQL statement used
                 -- (from DB_EXPRESSION)

     mapped_value (key: STRING): ANY
                 -- Value mapped with key
                 -- (from STRING_HDL)
           require -- from STRING_HDL
                 key_exists: key /= void
                 key_mapped: is_mapped (key)
           ensure -- from STRING_HDL
                 result_exists: Result /= void

     object: ANY
                 -- Eiffel object to be filled in by cursor_to_object

     stop_condition: ACTION
                 -- Object providing an execute routine called
                 -- after each load_result iteration step

     trace_output: FILE
                 -- Trace destination file
                 -- (from DB_EXEC_USE)
     
feature -- Status report

     is_connected: BOOLEAN
                 -- Has connection to the database server succeeded?
                 -- (from DB_STATUS_USE)

     is_ok: BOOLEAN
                 -- Is last SQL statement ok ?
                 -- (from DB_STATUS_USE)
     
feature -- Status setting

     clear_all
                 -- Remove all mapped keys.
                 -- (from STRING_HDL)

     cursor_to_object
                 -- Assign object attributes with cursor field values.
           require
                 cursor_exists: cursor /= void
                 object_exists: object /= void

     forth
                 -- Move cursor to next element of container.
           require else
                 container_exists: container /= void
           ensure then
                 container_index_moved: container.index = old container.index + 1
                 cursor_updated: not after implies cursor = container.item

     no_object_convert
                 -- Do not transform cursor into an Eiffel object
                 -- while reading in selection results.
           ensure
                 object = void

     object_convert (reference: ANY)
                 -- Set object with reference, reference to an Eiffel
                 -- object to be filled in with cursor field values.
           require
                 reference_exists: reference /= void
           ensure
                 object_set: object = reference

     reset_cursor (c: DB_RESULT)
                 -- Reset cursor with c.
           require
                 arguments_exists: c /= void
                 connected: is_connected
           ensure
                 cursor_reset: cursor = c

     set_action (action: ACTION)
                 -- Set stop_condition with action.
           require
                 action_exists: action /= void
           ensure
                 stop_condition_set: stop_condition = action

     set_container (one_container: like container)
                 -- Make results of selection query persist in container.
           require
                 container_exists: one_container /= void
           ensure
                 container_set: container = one_container

     set_immediate
                 -- Set queries to be executed with a
                 -- `EXECUTE IMMEDIATE' SQL  statement.
                 -- (from DB_EXEC_USE)
           ensure -- from DB_EXEC_USE
                 execution_status: immediate_execution

     set_map_name (n: ANY; key: STRING)
                 -- Store item n with key key.
                 -- n can be Void.
                 -- (from STRING_HDL)
           require -- from STRING_HDL
                 key_exists: key /= void
                 not_key_in_table: not is_mapped (key)
           ensure -- from STRING_HDL
                 ht.count = old ht.count + 1

     set_query (query: STRING)
                 -- Set last_query with query.
                 -- (from DB_EXPRESSION)
           require -- from DB_EXPRESSION
                 query_not_void: query /= void
           ensure -- from DB_EXPRESSION
                 last_query_changed: last_query = query

     set_trace
                 -- Trace queries sent to database server.
                 -- (from DB_EXEC_USE)
           ensure -- from DB_EXEC_USE
                 trace_status: is_tracing

     start
                 -- Set cursor on first element of container.
           require else
                 container_exists: container /= void
           ensure then
                 container_on_first: container.isfirst
                 cursor_updated: cursor = container.item

     unset_action
                 -- Reset stop_condition to Void.
           ensure
                 stop_condition_void: stop_condition = void

     unset_container
                 -- Do not store in container results of selection.
           require
                 container_exists: container /= void
           ensure
                 container_is_void: container = void

     unset_immediate
                 -- Set queries to be executed with a
                 -- PREPARE followed by a EXECUTE SQL statement.
                 -- (from DB_EXEC_USE)
           ensure -- from DB_EXEC_USE
                 execution_status: not immediate_execution

     unset_map_name (key: STRING)
                 -- Remove item associated with key key.
                 -- (from STRING_HDL)
           require -- from STRING_HDL
                 key_exists: key /= void
                 item_exists: is_mapped (key)
           ensure -- from STRING_HDL
                 ht.count = old ht.count - 1

     unset_trace
                 -- Do not trace queries sent to database server.
                 -- (from DB_EXEC_USE)
           ensure -- from DB_EXEC_USE
                 trace_status: not is_tracing
     
feature -- Basic operations

     execute_query
                 -- Execute query with last_query.
           require -- from DB_EXPRESSION
                 last_query_not_void: last_query /= void

     load_result
                 -- Iterate through selection results,
                 -- load container if requested and call action routine
                 -- for each iteration step until exit_condition is met.
           require
                 connected: is_connected
                 is_ok: is_ok
           ensure
                 cursor_not_void: cursor /= void
                 exit_condition_met: is_exiting

     next
                 -- Move to next element matching the query.
           require
                 connected: is_connected

     query (s: STRING)
                 -- Select stored objects using s and make
                 -- them retrievable using load_result.
           require
                 connected: is_connected
                 argument_exists: s /= void
                 argument_is_not_empty: not s.is_empty
                 is_ok: is_ok
                 is_allocatable: is_allocatable
           ensure
                 last_query_changed: last_query = s

     terminate
                 -- Clear database cursor.
           require
                 connected: is_connected
           ensure
                 is_allocatable: is_allocatable

     wipe_out
                 -- Clear selection results.
           ensure
                 container_is_empty: container /= void implies container.is_empty
                 object_model_void: object = void
                 cursor_void: cursor = void
     
invariant

     last_cursor_in_container: container /= void and then not container.is_empty implies container.has (cursor)
           -- from ANY
     reflexive_equality: standard_is_equal (Current)
     reflexive_conformance: conforms_to (Current)

end -- class DB_SELECTION