# Record class

Record class is an implementation of DbRecord interface. It uses GDA to get access to a database's row in a table.

In order to load data, you need to set a Gda.Connection, a table and a key. Then update() method execute a SELECT command using the key to find the required row in the table.

## Record class UML definition

### UML definition

This diagram describes Record class and its implementations.

## Using a Record class to access a row in a table

This codes initiate a Record class, set a table to use, a key and a connection in order to call update().

      var r = new Record ();
      var t = new Table ();
      t.name = "customer";
      r.table = t;
      r.connection = connection;
      r.set_key_value ("id", 1);
      r.update ();

In the above code, connection is opened before to be set to Record.connection property. You need to setup a Table class to set to Record.table property, but just set Table.name property to the table's name is required. Use Record.set_key_value() method to set the value to the column used in the table as the primary key and to allow update() method to find the correct row (the WHERE clause in SELECT statement), if more than one key exists you must set it; you must know the column and type of value to set.

## Using a Record class to add a new row in a table

This code set up a row to be added to a database's table:

      var r = new Record ();
      var t = new Table ();
      t.name = "customer";
      r.table = t;
      r.connection = connection;
      r.set_field_value ("name", "Clausse Rayman");
      r.set_field_value ("company", "Packing Sources, Ltd.");
      r.append ();

In the above code a new row will be added. Create a new Record object, set a table to add a new row to; use Record.set_field_value() to set values to columns in the table, you must know columns and data type to set. At the end call Record.save() to add the new row.

Record.set_field_value() doesn't know if the columns and type is correct, just store the value to used in an INSERT statement; if key is set by database engine it will be added automatically, if not you must set it in order to execute save() with no errors.

## Update data in a row

Once you have set a key and a table to a Record object, you can call Record.set_field_value() to change row's column's values, once done, you can call Record.save() to call an UPDATE command and update database's row/column values.

### Updating columns' values

This code sets a key and a table to find a row and set a column's value, then call save() to update data in the database

      var r = new Record ();
      r.connection = connection;
      /* Set a value to the key you want to use to select the correct row */
      r.set_key_value ("id", 1);
      r.set_field_value ("name", "Jack Swan");
      r.save ();

## Deleting rows

If you want to delete a row in a database's table, just create a new Record object, set a key, a table and a connection, then call Record.drop().

### How to delete a row in a table

This code shows how to setup and delete a row to be deleted in a database's table.

      var r = new Record ();
      r.connection = connection;
      var t = new Table ();
      t.name = "table_name";
      r.table = t;
      r.set_key_value ("id", 1);
      r.drop ();

## Subclassing Record class

Record class could be used as base for others. Is useful to wrap Record.set_field_value() into your class property to hide database access.

Use try{} catch{} to avoid warnings for unhandled error.

This code declares a new class MyRecord derived from Record.

      class MyRecord : Record
      {
        public MyRecord () { /* Your init code */ }

        public string name
        {
          get
          {
            try {
              return this.get_value ("name");
            }
            catch (Error e) {
              GLib.warning ("ERROR on getting value from name property: " + e.message)
            }
          }

          set
          {
            try {
              return this.set_field_value ("name", value);
            }
            catch (Error e) {
              GLib.warning ("ERROR on setting value to name property: " + e.message)
            }
          }
        }
      }

The above code declares a MyRecord.name property witch uses Record.get_value() and Record.set_field_value() from its base class, to get and set its value.

## Iterating through Fields

You can iterate over Record's fields using Vala foreach statement, by using Record.fields property; it's a Gee.Collection of DbField objects, then you can use:

      foreach (DbField f in record.fields) {
        /* work with DbField object */
      }

The same apply for all keys you set by using Record.keys property.