Basic operations

Inserting

You can insert a new object using feature insert in PS_TRANSACTION. As every write operation in ABEL needs to be embedded in a transaction, you first need to create a PS_TRANSACTION object. Let's add three new persons to the database:

insert_persons -- Populate the repository with some person objects. local p1, p2, p3: PERSON transaction: PS_TRANSACTION do -- Create persons create p1.make (...) create ... -- We first need a new transaction. transaction := repository.new_transaction -- Now we can insert all three persons. if not transaction.has_error then transaction.insert (p1) end if not transaction.has_error then transaction.insert (p2) end if not transaction.has_error then transaction.insert (p3) end -- Commit the changes. if not transaction.has_error then transaction.commit end -- Check for errors. if transaction.has_error then print ("An error occurred!%N") end end

Querying

A query for objects is done by creating a PS_QUERY [G] object and executing it using features of PS_REPOSITORY or PS_TRANSACTION. The generic parameter G denotes the type of objects that should be queried.

After a successful execution of the query, you can iterate over the result using the across syntax. The feature print_persons below shows how to get and print a list of persons from the repository:

print_persons -- Print all persons in the repository local query: PS_QUERY[PERSON] do -- First create a query for PERSON objects. create query.make -- Execute it against the repository. repository.execute_query (query) -- Iterate over the result. across query as person_cursor loop print (person_cursor.item) end -- Check for errors. if query.has_error then print ("An error occurred!%N") end -- Don't forget to close the query. query.close end

In a real database the result of a query may be very big, and you are probably only interested in objects that meet certain criteria, e.g. all persons of age 20. You can read more about it in Advanced Queries.

Please note that ABEL does not enforce any kind of order on a query result.

Updating

Updating an object is done through feature update in PS_TRANSACTION. Like the insert operation, an update needs to happen within a transaction. Note that in order to update an object, we first have to retrieve it.

Let's update the age attribute of Berno Citrini by celebrating his birthday:

update_berno_citrini -- Increase the age of Berno Citrini by one. local query: PS_QUERY[PERSON] transaction: PS_TRANSACTION berno: PERSON do print ("Updating Berno Citrini's age by one.%N") -- Create query and transaction. create query.make transaction := repository.new_transaction -- As we're doing a read followed by a write, we -- need to execute the query within a transaction. if not transaction.has_error then transaction.execute_query (query) end -- Search for Berno Citrini across query as cursor loop if cursor.item.first_name ~ "Berno" then berno := cursor.item -- Change the object. berno.celebrate_birthday -- Perform the database update. transaction.update (berno) end end -- Cleanup query.close if not transaction.has_error then transaction.commit end if transaction.has_error then print ("An error occurred.%N") end end

To perform an update the object first needs to be retrieved or inserted within the same transaction. Otherwise ABEL cannot map the Eiffel object to its database counterpart.

Deleting

ABEL does not support explicit deletes any longer, as it is considered dangerous for shared objects. Instead of deletion it is planned to introduce a garbage collection mechanism in the

Dealing with Known Objects

Within a transaction ABEL keeps track of objects that have been inserted or queried. This is important because in case of an update, the library internally needs to map the object in the current execution of the program to its specific entry in the database.

Because of that, you can't update an object that is not yet known to ABEL. As an example, the following functions will fail:

failing_update -- Trying to update a new person object. local bob: PERSON transaction: PS_TRANSACTION do create bob.make ("Robert", "Baratheon") transaction := repository.new_transaction -- Error: Bob was not inserted / retrieved before. -- The result is a precondition violation. transaction.update (bob) transaction.commit end update_after_commit -- Update after transaction committed. local joff: PERSON transaction: PS_TRANSACTION do create joff.make ("Joffrey", "Baratheon") transaction := repository.new_transaction transaction.insert (joff) transaction.commit joff.celebrate_birthday -- Prepare can be used to restart a transaction. transaction.prepare -- Error: Joff was not inserted / retrieved before. -- The result is a precondition violation. transaction.update (joff) -- Note: After commit and prepare,`transaction' -- represents a completely new transaction. end

The feature is_persistent in PS_TRANSACTION can tell you if a specific object is known to ABEL and hence has a link to its entry in the database.