Improved javadoc comments.

jaxb-reflection/pom.xml

@@ -12,7 +12,11 @@
   <packaging>jar</packaging>
   <version>1.0-SNAPSHOT</version>
   <name>jaxb-reflection</name>
-  <url>http://maven.apache.org</url>
+
+  <scm>
+  	<url>scm:svn:https://security-automation-content-repository.googlecode.com/svn/trunk/jaxb-reflection</url>
+  </scm>
+
   <dependencies>
   	<dependency>
   		<groupId>junit</groupId>
@@ -44,4 +48,26 @@
       <artifactId>commons-lang</artifactId>
     </dependency>
   </dependencies>
+
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-compiler-plugin</artifactId>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-javadoc-plugin</artifactId>
+      </plugin>
+    </plugins>
+  </build>
+
+  <reporting>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-javadoc-plugin</artifactId>
+      </plugin>
+    </plugins>
+  </reporting>
 </project>

jaxb-reflection/src/main/java/org/scapdev/content/core/util/AnnotationUtil.java

@@ -25,8 +25,22 @@
 
 import java.lang.annotation.Annotation;
 
+/**
+ * Utility methods that support identifying annotations on a class or a super class recursively.
+ * 
+ * @author David Waltermire
+ *
+ */
 public class AnnotationUtil {
 
+	/**
+	 * Retrieves an annotation from a class or one of its super classes.
+	 * @param <A> the annotation type to retrieve
+	 * @param clazz the class to search for an annotation
+	 * @param annotationClass the annotation type to search for
+	 * @return the annotation if it exists on the class or a super class or
+	 * 		<code>null</code> if the annotation is not present
+	 */
 	public static <A extends Annotation> A getAnnotationRecursive(Class<?> clazz, Class<A> annotationClass) {
 		do {
 			A result = clazz.getAnnotation(annotationClass);
@@ -37,6 +51,15 @@ public static <A extends Annotation> A getAnnotationRecursive(Class<?> clazz, Cl
 		return null;
 	}
 
+	/**
+	 * Identifies if an annotation is present on a class or one of its super classes.
+	 * @param <A> the annotation type to identify
+	 * @param clazz the class to search for an annotation
+	 * @param annotationClass the annotation type to search for
+	 * @return <code>true</code> if the annotation exists on the class or a super class or
+	 * 		<code>false</code> if the annotation is not present
+	 * @return
+	 */
 	public static <A extends Annotation> boolean isAnnotationPresentRecursive(Class<?> clazz, Class<A> annotationClass) {
 		do {
 			if (clazz.isAnnotationPresent(annotationClass)) {

jaxb-reflection/src/main/java/org/scapdev/content/core/util/BeanUtil.java

@@ -28,30 +28,52 @@
 
 import org.scapdev.jaxb.reflection.model.JAXBModelException;
 
+/**
+ * Utility class that enables retrieval of a method on a JAXB bound class, or
+ * one of its super classes recursively, that represents an XML element or
+ * attribute.
+ * @author David Waltermire
+ *
+ */
 public class BeanUtil {
-	public static Method getPropertyGetter(Field field, Class<?> clazz, boolean recurse) throws NoSuchMethodException {
+	/**
+	 * 
+	 * @param field the Field associated with the getter using bean naming conventions
+	 * @param clazz the class to retrieve the Method from
+	 * @param recurse if <code>true</code> search super classes for methods
+	 * @return the Method associated with the field or <code>null</code> if a
+	 * 		matching Method was not found
+	 */
+	public static Method getPropertyGetter(Field field, Class<?> clazz, boolean recurse) {
 		return getPropertyGetter(field.getName(), field.getType(), clazz, recurse);
 	}
-	public static Method getPropertyGetter(String property, Class<?> fieldType, Class<?> clazz, boolean recurse) throws NoSuchMethodException {
+
+	private static Method getPropertyGetter(String property, Class<?> fieldType, Class<?> clazz, boolean recurse) {
+
+		// Build the method name
 		StringBuilder builder = new StringBuilder();
+		// if the field is a Boolean typed field, use "is" as the prefix
 		if (Boolean.class.isAssignableFrom(fieldType)) {
 			builder.append("is");
 		} else {
 			builder.append("get");
 		}
+
 		builder.append(property.substring(0, 1)
 				.toUpperCase())
 				.append(property.substring(1));
+
 		String methodName = builder.toString();
+		Method result = null;
 		do {
-			Method result;
 			try {
 				result = clazz.getDeclaredMethod(methodName);
 			} catch (SecurityException e) {
 				throw new JAXBModelException(e);
+			} catch (NoSuchMethodException e) {
+				result = null;
 			}
-			if (result != null) return result;
-		} while (recurse && (clazz = clazz.getSuperclass()) != null);
-		return null;
+		} while (result == null && recurse && (clazz = clazz.getSuperclass()) != null);
+		return result;
 	}
 }

jaxb-reflection/src/main/java/org/scapdev/jaxb/reflection/JAXBContextFactory.java

@@ -37,7 +37,16 @@
 import javax.xml.bind.JAXBException;
 
 import org.apache.log4j.Logger;
+import org.scapdev.jaxb.reflection.model.JAXBModelException;
 
+/**
+ * This factory class produces a JAXBContext and manages Java packages related
+ * to bound classes within the /META-INF/jaxb-manifest.  The contents of these
+ * files are one package name per line.
+ * 
+ * @author David Waltermire
+ *
+ */
 public class JAXBContextFactory {
 	private static Logger log = Logger.getLogger(JAXBContextFactory.class);
 	private static final ConcurrentMap<JAXBContext, ContextInfo> contextMap = new ConcurrentHashMap<JAXBContext, ContextInfo>();
@@ -49,9 +58,16 @@ public static JAXBContext getJAXBContext(ClassLoader classLoader) throws IOExcep
 	}
 
 	public static Set<String> getPackagesForContext(JAXBContext context) {
-		return contextMap.get(context).getPackages();
+		ContextInfo info = contextMap.get(context);
+		if (info == null) {
+			throw new JAXBModelException("the JAXBContext was not initialized by this factory");
+		}
+		return info.getPackages();
 	}
 
+	// TODO: this method will only find the manifest in a single jar associated
+	// with the class loader.  It might be better to allow multiple classloaders
+	// to be provided allowing multiple jars to be used.
 	private static Set<String> getContextPackages(ClassLoader classLoader) throws IOException {
 		log.info("Retrieving packages from jaxb-manifest");
 		InputStream is = classLoader.getResourceAsStream("/META-INF/jaxb-manifest");

jaxb-reflection/src/main/java/org/scapdev/jaxb/reflection/instance/visitor/DefaultInstanceVisitor.java → jaxb-reflection/src/main/java/org/scapdev/jaxb/reflection/instance/DefaultInstanceVisitor.java

@@ -21,7 +21,7 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
  ******************************************************************************/
-package org.scapdev.jaxb.reflection.instance.visitor;
+package org.scapdev.jaxb.reflection.instance;
 
 import java.lang.reflect.InvocationTargetException;
 

jaxb-reflection/src/main/java/org/scapdev/jaxb/reflection/instance/visitor/InstanceVisitable.java → jaxb-reflection/src/main/java/org/scapdev/jaxb/reflection/instance/InstanceVisitable.java

@@ -21,7 +21,7 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
  ******************************************************************************/
-package org.scapdev.jaxb.reflection.instance.visitor;
+package org.scapdev.jaxb.reflection.instance;
 
 import org.scapdev.jaxb.reflection.model.ExtendedModel;
 import org.scapdev.jaxb.reflection.model.PropertyInfo;

jaxb-reflection/src/main/java/org/scapdev/jaxb/reflection/instance/visitor/InstanceVisitor.java → jaxb-reflection/src/main/java/org/scapdev/jaxb/reflection/instance/InstanceVisitor.java

@@ -21,7 +21,7 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
  ******************************************************************************/
-package org.scapdev.jaxb.reflection.instance.visitor;
+package org.scapdev.jaxb.reflection.instance;
 
 import org.scapdev.jaxb.reflection.model.ExtendedModel;
 import org.scapdev.jaxb.reflection.model.PropertyInfo;

jaxb-reflection/src/main/java/org/scapdev/jaxb/reflection/instance/PropertyPathEvaluator.java

@@ -27,15 +27,33 @@
 import java.util.List;
 
 import org.scapdev.jaxb.reflection.model.PropertyInfo;
-
+/**
+ * @author David Waltermire
+ */
 public class PropertyPathEvaluator {
 	private PropertyPathEvaluator() {}
 
+	/**
+	 * Evaluates a property path against an instance returning the value at the
+	 * end of the path.
+	 * @param <T> the type of the PropertyInfo
+	 * @param instance the JAXB instance to evaluate
+	 * @param path the property path to follow
+	 * @return the value at the end of the property path
+	 * @throws IllegalArgumentException
+	 * @throws IllegalAccessException
+	 * @throws InvocationTargetException
+	 */
 	public static <T extends PropertyInfo> String evaluate(Object instance, List<T> path) throws IllegalArgumentException, IllegalAccessException, InvocationTargetException {
 		for (T propertyInfo : path) {
+			if (instance == null) break;
 			instance = propertyInfo.getInstance(instance);
 			instance = propertyInfo.getValue().getInstance(instance);
 		}
-		return instance.toString();
+		String retval = null;
+		if (instance != null) {
+			retval = instance.toString();
+		}
+		return retval;
 	}
 }

jaxb-reflection/src/main/java/org/scapdev/jaxb/reflection/instance/package.html

@@ -0,0 +1,8 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head></head>
+<body>
+This package supports iterating over an XML instance based on bound Java
+classes. 
+</body>
+</html>

jaxb-reflection/src/main/java/org/scapdev/jaxb/reflection/model/ListPropertyValue.java

@@ -30,7 +30,7 @@
 import java.util.Collection;
 import java.util.List;
 
-import org.scapdev.jaxb.reflection.instance.visitor.InstanceVisitor;
+import org.scapdev.jaxb.reflection.instance.InstanceVisitor;
 import org.scapdev.jaxb.reflection.model.visitor.ModelVisitor;
 
 public class ListPropertyValue implements DelegatingPropertyValue {

jaxb-reflection/src/main/java/org/scapdev/jaxb/reflection/model/ObjectPropertyValue.java

@@ -27,7 +27,7 @@
 import java.util.Collection;
 import java.util.Collections;
 
-import org.scapdev.jaxb.reflection.instance.visitor.InstanceVisitor;
+import org.scapdev.jaxb.reflection.instance.InstanceVisitor;
 import org.scapdev.jaxb.reflection.model.visitor.ModelVisitor;
 
 public class ObjectPropertyValue implements PropertyValue {

jaxb-reflection/src/main/java/org/scapdev/jaxb/reflection/model/PropertyInfo.java

@@ -31,13 +31,27 @@
 
 
 /**
- * This interface represents a property contained within a bound XML class.
+ * This interface represents an XML element or attribute property contained
+ * within a bound XML class.
+
  * @author David Waltermire
  *
  */
 public interface PropertyInfo {
+	/**
+	 * Retrieves the Java Method getter associated with the property
+	 * @return the Java Method associated with the property
+	 */
 	Method getGetter();
+	/**
+	 * Retrieves the Java Field associated with the property
+	 * @return the Java Field associated with the property
+	 */
 	Field getField();
+	/**
+	 * Retrieves the PropertyValue object directly associated with the property
+	 * @return the PropertyValue associated with the property
+	 */
 	PropertyValue getValue();
 	/**
 	 * Retrieves the TypeInfo records of the bound XML class for which this property is a member
@@ -49,8 +63,34 @@ public interface PropertyInfo {
 	 * @return the property name
 	 */
 	String getName();
+	/**
+	 * @return <code>true</code> if the property represents a bound XML
+	 * 		attribute, <code>false</code> otherwise
+	 */
 	boolean isAttribute();
+	/**
+	 * @return <code>true</code> if the property represents a bound XML
+	 * 		element, <code>false</code> otherwise
+	 */
 	boolean isElement();
+	/**
+	 * Retrieves the instance associated with the property
+	 * @param classInstance the Java object to retrieve the property value from 
+	 * @return the instance associated with the property
+	 * @throws IllegalArgumentException (from Java) when invoking a Java method
+	 * 		that is an instance method and the specified object argument is not
+	 * 		an instance of the class or interface declaring the underlying
+	 * 		method (or of a subclass or implementor thereof); if the number of
+	 * 		actual and formal parameters differ; if an unwrapping conversion for
+	 * 		primitive arguments fails; or if, after possible unwrapping, a
+	 * 		parameter value cannot be converted to the corresponding formal
+	 * 		parameter type by a method invocation conversion.
+	 * @throws IllegalAccessException (from Java) when invoking a Java method
+	 * 		object that enforces Java language access control and the underlying
+	 * 		method is inaccessible.
+	 * @throws InvocationTargetException (from Java) when invoking a Java method
+	 * 		where the underlying method throws an exception.
+ 	 */
 	Object getInstance(Object classInstance) throws IllegalArgumentException, IllegalAccessException, InvocationTargetException;
 	<T extends Annotation> T getAnnotation(Class<T> annotation);
 }

jaxb-reflection/src/main/java/org/scapdev/jaxb/reflection/model/PropertyValue.java

@@ -26,7 +26,7 @@
 import java.lang.reflect.Type;
 import java.util.Collection;
 
-import org.scapdev.jaxb.reflection.instance.visitor.InstanceVisitable;
+import org.scapdev.jaxb.reflection.instance.InstanceVisitable;
 import org.scapdev.jaxb.reflection.model.visitor.ModelVisitable;
 
 

jaxb-reflection/src/main/java/org/scapdev/jaxb/reflection/model/TypeInfoPropertyValue.java

@@ -26,7 +26,7 @@
 import java.lang.reflect.Type;
 import java.util.Collection;
 
-import org.scapdev.jaxb.reflection.instance.visitor.InstanceVisitor;
+import org.scapdev.jaxb.reflection.instance.InstanceVisitor;
 import org.scapdev.jaxb.reflection.model.visitor.ModelVisitor;
 
 public class TypeInfoPropertyValue implements PropertyValue {

jaxb-reflection/src/main/java/org/scapdev/jaxb/reflection/model/jaxb/DefaultPropertyInfo.java

@@ -79,23 +79,25 @@ public Field getField() {
 
 	public Method getGetter() {
 
-		try {
-			return BeanUtil.getPropertyGetter(field, typeInfo.getType(), true);
-		} catch (NoSuchMethodException e) {
+		Method result = BeanUtil.getPropertyGetter(field, typeInfo.getType(), true);
+		if (result == null) {
 			String name;
+			// TODO: It doesn't appear that the annotations have any impact on
+			// the name of the getter. Evaluate if this logic is doing anything.
 			if (field.isAnnotationPresent(XmlAttribute.class)) {
 				name = field.getAnnotation(XmlAttribute.class).name();
 			} else if (field.isAnnotationPresent(XmlElement.class)) {
 				name = field.getAnnotation(XmlElement.class).name();
 			} else {
-				throw(new JAXBModelException(e));
+				throw(new JAXBModelException("Unable to guess the field name"));
 			}
 			try {
-				return typeInfo.getType().getDeclaredMethod("get"+name);
+				result = typeInfo.getType().getDeclaredMethod("get"+name);
 			} catch (NoSuchMethodException e2) {
 				throw new JAXBModelException(e2);
 			}
 		}
+		return result;
 	}
 
 	public boolean isAttribute() {

jaxb-reflection/src/main/java/org/scapdev/jaxb/reflection/model/jaxb/JAXBPropertyValue.java

@@ -30,7 +30,7 @@
 
 import javax.xml.bind.JAXBElement;
 
-import org.scapdev.jaxb.reflection.instance.visitor.InstanceVisitor;
+import org.scapdev.jaxb.reflection.instance.InstanceVisitor;
 import org.scapdev.jaxb.reflection.model.DelegatingPropertyValue;
 import org.scapdev.jaxb.reflection.model.ExtendedModel;
 import org.scapdev.jaxb.reflection.model.PropertyInfo;

jaxb-reflection/src/main/java/org/scapdev/jaxb/reflection/model/jaxb/MultiJAXBPropertyValue.java

@@ -35,7 +35,7 @@
 import javax.xml.bind.annotation.XmlElementRefs;
 import javax.xml.bind.annotation.XmlElements;
 
-import org.scapdev.jaxb.reflection.instance.visitor.InstanceVisitor;
+import org.scapdev.jaxb.reflection.instance.InstanceVisitor;
 import org.scapdev.jaxb.reflection.model.ExtendedModel;
 import org.scapdev.jaxb.reflection.model.JAXBModelException;
 import org.scapdev.jaxb.reflection.model.Model;