[webbeans-commits] Webbeans SVN: r370 - ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/introspector/jlr.

Author: nickarls Date: 2008-11-27 06:00:34 -0500 (Thu, 27 Nov 2008) New Revision: 370 Modified: ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/introspector/jlr/AbstractAnnotatedItem.java ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/introspector/jlr/AbstractAnnotatedMember.java ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/introspector/jlr/AbstractAnnotatedType.java ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/introspector/jlr/AnnotatedAnnotationImpl.java Log: Some javadocs/comments Modified: ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/introspector/jlr/AbstractAnnotatedItem.java =================================================================== --- ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/introspector/jlr/AbstractAnnotatedItem.java 2008-11-27 07:52:23 UTC (rev 369) +++ ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/introspector/jlr/AbstractAnnotatedItem.java 2008-11-27 11:00:34 UTC (rev 370) @@ -1,3 +1,20 @@ +/* + * JBoss, Home of Professional Open Source + * Copyright 2008, Red Hat Middleware LLC, and individual contributors + * by the @authors tag. See the copyright.txt in the distribution for a + * full listing of individual contributors. + * + * Licensed 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. + */ + package org.jboss.webbeans.introspector.jlr; import java.lang.annotation.Annotation; @@ -11,9 +28,7 @@ import java.util.Map; import java.util.Set; -import javax.webbeans.AnnotationLiteral; import javax.webbeans.BindingType; -import javax.webbeans.Stereotype; import org.jboss.webbeans.ManagerImpl; import org.jboss.webbeans.bindings.CurrentAnnotationLiteral; @@ -24,9 +39,25 @@ import com.google.common.collect.ForwardingMap; +/** + * Represents functionality common for all annotated items, mainly different + * mappings of the annotations and meta-annotations + * + * @author Pete Muir + * @author Nicklas Karlsson + * + * @param <T> + * @param <S> + * + * @see org.jboss.webbeans.introspector.AnnotatedItem + */ public abstract class AbstractAnnotatedItem<T, S> implements AnnotatedItem<T, S> { + /** + * Represents a mapping from a annotation type to an annotation + * implementation + */ public static class AnnotationMap extends ForwardingMap<Class<? extends Annotation>, Annotation> { private Map<Class<? extends Annotation>, Annotation> delegate; @@ -44,6 +75,11 @@ } + /** + * Represents a mapping from a annotation (meta-annotation) to a set of + * annotations + * + */ public static class MetaAnnotationMap extends ForwardingMap<Class<? extends Annotation>, Set<Annotation>> { private Map<Class<? extends Annotation>, Set<Annotation>> delegate; @@ -59,6 +95,16 @@ return delegate; } + /** + * Gets the set of annotations matching the given annotation type + * + * If the key is not found, an empty set is created and placed in the map + * before returned + * + * @param key The meta-annotation to match + * @returns The set of matching annotations containing this + * meta-annotation + */ @SuppressWarnings("unchecked") @Override public Set<Annotation> get(Object key) @@ -74,16 +120,33 @@ } + // The array of default binding types private static final Annotation[] DEFAULT_BINDING_ARRAY = { new CurrentAnnotationLiteral() }; + // The set of default binding types private static final Set<Annotation> DEFAULT_BINDING = new HashSet<Annotation>(Arrays.asList(DEFAULT_BINDING_ARRAY)); + // The array of meta-annotations to map private static final Annotation[] MAPPED_METAANNOTATIONS_ARRAY = {}; + // The set of meta-annotations to map private static final Set<Annotation> MAPPED_METAANNOTATIONS = new HashSet<Annotation>(Arrays.asList(MAPPED_METAANNOTATIONS_ARRAY)); + // The annotation map (annotation type -> annotation) of the item private AnnotationMap annotationMap; + // The meta-annotation map (annotation type -> set of annotations containing meta-annotation) of the item private MetaAnnotationMap metaAnnotationMap; + // The set of all annotations on the item private Set<Annotation> annotationSet; + // The array of all annotations on the item private Annotation[] annotationArray; + /** + * Constructor + * + * Also builds the meta-annotation map. Throws a NullPointerException if + * trying to register a null map + * + * @param annotationMap A map of annotation to register + * + */ public AbstractAnnotatedItem(AnnotationMap annotationMap) { if (annotationMap == null) @@ -94,6 +157,15 @@ buildMetaAnnotationMap(annotationMap); } + /** + * Build the meta-annotation map + * + * Iterates through the annotationMap values (annotations) and for each + * meta-annotation on the annotation register the annotation in the set under + * they key of the meta-annotation type. + * + * @param annotationMap The annotation map to parse + */ private void buildMetaAnnotationMap(AnnotationMap annotationMap) { metaAnnotationMap = new MetaAnnotationMap(); @@ -101,20 +173,33 @@ { for (Annotation metaAnnotation : annotation.annotationType().getAnnotations()) { -// TODO: Check with Pete how to fill the array. Make annotation literals for all? -// if (MAPPED_METAANNOTATIONS.contains(metaAnnotation)) -// { - metaAnnotationMap.get(metaAnnotation.annotationType()).add(annotation); -// } + // TODO: Check with Pete how to fill the array. Make annotation + // literals for all? + // if (MAPPED_METAANNOTATIONS.contains(metaAnnotation)) + // { + metaAnnotationMap.get(metaAnnotation.annotationType()).add(annotation); + // } } } } + /** + * Static helper method for building annotation map from an annotated element + * + * @param element The element to examine + * @return The annotation map + */ protected static AnnotationMap buildAnnotationMap(AnnotatedElement element) { return buildAnnotationMap(element.getAnnotations()); } + /** + * Builds the annotation map (annotation type -> annotation) + * + * @param annotations The array of annotations to map + * @return The annotation map + */ protected static AnnotationMap buildAnnotationMap(Annotation[] annotations) { AnnotationMap annotationMap = new AnnotationMap(); @@ -125,6 +210,14 @@ return annotationMap; } + /** + * Static helper method for getting the current parameter values from a list + * of annotated parameters. + * + * @param parameters The list of annotated parameter to look up + * @param manager The Web Beans manager + * @return The object array of looked up values + */ protected static Object[] getParameterValues(List<AnnotatedParameter<Object>> parameters, ManagerImpl manager) { Object[] parameterValues = new Object[parameters.size()]; @@ -136,17 +229,40 @@ return parameterValues; } + /** + * Gets the annotation for a given annotation type. + * + * @param annotationType the annotation type to match + * @return The annotation if found, null if no match was found + */ @SuppressWarnings("unchecked") public <A extends Annotation> A getAnnotation(Class<? extends A> annotationType) { return (A) annotationMap.get(annotationType); } + /** + * Gets the set of annotations that contain a given annotation type + * + * @param metaAnnotationType The meta-annotation type to match + * @return The set of annotations containing this meta-annotation. An empty + * set is returned if no match is found. + */ public Set<Annotation> getMetaAnnotations(Class<? extends Annotation> metaAnnotationType) { return metaAnnotationMap.get(metaAnnotationType); } + /** + * Gets (as an array) the set of annotations that contain a given annotation + * type. + * + * Populates the annotationArray if it was null + * + * @param metaAnnotationType meta-annotation type to match + * @return The array of annotations to match. An empty array is returned if + * no match is found. + */ public Annotation[] getMetaAnnotationsAsArray(Class<? extends Annotation> metaAnnotationType) { if (annotationArray == null) @@ -157,6 +273,13 @@ return annotationArray; } + /** + * Gets all annotations on this item + * + * Populates the annotationSet if it was empty + * + * @return The set of annotations on this item. + */ public Set<Annotation> getAnnotations() { if (annotationSet == null) @@ -167,16 +290,33 @@ return annotationSet; } + /** + * Checks if an annotation is present on the item + * + * @param annotatedType The annotation type to check for + * @return True if present, false otherwise. + */ public boolean isAnnotationPresent(Class<? extends Annotation> annotatedType) { return annotationMap.containsKey(annotatedType); } + /** + * Gets the annotation map + * + * @return The annotation map + */ protected AnnotationMap getAnnotationMap() { return annotationMap; } + /** + * Compares two AbstractAnnotatedItems + * + * @param other The other item + * @return True if equals, false otherwise + */ @Override public boolean equals(Object other) { @@ -188,11 +328,24 @@ return false; } + /** + * Checks if this item is assignable from another annotated item (through + * type and actual type arguments) + * + * @param that The other annotated item to check against + * @return True if assignable, false otherwise + */ public boolean isAssignableFrom(AnnotatedItem<?, ?> that) { return isAssignableFrom(that.getType(), that.getActualTypeArguments()); } + /** + * Checks if this item is assignable from any one a set of types + * + * @param types The set of types to check against + * @return True if assignable, false otherwise + */ public boolean isAssignableFrom(Set<Class<?>> types) { for (Class<?> type : types) @@ -205,17 +358,34 @@ return false; } + /** + * Helper method for doing actual assignability check + * + * @param type The type to compare against + * @param actualTypeArguments The type arguments + * @return True is assignable, false otherwise + */ private boolean isAssignableFrom(Class<?> type, Type[] actualTypeArguments) { return Types.boxedType(getType()).isAssignableFrom(Types.boxedType(type)) && Arrays.equals(getActualTypeArguments(), actualTypeArguments); } + /** + * Gets the hash code of the actual type + * + * @return The hash code + */ @Override public int hashCode() { return getType().hashCode(); } + /** + * Gets a string representation of the item + * + * @return A string representation + */ @Override public String toString() { @@ -237,6 +407,14 @@ return string; } + /** + * Gets the binding types of the item + * + * Looks at the meta-annotations map for annotations with binding type + * meta-annotation. Returns default binding (current) if none specified. + * + * @return A set of (binding type) annotations + */ public Set<Annotation> getBindingTypes() { if (getMetaAnnotations(BindingType.class).size() > 0) @@ -249,6 +427,14 @@ } } + /** + * Gets (as array) the binding types of the item + * + * Looks at the meta-annotations map for annotations with binding type + * meta-annotation. Returns default binding (current) if none specified. + * + * @return An array of (binding type) annotations + */ public Annotation[] getBindingTypesAsArray() { if (getMetaAnnotationsAsArray(BindingType.class).length > 0) @@ -261,6 +447,11 @@ } } + /** + * Indicates if the type is proxyable to a set of pre-defined rules + * + * @return True if proxyable, false otherwise. + */ public boolean isProxyable() { if (Reflections.getConstructor(getType()) == null) Modified: ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/introspector/jlr/AbstractAnnotatedMember.java =================================================================== --- ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/introspector/jlr/AbstractAnnotatedMember.java 2008-11-27 07:52:23 UTC (rev 369) +++ ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/introspector/jlr/AbstractAnnotatedMember.java 2008-11-27 11:00:34 UTC (rev 370) @@ -1,3 +1,20 @@ +/* + * JBoss, Home of Professional Open Source + * Copyright 2008, Red Hat Middleware LLC, and individual contributors + * by the @authors tag. See the copyright.txt in the distribution for a + * full listing of individual contributors. + * + * Licensed 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. + */ + package org.jboss.webbeans.introspector.jlr; import java.lang.reflect.Member; @@ -7,31 +24,65 @@ import org.jboss.webbeans.ManagerImpl; import org.jboss.webbeans.util.Reflections; +/** + * Represents an abstract annotated memeber (field, method or constructor) + * + * @author Pete Muir + * + * @param <T> + * @param <S> + */ public abstract class AbstractAnnotatedMember<T, S extends Member> extends AbstractAnnotatedItem<T, S> { - + // The name of the member private String name; + /** + * Constructor + * + * @param annotationMap The annotation map + */ public AbstractAnnotatedMember(AnnotationMap annotationMap) { super(annotationMap); } - + + /** + * Indicates if the member is static (through the delegate) + * + * @return True if static, false otherwise + */ public boolean isStatic() { return Reflections.isStatic(getDelegate()); } - + + /** + * Indicates if the member if final (through the delegate) + * + * @return True if final, false otherwise + */ public boolean isFinal() { return Reflections.isFinal(getDelegate()); } - + + /** + * Gets the current value of the member + * + * @param manager The Web Beans manager + * @return The current value + */ public T getValue(ManagerImpl manager) { return manager.getInstanceByType(getType(), getMetaAnnotationsAsArray(BindingType.class)); } - + + /** + * Gets the name of the member + * + * @returns The name (or the name of the delegate if none is defined) + */ public String getName() { if (name == null) @@ -40,5 +91,5 @@ } return name; } - + } Modified: ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/introspector/jlr/AbstractAnnotatedType.java =================================================================== --- ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/introspector/jlr/AbstractAnnotatedType.java 2008-11-27 07:52:23 UTC (rev 369) +++ ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/introspector/jlr/AbstractAnnotatedType.java 2008-11-27 11:00:34 UTC (rev 370) @@ -1,3 +1,20 @@ +/* + * JBoss, Home of Professional Open Source + * Copyright 2008, Red Hat Middleware LLC, and individual contributors + * by the @authors tag. See the copyright.txt in the distribution for a + * full listing of individual contributors. + * + * Licensed 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. + */ + package org.jboss.webbeans.introspector.jlr; import org.jboss.webbeans.introspector.AnnotatedClass; @@ -3,29 +20,61 @@ import org.jboss.webbeans.util.Reflections; +/** + * Represents an abstract annotated type + * + * @author Pete Muir + * + * @param <T> + */ public abstract class AbstractAnnotatedType<T> extends AbstractAnnotatedItem<T, Class<T>> { - + // The superclass abstraction of the type private AnnotatedClass<Object> superclass; + /** + * Constructor + * + * @param annotationMap The annotation map + */ public AbstractAnnotatedType(AnnotationMap annotationMap) { super(annotationMap); } + /** + * Indicates if the type is static (through the delegate) + * + * @return True if static, false otherwise + */ public boolean isStatic() { return Reflections.isStatic(getDelegate()); } + /** + * Indicates if the type if final (through the delegate) + * + * @return True if final, false otherwise + */ public boolean isFinal() { return Reflections.isFinal(getDelegate()); } + /** + * Gets the name of the type + * + * @returns The name (through the delegate) + */ public String getName() { return getDelegate().getName(); } + /** + * Gets the superclass abstraction of the type + * + * @return The superclass abstraction + */ @SuppressWarnings("unchecked") // TODO Fix this Modified: ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/introspector/jlr/AnnotatedAnnotationImpl.java =================================================================== --- ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/introspector/jlr/AnnotatedAnnotationImpl.java 2008-11-27 07:52:23 UTC (rev 369) +++ ri/trunk/webbeans-ri/src/main/java/org/jboss/webbeans/introspector/jlr/AnnotatedAnnotationImpl.java 2008-11-27 11:00:34 UTC (rev 370) @@ -1,3 +1,20 @@ +/* + * JBoss, Home of Professional Open Source + * Copyright 2008, Red Hat Middleware LLC, and individual contributors + * by the @authors tag. See the copyright.txt in the distribution for a + * full listing of individual contributors. + * + * Licensed 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. + */ + package org.jboss.webbeans.introspector.jlr; import java.lang.annotation.Annotation; @@ -11,26 +28,52 @@ import org.jboss.webbeans.introspector.AnnotatedAnnotation; import org.jboss.webbeans.introspector.AnnotatedMethod; +/** + * Represents an annotated annotation + * + * @author Pete Muir + * + * @param <T> + */ public class AnnotatedAnnotationImpl<T extends Annotation> extends AbstractAnnotatedType<T> implements AnnotatedAnnotation<T> { - + // The annotated members map (annotation -> member with annotation) private Map<Class<? extends Annotation>, Set<AnnotatedMethod<?>>> annotatedMembers; - + // The implementation class of the annotation private Class<T> clazz; - + // The set of abstracted members private Set<AnnotatedMethod<?>> members; - + + /** + * Constructor + * + * Initializes the superclass with the built annotation map + * + * @param annotationType The annotation type + */ public AnnotatedAnnotationImpl(Class<T> annotationType) { super(buildAnnotationMap(annotationType)); this.clazz = annotationType; } - + + /** + * Gets the actual type arguments + * + * @return The type arguments + */ public Type[] getActualTypeArguments() { return new Type[0]; } + /** + * Gets all members of the annotation + * + * Initializes the members first if they are null + * + * @return The set of abstracted members + */ public Set<AnnotatedMethod<?>> getMembers() { if (members == null) @@ -40,32 +83,55 @@ return members; } + /** + * Gets the delegate + * + * @return The delegate + */ public Class<T> getDelegate() { return clazz; } + /** + * Gets the type of the annotation + */ public Class<T> getType() { return clazz; } - + + /** + * Initializes the members + * + * Iterates through the declared members, creates abstractions of them and + * adds them to the members set + */ private void initMembers() { - this.members = new HashSet<AnnotatedMethod<?>>(); + members = new HashSet<AnnotatedMethod<?>>(); for (Method member : clazz.getDeclaredMethods()) { members.add(new AnnotatedMethodImpl<Object>(member, this)); } } + /** + * Returns the annotated members with a given annotation type + * + * If the annotated members are null, they are initialized first. + * + * @param annotationType The annotation type to match + * @return The set of abstracted members with the given annotation type + * present. An empty set is returned if no matches are found + */ public Set<AnnotatedMethod<?>> getAnnotatedMembers(Class<? extends Annotation> annotationType) { if (annotatedMembers == null) { initAnnotatedMembers(); } - + if (!annotatedMembers.containsKey(annotationType)) { return new HashSet<AnnotatedMethod<?>>(); @@ -76,6 +142,15 @@ } } + /** + * Initializes the annotated members + * + * If the members are null, the are initialized first. + * + * Iterates over the members and for each member, iterate over the + * annotations present, creating member abstractions and mapping them under + * the annotation in the annotatedMembers map. + */ private void initAnnotatedMembers() { if (members == null) @@ -95,5 +170,5 @@ } } } - + }