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 will be available to the
application. You do that by adding a unit named Aurelius.SQL.XXX
and Aurelius.Schema.XXX
(where XXX is the name of SQL dialect) to any unit of your application,
or the project itself.
uses
{...}, Aurelius.SQL.MySQL, Aurelius.Schema.MySQL,
Aurelius.SQL.MSSQL, Aurelius.Schema.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.