polygene-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From nic...@apache.org
Subject [3/6] zest-qi4j git commit: Adding a HowTo on @Invocation injection.
Date Wed, 08 Jul 2015 08:15:13 GMT
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 <hedmann@betfair.com>
Authored: Wed Jul 8 11:12:23 2015 +0300
Committer: Niclas Hedhman <hedmann@betfair.com>
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


Mime
View raw message