Getting Started

In this chapter we will provide you basic info about how to get started using TMS Aurelius. They are simple examples, but shows you how quickly you can start use it, and how simple is that. The intention is to explain the macro structure of the framework and what are the major steps to setup it. For a full usage of the framework and full flexibility, see other chapters in this manual.

Quick Start

Here we describe minimal steps to get started using TMS Aurelius framework.

1. Create the class model

Create a new class to be saved in the database (you can also use an existing class in your application):

type
  TPerson = class
  private
    FLastName: string;
    FFirstName: string;
    FEmail: string;
  public
    property LastName: string read FLastName write FLastName;
    property FirstName: string read FFirstName write FFirstName;
    property Email: string read FEmail write FEmail;
  end;

Your class can descend from any other Delphi class.

2. Define and map persistent entity class

Add Entity and Automapping attributes to the class, and an integer FId field. This will do automatic mapping.

Note

All attributes you need are declared in unit Aurelius.Mapping.Attributes so you must add it to your unit.

uses
  {...}, Aurelius.Mapping.Attributes;

type
  [Entity]
  [Automapping]
  TPerson = class
  private
    FId: integer;
    FLastName: string;
    FFirstName: string;
    FEmail: string;
  public
    property Id: integer read FId;
    property LastName: string read FLastName write FLastName;
    property FirstName: string read FFirstName write FFirstName;
    property Email: string read FEmail write FEmail;
  end;

You can also fully customize mapping - there is no need to use automatic one. Even including an FId is not required if you don't use automatic mapping.

3. Obtain an IDBConnection interface

Get the component you use in your application to connect to the database (FireDAC, ADO) and obtain an IDBConnection interface from it.

Note

The IDBConnection interface is declared in Aurelius.Drivers.Interfaces unit. Each adapter is declared in a different unit, you must check which unit you must use for each available adapter.

Or, use a native database driver to connect to the database directly.

uses
  {...}, Aurelius.Drivers.Interfaces, Aurelius.Drivers.FireDac;

var
  MyConnection: IDBConnection;
begin
  // FDConnection1 is a FireDac TFDConnection component
  // You can use several different data-access component libraries
  // or use a native database driver to connect directly
  MyConnection := TFireDacConnectionAdapter.Create(FDConnection1, false);

4. Specify the SQL dialect

Let Aurelius know which SQL dialects wlll be available to the application. You do that by adding a unit named Aurelius.SQL.XXX (where XXX is the name of SQL dialect) to any unit of your application, or the project itself.

uses 
  {...}, Aurelius.SQL.MySQL, Aurelius.SQL.MSSQL;

In the example above, we make Aurelius aware of MySQL and Microsoft SQL Server dialects. The correct dialect will be chosen by Aurelius depending on the connection you specified in step 3. In that step (3) you can even specify which dialect you are using. There are plenty of SQL dialects you can use in Aurelius.

5. Create the database

Use the Database Manager to create the underlying database tables and fields where the objects will be saved.

Note

TDatabaseManager is declared in unit Aurelius.Engine.DatabaseManager.

uses
  {...}, Aurelius.Engine.DatabaseManager;

DBManager := TDatabaseManager.Create(MyConnection);
DBManager.UpdateDatabase;

If you have an existing database with specific fields and tables you want to use, just skip this step.

6. Instantiate and save objects

Now you can instantiate a new TPerson instance and save it in the database, using the object manager:

uses
  {...}, Aurelius.Engine.ObjectManager;

Person := TPerson.Create;
Person.LastName := 'Lennon';
Person.FirstName := 'John';
Person.Email := 'lennon@beatles.com';

Manager := TObjectManager.Create(MyConnection);
try
  Manager.Save(Person);
  PersonId := Person.Id;
finally
  Manager.Free;
end;

A new record will be created in the database. Person.Id will be generated automatically.

7. Retrieve and update objects

Manager := TObjectManager.Create(MyConnection);
Person := Manager.Find<TPerson>(PersonId);
Person.Email := 'john.lennon@beatles.org';
Manager.Flush;
Manager.Free;

This way you can retrieve object data, update values and save it back to the database.

8. Perform queries

What if you want to retrieve all persons which e-mail belongs to domain "beatles.org" or "beatles.com"?

Note

There are several units you can use to build queries. Aurelius.Criteria.Base must be always used, then for filter expressions you can use Aurelius.Criteria.Expression or Aurelius.Criteria.Linq if you prefer using linq-like operators. To use projections, use Aurelius.Criteria.Projections unit.

uses
  {...}, Aurelius.Criteria.Base, Aurelius.Criteria.Linq;

Manager := TObjectManager.Create(MyConnection);
Results := Manager.Find<TPerson>
  .Where(
     Linq['Email'].Like('%beatles.org%')
     or Linq['Email'].Like('%beatles.com%')
     )
  .List;

// Iterate through Results here, which is a TList<TPerson> list.
for person in Results do
  // use person variable here, it's a TPerson object

Manager.Free;

9. What's Next?

With just the above steps you are able to create the database and SAVE your classes in there, being able to save, delete, update and query objects. But what if you want:

a. Create a new class TCompany descending from TPerson and also save it?

Aurelius supports inheritance strategies using the Inheritance attribute.

b. Fine-tune the mapping to define names and types of the table columns where the class properties will be saved to?

You can do manual mapping using several attributes like Table and Column to define the database table and columns. You can even use Nullable<T> types to specify fields that can receive null values.

c. Create properties that are also objects or list of objects (e.g., a property Country: TCountry in my TPerson class), and also save them?

You can do it, using associations that can be fetched in a lazy or eager mode. You do that using Association and ManyValuedAssociation attributes.

d. Define different identifier strategies, define sequences, unique indexes, etc., in my database?

Just use the several mapping attributes available.

e. Perform complex queries using different conditional expressions, grouping, ordering, aggregated functions, condition expression in associated objects, etc.?

Aurelius allow you to create complex queries using all the mentioned features and more, all at object-level. ou don't need to use SQL statements for that.

f. Send/receive Aurelius objects in JSON format through REST servers or any other multi-tier architecture?

You can use TMS XData automatic CRUD endpoints to create REST server and distributed applications that automatically send and receive Aurelius objects via JSON.