<commit_before>[[thirty-minutes-intro,Qi4j in 30 minutes]]
= Qi4j in 30 minutes =

TIP: Theses tutorials are based on actual code found in the `tutorials/` directory of the
http://qi4j.org/downloads.html[Qi4j SDK sources]. You should start your favorite editor and find the code related to
this tutorial, run it and play with it.


This introduction will deepen your understanding of Qi4j, as we touches on a couple of the common features of Qi4j. It
is expected that you have gone through and understood the "Qi4j in 10 minutes" introduction.

We will go back to the OrderEntity example;
[snippet,java]
-----------
source=tutorials/introduction/tenminutes/src/main/java/org/qi4j/demo/tenminute/OrderEntity.java
tag=mainClass
-----------

Let's say that this is an existing Composite, perhaps found in a library or used in a previous object, but we want to
add that it tracks all the changes to the order and the confirmation of such order.

First we need to create (or also find in a library) the mechanics of the audit trail. It could be something like this;

[snippet,java]
-----------
source=tutorials/introduction/thirtyminutes/src/main/java/org/qi4j/demo/thirtyminutes/ThirtyMinutesDocs.java
tag=2
-----------

Quite a lot of Qi4j features are leveraged above;
[1] Property is a first class citizen in Qi4j, instead of getters/setters naming convention to declare properties.
[2] ValueComposite for Action means that it is among other things Immutable.
[3] The Action extends a Property. We call that Property subtyping and highly recommended.
[4] The CompositeBuilder creates Immutable Action instances.

We also need a Concern to hang into the methods of the Order interface.

[snippet,java]
-----------
source=tutorials/introduction/thirtyminutes/src/main/java/org/qi4j/demo/thirtyminutes/ThirtyMinutesDocs.java
tag=3
-----------

In this case, we have chosen to make an Order specific Concern for the more generic AuditTrail subsystem, and would
belong in the client (Order) code and not with the library (AuditTrail).
Pay attention to the @This annotation for a type that is not present in the Composite type interface. This is called a
private Mixin, meaning the Mixin is only reachable from Fragments within the same Composite instance.

But the AuditTrail subsystem could provide a Generic Concern, that operates on a naming pattern (for instance). In this
case, we would move the coding of the concern from the application developer to the library developer, again increasing
the re-use value. It could look like this;

[snippet,java]
-----------
source=tutorials/introduction/thirtyminutes/src/main/java/org/qi4j/demo/thirtyminutes/ThirtyMinutesDocs.java
tag=4
-----------

The above construct is called a Generic Concern, since it implements java.lang.reflect.InvocationHandler instead of the
interface of the domain model. The ConcernOf baseclass will also need to be of InvocationHandler type, and the
Qi4j Runtime will handle the chaining between domain model style and this generic style of interceptor call chain.

Finally, we need to declare the Concern in the OrderEntity;

[snippet,java]
-----------
source=tutorials/introduction/thirtyminutes/src/main/java/org/qi4j/demo/thirtyminutes/ThirtyMinutesDocs.java
tag=5
-----------

We also place it first, so that the AuditTrailConcern will be the first Concern in the interceptor chain
(a.k.a InvocationStack), so that in case any of the other Concerns throws an Exception, the AuditTrail is not updated
(In fact, the AuditTrail should perhaps be a SideEffect rather than a Concern. It is largely depending on how we define
SideEffect, since the side effect in this case is within the composite instance it is a border case.).

So let's move on to something more complicated. As we have mentioned, EntityComposite is automatically persisted to an
underlying store (provided the Runtime is setup with one at bootstrap initialization), but how do I locate an Order?

Glad you asked. It is done via the Query API. It is important to understand that Indexing and Query are separated from
the persistence concern of storage and retrieval. This enables many performance optimization opportunities as well as a
more flexible Indexing strategy. The other thing to understand is that the Query API is using the domain model, in Java,
and not some String based query language. We have made this choice to ensure refactoring safety. In rare cases, the
Query API is not capable enough, in which case Qi4j still provides the ability to look up and execute native queries.

