Adding a HowTo on @Invocation injection.
Project: http://git-wip-us.apache.org/repos/asf/zest-qi4j/repo Commit: http://git-wip-us.apache.org/repos/asf/zest-qi4j/commit/f7e0991a Tree: http://git-wip-us.apache.org/repos/asf/zest-qi4j/tree/f7e0991a Diff: http://git-wip-us.apache.org/repos/asf/zest-qi4j/diff/f7e0991a Branch: refs/heads/develop Commit: f7e0991ae6effb828509081151fe9b7c48f9982c Parents: 7c48e8a Author: Niclas Hedhman <[email protected]> Authored: Wed Jul 8 11:12:23 2015 +0300 Committer: Niclas Hedhman <[email protected]> Committed: Wed Jul 8 11:12:23 2015 +0300 ---------------------------------------------------------------------- .../injection/InvocationInjectionTest.java | 13 ++-- .../tutorials/howto-invocation-annotation.txt | 78 ++++++++++++++++++++ 2 files changed, 86 insertions(+), 5 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/f7e0991a/core/runtime/src/test/java/org/qi4j/runtime/injection/InvocationInjectionTest.java ---------------------------------------------------------------------- diff --git a/core/runtime/src/test/java/org/qi4j/runtime/injection/InvocationInjectionTest.java b/core/runtime/src/test/java/org/qi4j/runtime/injection/InvocationInjectionTest.java index 7424dc3..bf5091c 100644 --- a/core/runtime/src/test/java/org/qi4j/runtime/injection/InvocationInjectionTest.java +++ b/core/runtime/src/test/java/org/qi4j/runtime/injection/InvocationInjectionTest.java @@ -59,27 +59,29 @@ public class InvocationInjectionTest @Mixins( MyMixin.class ) @Concerns( MyConcern.class ) +// START SNIPPET: declaration public interface MyComposite extends TransientComposite { @Foo( "1" ) void doStuff(); - +// END SNIPPET: declaration void doStuff2(); @Foo( "X" ) void doStuff3(); } +// START SNIPPET: use1 public abstract static class MyConcern extends ConcernOf<MyComposite> implements MyComposite { @Invocation - Method method; - - @Invocation Foo foo; +// END SNIPPET: use1 + @Invocation + Method method; @Invocation AnnotatedElement ae; @@ -129,10 +131,11 @@ public class InvocationInjectionTest { } } - +// START SNIPPET: annotation @Retention( RUNTIME ) @interface Foo { String value(); } +// END SNIPPET: annotation } \ No newline at end of file http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/f7e0991a/manual/src/docs/tutorials/howto-invocation-annotation.txt ---------------------------------------------------------------------- diff --git a/manual/src/docs/tutorials/howto-invocation-annotation.txt b/manual/src/docs/tutorials/howto-invocation-annotation.txt new file mode 100644 index 0000000..454c46a --- /dev/null +++ b/manual/src/docs/tutorials/howto-invocation-annotation.txt @@ -0,0 +1,78 @@ +/////////////////////////////////////////////////////////////// + * 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]] += How to use @Invocation annotation = +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 difference +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 a annotation of your own liking, and 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 method of the current composite. This is particularly useful for mixins +or concerns that builds information about the composite they belong to. \ No newline at end of file
