-
Notifications
You must be signed in to change notification settings - Fork 0
/
typeutilities.xml
executable file
·169 lines (128 loc) · 6.91 KB
/
typeutilities.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="annotationutilities">
<title>Annotation and AnnotatedType Utilities</title>
<para>
Seam Solder provides a number of utilility classes to make working with Annotations and AnnotatedTypes easier.
This chapter will walk you each utility, and give you an idea of how to use it. For more detail, take a look at
the javaodoc on each class.
</para>
<section>
<title>Annotated Type Builder</title>
<para>
Seam Solder provides an <code>AnnotatedType</code> implementation that should be suitable for most
portable extensions needs. The <code>AnnotatedType</code> is created from
<code>AnnotatedTypeBuilder</code> as follows:
</para>
<programlisting role="JAVA" ><![CDATA[AnnotatedTypeBuilder builder = new AnnotatedTypeBuilder()
.readFromType(baseType,true) /* readFromType can read from an AnnotatedType or a class */
.addToClass(ModelLiteral.INSTANCE) /* add the @Model annotation */
.create();]]></programlisting>
<para>
Here we create a new builder, and initialize it using an existing <code>AnnotatedType</code>. We can then
add or remove annotations from the class, and it's members. When we have finished modifying the type, we call
<code>create()</code> to spit out a new, immutable, <code>AnnotatedType</code>.
</para>
<para>
<code>AnnotatedTypeBuilder</code> also allows you to specify a "redefinition" which can be applied to the
type, a type of member, or all members. The redefiner will receive a callback for any annotations present which
match the annotation type for which the redefinition is applied. For example, to remove the qualifier
<code>@Unique</code> from any class member and the type:
</para>
<programlisting role="JAVA" ><![CDATA[AnnotatedTypeBuilder builder = new AnnotatedTypeBuilder()
.readFromType(baseType,true)
.redefine(Unique.class, new AnnotationRedefiner<Unique>() {
public void redefine(RedefinitionContext<A> ctx) {
ctx.getAnnotationBuilder().remove(Unique.class);
}
}
.create();]]></programlisting>
</section>
<section>
<title>Annotation Instance Provider</title>
<para>
Sometimes you may need an annotation instance for an annotation whose type is not known at development time.
Seam Solder provides a <code>AnnotationInstanceProvider</code> class that can create an
<code>AnnotationLiteral</code> instance for any annotation at runtime. Annotation attributes
are passed in via a <code>Map<String,Object></code>. For example given the follow annotation:
</para>
<programlisting role="JAVA"><![CDATA[@Retention(RetentionPolicy.RUNTIME)
public @interface MultipleMembers {
int intMember();
long longMember();
short shortMember();
float floatMember();
double doubleMember();
byte byteMember();
char charMember();
boolean booleanMember();
int[] intArrayMember();
}]]></programlisting>
<para>
We can create an annotation instance as follows:
</para>
<programlisting role="JAVA"><![CDATA[/* Create a new provider */
AnnotationInstanceProvider provider = new AnnotationInstanceProvider();
/* Set the value for each of attributes */
Map<String, Object> values = new HashMap<String, Object>();
values.put("intMember", 1);
values.put("longMember", 1);
values.put("shortMember", 1);
values.put("floatMember", 0);
values.put("doubleMember", 0);
values.put("byteMember", ((byte) 1));
values.put("charMember", 'c');
values.put("booleanMember", true);
values.put("intArrayMember", new int[] { 0, 1 });
/* Generate the instance */
MultipleMembers an = provider.get(MultipleMembers.class, values);]]></programlisting>
</section>
<section>
<title>Annotation Inspector</title>
<para>
The Annotation Inspector allows you to easily discover annotations which are meta-annotated. For example:
</para>
<programlisting role="JAVA"><![CDATA[ /* Discover all annotations on type which are meta-annotated @Constraint */
Set<Annotation> constraints = AnnotationInspector.getAnnotations(type, Constraint.class);
/* Load the annotation instance for @FacesValidator the annotation may declared on the type, */
/* or, if the type has any stereotypes, on the stereotypes */
FacesValidator validator = AnnotationInspector.getAnnotation(
type,
FacesValidator.class,
true,
beanManager);]]></programlisting>
</section>
<section>
<title>Synthetic Qualifiers</title>
<para>
When developing an extension to CDI, it can be useful to detect certain injection points, or bean definitions
and based on annotations or other metadata, add qualifiers to further disambiguate the injection point or bean
definition for the CDI bean resolver. Seam Solder's synthetic qualifers can be used to easily generate and
track such qualifers.
</para>
<para>
In this example, we will create a synthetic qualifier provider, and use it to create a qualifier. The provider
will track the qualifier, and if a qualifier is requested again for the same original annotation, the same
instance will be returned.
</para>
<programlisting role="JAVA"><![CDATA[ /* Create a provider, giving it a unique namespace */
Synthetic.Provider provider = new Synthetic.Provider("com.acme");
/* Get the a synthetic qualifier for the original annotation instance */
Synthetic synthetic = provider.get(originalAnnotation);
/* Later calls with the same original annotation instance will return the same instance */
/* Alternatively, we can "get and forget" */
Synthetic synthetic2 = provider.get();]]></programlisting>
</section>
<section>
<title>Reflection Utilities</title>
<para>
Seam Solder comes with a number miscellaneous reflection utilities; these extend JDK reflection, and some
also work on CDI's Annotated metadata. See the javadoc on <code>Reflections</code> for more.
</para>
<para>
<code>InjectableMethod</code> allows an <code>AnnotatedMethod</code> to be injected with parameter values
obtained by following the CDI type safe resolution rules, as well as allowing the defautl aparameter values to
be overridden.
</para>
</section>
</chapter>