CybeResearch

Template-Axiom-Query (TAQ)

CybeResearch Home » TAQ Reference » Axioms and Entities

Axioms and Entities

TAQ features relational database support so an applications can reliably persist data over time. A resource provider, dedicated to this purpose, can connect to a relational database and perform statements and queries using SQL. In order to perform it's role as a resource provider, it maps the rows of database tables to axioms. Although there is a high level of automation, some Java development is required in order to cross the divide between SQL and TAQ. The default database product is H2. Sqlite is also supported.

Database Resource Provider

The Database resource provider is identified by having a "database" property set in the resource declaration The database value is a path containing a name and location, an example being database=db/cities" for a database name of "cities" in a location of "db" relative to the application workspace. An absolute location can also be used for the case the database already exists. Note that the actual file name for a newly created database may include an extension added by the database driver,

Here is the declaration for a resource to access a "cities" database with user = "sa" and password = "secret?"

resource cities(database="db/cities") {}
(

cities.set(user="sa", password="secret?")

)

Database resource method set() configures connection properties. It appears in the resource declaration to take effect before the database connection is established.

This is not a typical database resource declaration because there are no resource roles configured as indicated by the empty braces. This omission of roles is to show that such a configuration is still useful for a function provider that needs to connect to a database.

No Resource Roles

A database resource without roles does create the database, if it does not already exist. The connection details are then available to any function provider which wants to access that database. An example of such a declaration is in a program called "show-cities.taq" which has a "print" function to display the database contents. When the program is run before the database has been created, this error is displayed

Table "CITY" not found (this database is empty); SQL statement:
SELECT `id`, `name`, `altitude` FROM `City` [42104-214]

This indicates that the database resource provider created an empty database to which the print function successfully connected and failed while running the SQL query shown on the second line of the message. Run cities.taq to populate the cities database and show-cities.taq displays 10 cities with ids ranging from 1 to 10.

Entity Class

The cities.taq resource declaration has this data consumer role

template city -> "entities_axioms.City"

This role introduces the first example of Java development required for a database resource to access a database table, in this case, an entity class named "City". An entity class is a Java bean with annotations from the Java Persistence API] (JPA) applied to create a plan of a database table. There are 3 annotations that are relevant

Annotation	Scope	Description
@Entity	class	Attribute "name" = table name
@Column	field	Attribute "name" = column name
@Id	field	Primary key - always named "id"

@Id designates the primary key. A convention applies in order to keep things simple. The primary key must be a field of integer type named "id". Pleas refer to the entity classes in the examples project to see these annotations in action.

'StarPerson' Entity Class

perfect-match2.taq writes a list of clients of a match maker agency to a "star-people" database. Included is each person's Zodiac sign. A "StarPerson" entity class has been created to provide the plan for a "StartPerson" database table. These are the @Column fields

Name	Java Type	@Column Attribute
name	String	name="name"
age	long	name="age"
starsign	entities_axiom.Zodiac	name="starsign"
rating	double	name="rating"
timestamp	java.time.Instant	name="timestamp"

This class features types which require a special approach to data persistence:

enumeration

Type 'Zodiac' is an enumeration of the 12 signs of the Zodiac. A Zodiac constant is persisted as a string, the value being the Zodiac name. This name is converted back to a Zodiac enumeration when the StartPerson table is queried.

double

