You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@polygene.apache.org by ni...@apache.org on 2015/07/08 10:15:13 UTC
[3/6] zest-qi4j git commit: Adding a HowTo on @Invocation injection.
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 <he...@betfair.com>
Authored: Wed Jul 8 11:12:23 2015 +0300
Committer: Niclas Hedhman <he...@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