Let's say that we want to find a particular Order from its SequenceNumber.

[snippet,java]
-----------
source=tutorials/introduction/thirtyminutes/src/main/java/org/qi4j/demo/thirtyminutes/ThirtyMinutesDocs.java
tag=6
-----------

The important bits are;

    * The QueryExpressions.templateFor() method is used to define the template used in the query upon execution. In
      this case, we choose to template only the HasSequenceNumber, an interface used in OrderEntity, but is not part of
      Order (may or may not be a good design choice).

    * The where() clause, which has a statically imported method eq(), which builds up the expression logic, and will
      be translated into the underlying query language upon execution, which happens in the iterator() method.

Another example,

[snippet,java]
-----------
source=tutorials/introduction/thirtyminutes/src/main/java/org/qi4j/demo/thirtyminutes/ThirtyMinutesDocs.java
tag=7
-----------

In the above case, we find the Orders that has been created in the last 90 days, and add them to a report to be
generated. This example assumes that the Order type has a Property<Date> createdDate() method.

Now, Orders has a relation to the CustomerComposite which is also an Entity. Let's create a query for all customers
that has made an Order in the last 30 days;

[source,java]
-----------
QueryBuilder<HasCustomer> builder = qbf.newQueryBuilder( HasCustomer.class );

Calendar cal = Calendar.getInstance();
cal.setTime( new Date() );
Date lastMonth = cal.roll( Calendar.MONTH, -1 );
Order template1 = templateFor( Order.class );
builder.where( gt( template1.createdDate(), lastMonth ) );
Query<HasCustomer> query = builder.newQuery();

for( HasCustomer hasCustomer : query )
{
    report.addCustomerToReport( hasCustomer.customer().get() );
}
-----------

This covers the most basic Query capabilities and how to use it. For Querying to work, an Indexing subsystem must be<commit_msg>Continue work to remove all [source,java] and replace them with [snippet]<commit_after>[[thirty-minutes-intro,Qi4j in 30 minutes]]
= Qi4j in 30 minutes =

TIP: Theses tutorials are based on actual code found in the `tutorials/` directory of the
http://qi4j.org/downloads.html[Qi4j SDK sources]. You should start your favorite editor and find the code related to
this tutorial, run it and play with it.


This introduction will deepen your understanding of Qi4j, as we touches on a couple of the common features of Qi4j. It
is expected that you have gone through and understood the "Qi4j in 10 minutes" introduction.

We will go back to the OrderEntity example;
[snippet,java]
-----------
source=tutorials/introduction/tenminutes/src/main/java/org/qi4j/demo/tenminute/OrderEntity.java
tag=mainClass
-----------

Let's say that this is an existing Composite, perhaps found in a library or used in a previous object, but we want to
add that it tracks all the changes to the order and the confirmation of such order.

First we need to create (or also find in a library) the mechanics of the audit trail. It could be something like this;

[snippet,java]
-----------
source=tutorials/introduction/thirtyminutes/src/main/java/org/qi4j/demo/thirtyminutes/ThirtyMinutesDocs.java
tag=2
-----------

Quite a lot of Qi4j features are leveraged above;
[1] Property is a first class citizen in Qi4j, instead of getters/setters naming convention to declare properties.
[2] ValueComposite for Action means that it is among other things Immutable.
[3] The Action extends a Property. We call that Property subtyping and highly recommended.
[4] The CompositeBuilder creates Immutable Action instances.

We also need a Concern to hang into the methods of the Order interface.

[snippet,java]
-----------
source=tutorials/introduction/thirtyminutes/src/main/java/org/qi4j/demo/thirtyminutes/ThirtyMinutesDocs.java
tag=3
-----------