Primitive type double (and it's Double wrapper) is persisted as a long value set to the bits which represent the double value. This preserves the precision of Java double values and special values "NaN" and "Infinity".

Instant

Type java.time.Instant is an example of a class which implements interface java.lang.Serializable. All serializable objects are persisted as byte arrays and readily recovered using deserialization. Note that there is no support for any object which is neither mapped to an TAQ type nor serializable.

Entity Agents

The database resource framework has two agents that perform database operations with entity classes. One is called a "collector", an agent for performing read operations and the other is called an "emitter" which performs write operations. These agents can be extended in order to customize their behavior, for example, working with two database tables which have an association with each other.

"AgriAreaPercent" Entity Class

agriculture-report.taq finds all countries which have increased the area under cultivation in the twenty-year interval between 1990 and 2010. Input data comes from 208 countries with 5 data points per country. Data for some years is not available and this is indicated using the double value 'NaN' (not a number).

The AgriAreaPercent entity class models the "AgriAreaPercent" database table which contains the input data for the report. It has the following @Column fields

Name	Java Type	@Column Attribute
country	String	name="country"
surfaceAreaKm2	double	name="surface_area_Km2"
y1970	double	name="Y1970"
y1980	double	name="Y1980"
y1990	double	name="Y1990"
y2000	double	name="Y2000"
y2010	double	name="Y2010"

Here we have the name of a country, it's surface area in square kilometers and "under cultivation" percentage values sampled over 5 decades. In all but one field, the term name differs from the field name, for example, "surface_area_Km2" is the table/axiom name for field "surfaceAreaKm2",

A second entity class named Agri20Year models the "Agri20Year" table of the report database. This defines country and surface area fields

Name	Java Type	@Column Attribute
country	String	name="country"
surfaceArea	double	name="surface_area

Entity Fields

Each entity class field representing an axiom term has a @Column annotation which maps both to an axiom term and a table column. To configure an axiom term name consistent with TAQ conventions A 'name' attribute is normally applied to the column annotation. In the case the database already exists and cannot be modified, the term name can also be configured independently of the entity class by using a name mapping feature of the database resource framework.

Entity Examples

The first two examples demonstrate the minimum Java development case where only a single entity class is required by a TAQ program. The next two examples deal with cases where the database resource provider has to be extended in order to cross the SQL/TAQ divide. These examples indicate the framework on offer is adaptable beyond working with a single database table.

'City' Entity Class

The "City" entity class previously referenced in cities.taq defines the following fields

Name	Java Type	@Column Attribute
name	String	name="name"
altitude	long	name="altitude"

In this case Java field names and TAQ term names are identical. The Java types String and long map to TAQ string and integer respectively.

high-cities-sorted3.taq reads a list of cities from the "cities" database and writes the solution to a "sorted-cites" database.There is a separate resource declaration for each database

resource data_source : "cities"
(database="db/cities")
{

"entities_axioms.City" ->

axiom city(altitude, name)

}

resource data_consumer : "sort_cities"
(database="db/sorted-cities")
{

list global.insert_sort.high_cities ->

"entities_axioms.City"

}

Notice that the "cities" data-source role has the 'name' and 'altitude' terms in reverse order to the corresponding entity fields. This has been done deliberately to point out that the order of the data-source terms is is determined by the role and not the entity fields.

As the same entity is applied to both resources they both create databases with the same layout. Run show-high-cites.taq to see the contents of the "sorted-cities" database:

Exported cities:

1 denver,5280
2 flagstaff,6970
3 addis ababa,8000
4 leadville,10200

List Data-consumer

A list data-consumer role in the "sort_cities" resource declaration is used in place of customary template to delay list contents being persisted until completion of the sort query.

Next: 'StarPerson' Entity Class ...

An entity agent can be placed in a resource role the same way an entity class can. As an example, we see in agriculture-report.taq class AgriPercentCollector feeds an axiom data-source role named "agri_area_percent"

resource agri_area_percent
(

database="db/agri-area-percent1"

)
{

"agriculture.AgriPercentCollector" -> axiom agri_area_percent()
...

}

AgriPercentCollector is an agent for the AgriAreaPercent entity class. It's customization is to enable paging so that records are read from the database in batches of no more than 10 records at a time. This avoids reading am entire database table into memory in one go.

Transfer Agent

The above agri_area_percent resource also has this axiom data-consumer role

axiom agri_decades() -> "agriculture.AgriAreaPercent"

This configures an emitter as agent for entity AgriAreaPercent and at the same time is a collector for an axiom source named "agri_decades". This arrangement allows an efficient transfer of an axiom list to a database table as the incoming axioms can be fed by a cursor in a loop. Here is the flow in which this happens

flow agri_export
{ cursor record(agri_decades) }
(

agri_area_percent.drop_tables(),
{ ?? (item = record++) agri_area_percent.emit(item) }

)

The database resource emit() method takes each axiom provided by the cursor to the transfer agent to be translated into a record that is written to the database.

Note also there is also a drop_tables() method called at the start to avoid duplication each time the query runs.

Prev: Database Resource Provider ...

Next: "AgriAreaPercent" Entity Class ...

AgriPercent Provider

The agriculture-report.taq report requires the source database plan to be updated when any new data points have to be added. This can be avoided by storing the data points for each country singly instead of collectively. An entity class named "YearPercent" models the new data points table. Each data point refers to a new country table by id..Each country record contains a name and the surface area of that country. The YearPercent @Column fields are as follows

Name	Java Type	@Column Attribute
countryId	int	name="country_id"
decade	String
percent	long

Now things get a little complicated as 5 rows need to be inserted into the new database for each input record containing 5 data points. This requires more Java development than just creating some entity classes. The end result is that the database resource provider itself has to be extended to deal with the amount of customization required. The new provider is called "AgriPercentProvider" and it is referenced in the resource declaration with a "provider" property

resource agri_area_percent
(

provider="agriculture.AgriPercentProvider",
database="db/agri-area-percent2",
type="H2"

)
{

axiom agri_area_percent()
axiom agri_decades()

}

Prev: 'StarPerson' Entity Class...