manual/src/docs/tutorials/howto-invocation-annotation.txt

///////////////////////////////////////////////////////////////
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
///////////////////////////////////////////////////////////////

[[howto-invocation-annotation,Use @Invocation]]
= Use @Invocation =
The @Invocation annotation is relatively unknown but can be rather powerful to use, especially when creating
libraries that needs to be flexible of what the user needs to do.

@Invocation is a different +InjectionScope+, which is a concept to tell Zest runtime where to look for the
instances to be injected. Other, more well-known, +InjectionScope+ annotations are +@This+, +@Structure+ and
+@Service+.

The +@Invocation+ injection scope can provide the following types, all related to the on-going method invocation,
which is especially useful in Generic Concerns or Generic Mixins;

    * +java.lang.reflect.Method+ - The current method being invoked.
    * +java.lang.reflect.AnnotatedElement+ - An descriptor for all annotations of the Method.
    * _Custom Annotations_ - Your own annotation type.
    * +java.util.Iterable<Method>+ - An iterable of all declared methods of the composite type.

== java.lang.reflect.Method ==
This injection will simply provide the +java.lang.reflect.Method+ of the on-going call. For generic fragments that
will be the same as the second argument in the +java.lang.reflect.InvocationHandler.invoke()+ method. Sometimes
it is useful to obtain this for typed fragment as well, to reduce names in Strings.

== java.lang.reflect.AnnotatedElement ==
This Reflection API class encapsulates the annotation aspect of any element that can be annotated. Zest implements
this interface for the Composite. That means that annotations for both the method as well as the composite is provided
through this injection.

== Custom Annotations ==
It is often useful to introduce one's own annotations, especially for libraries, and use these annotations to direct
the runtime to do different things. Many of the "built-in" features in Zest is actually done by this mechanism and
not directly implemented in the Core Runtime.

First create an annotation of your own liking, it must have +java.lang.annotation.Retention+ set to +RUNTIME+

[snippet,java]
-----------
source=core/runtime/src/test/java/org/qi4j/runtime/injection/InvocationInjectionTest.java
tag=annotation
-----------

After that it is possible to have this annotation placed on composite type methods,

[snippet,java]
-----------
source=core/runtime/src/test/java/org/qi4j/runtime/injection/InvocationInjectionTest.java
tag=declaration
-----------

and then the annotation can simply be injected into your Concerns or Mixins, like this;

[snippet,java]
-----------
source=core/runtime/src/test/java/org/qi4j/runtime/injection/InvocationInjectionTest.java
tag=use1
-----------

== java.util.Iterable<Method> ==
This injection will provide all the declared methods of the current composite. This is particularly useful for mixins
or concerns that builds information about the composite they belong to.