manual/src/docs/tutorials/howto-create-concern.txt

[[howto-create-concern,Create a Concern]]
= Create a Concern =

Concerns are defined in <<def-concern>>.

If you want to reproduce what's explained in this tutorial, remember to depend on the Core Bootstrap artifact:

include::../../../../core/bootstrap/build/docs/buildinfo/artifact.txt[]

At runtime you will need the Core Runtime artifact too. See the <<howto-depend-on-qi4j>> tutorial for details.

== Typed Concern ==

A typed Concern is a Java class that implements the MixinType it can be used on:

[snippet,java]
-----------
source=tutorials/introduction/tenminutes/src/main/java/org/qi4j/demo/tenminute/InventoryConcern.java
tag=allClass
-----------

The InventoryConcern is implemented as an abstract class, since we are not interested in the many other methods in the
Order interface. Extending the ConcernOf is a convenience mechanism, instead of an explicit @ConcernFor annotation on
a private field, which can be used in rare occasions when you are not able to extend. This base class defines the next
field, which is set up by the Qi4j runtime and points to the next fragment in the call stack. We can also see that the
InventoryService is provided to the concern, which is done with dependency injection. Qi4j also supports dependency
injection via constructors and methods.

It can be used as follows;

[snippet,java]
-----------
source=manual/src/main/java/org/qi4j/manual/recipes/concern/Order.java
tag=class
-----------

Methods of the Concern Fragment will be called before the Mixin invocation.


== Generic Concern ==

A generic Concern is a Java class that implements java.lang.reflect.InvocationHandler which allows it to be used on any
arbitrary MixinType.

[snippet,java]
-----------
source=manual/src/main/java/org/qi4j/manual/recipes/concern/MyGenericConcern.java
tag=class
-----------

It can be used as follows;

[snippet,java]
-----------
source=manual/src/main/java/org/qi4j/manual/recipes/concern/AnyMixinType.java
tag=class
-----------

Methods of the Concern Fragment will be called before the Mixin invocation.

=== AppliesTo ===

For generic Concerns that should only trigger on methods with specific annotations or fulfilling some expression, add
@AppliesTo annotation to the Concern class which points to either triggering annotation(s), or to AppliesToFilter
implementation(s).

The Concern is invoked if one of the triggering annotations is found or one of the AppliesToFilter accepts the
invocation. In other words the AppliesTo arguments are OR'ed.

Here is how the declaration goes ;

[snippet,java]
-----------
source=manual/src/main/java/org/qi4j/manual/recipes/concern/MyGenericConcern.java
tag=appliesTo
-----------

And how to use the annotation ;

[snippet,java]
-----------
source=manual/src/main/java/org/qi4j/manual/recipes/concern/AnyMixinType.java
tag=annotationUse
-----------

Here only the doSomething() method will see the Concern applied whereas the doSomethingElse() method won't.

Finally here is how to implement an AppliesToFilter:

[snippet,java]
-----------
source=manual/src/main/java/org/qi4j/manual/recipes/concern/MyAppliesToFilter.java
tag=filter
-----------