In this case, we have chosen to make an Order specific Concern for the more generic AuditTrail subsystem, and would
belong in the client (Order) code and not with the library (AuditTrail).
Pay attention to the @This annotation for a type that is not present in the Composite type interface. This is called a
private Mixin, meaning the Mixin is only reachable from Fragments within the same Composite instance.

But the AuditTrail subsystem could provide a Generic Concern, that operates on a naming pattern (for instance). In this
case, we would move the coding of the concern from the application developer to the library developer, again increasing
the re-use value. It could look like this;

[snippet,java]
-----------
source=tutorials/introduction/thirtyminutes/src/main/java/org/qi4j/demo/thirtyminutes/ThirtyMinutesDocs.java
tag=4
-----------

The above construct is called a Generic Concern, since it implements java.lang.reflect.InvocationHandler instead of the
interface of the domain model. The ConcernOf baseclass will also need to be of InvocationHandler type, and the
Qi4j Runtime will handle the chaining between domain model style and this generic style of interceptor call chain.

Finally, we need to declare the Concern in the OrderEntity;

[snippet,java]
-----------
source=tutorials/introduction/thirtyminutes/src/main/java/org/qi4j/demo/thirtyminutes/ThirtyMinutesDocs.java
tag=5
-----------

We also place it first, so that the AuditTrailConcern will be the first Concern in the interceptor chain
(a.k.a InvocationStack), so that in case any of the other Concerns throws an Exception, the AuditTrail is not updated
(In fact, the AuditTrail should perhaps be a SideEffect rather than a Concern. It is largely depending on how we define
SideEffect, since the side effect in this case is within the composite instance it is a border case.).

So let's move on to something more complicated. As we have mentioned, EntityComposite is automatically persisted to an
underlying store (provided the Runtime is setup with one at bootstrap initialization), but how do I locate an Order?

Glad you asked. It is done via the Query API. It is important to understand that Indexing and Query are separated from
the persistence concern of storage and retrieval. This enables many performance optimization opportunities as well as a
more flexible Indexing strategy. The other thing to understand is that the Query API is using the domain model, in Java,
and not some String based query language. We have made this choice to ensure refactoring safety. In rare cases, the
Query API is not capable enough, in which case Qi4j still provides the ability to look up and execute native queries.

Let's say that we want to find a particular Order from its SequenceNumber.

[snippet,java]
-----------
source=tutorials/introduction/thirtyminutes/src/main/java/org/qi4j/demo/thirtyminutes/ThirtyMinutesDocs.java
tag=6
-----------

The important bits are;

    * The QueryExpressions.templateFor() method is used to define the template used in the query upon execution. In
      this case, we choose to template only the HasSequenceNumber, an interface used in OrderEntity, but is not part of
      Order (may or may not be a good design choice).

    * The where() clause, which has a statically imported method eq(), which builds up the expression logic, and will
      be translated into the underlying query language upon execution, which happens in the iterator() method.

Another example,

[snippet,java]
-----------
source=tutorials/introduction/thirtyminutes/src/main/java/org/qi4j/demo/thirtyminutes/ThirtyMinutesDocs.java
tag=7
-----------

In the above case, we find the Orders that has been created in the last 90 days, and add them to a report to be
generated. This example assumes that the Order type has a Property<Date> createdDate() method.

Now, Orders has a relation to the CustomerComposite which is also an Entity. Let's create a query for all customers
that has made an Order in the last 30 days;

[snippet,java]
-----------
source=tutorials/introduction/thirtyminutes/src/main/java/org/qi4j/demo/thirtyminutes/ThirtyMinutesDocs.java
tag=8
-----------

This covers the most basic Query capabilities and how to use it. For Querying to work, an Indexing subsystem must be
{'fraction_non_alphanumeric': 0.07768829938417811, 'fraction_numerical': 0.006395073424917101, 'mean_word_length': 4.062749800159872, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3108955', 'n_tokens_mistral': 3481, 'n_tokens_neox': 3284, 'n_words': 1689}