updates to reflection library (largely javadoc, but with a few small tweaks)

29 files changed, 784 insertions, 165 deletions

diff --git a/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/AdviceImpl.java b/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/AdviceImpl.java
index d46b0bf61..7bfba4ca1 100644
--- a/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/AdviceImpl.java
+++ b/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/AdviceImpl.java
@@ -15,7 +15,9 @@ import java.lang.reflect.Method;
 
 import org.aspectj.lang.annotation.AdviceName;
 import org.aspectj.lang.reflect.Advice;
-import org.aspectj.lang.reflect.AdviceType;
+import org.aspectj.lang.reflect.AdviceKind;
+import org.aspectj.lang.reflect.AjType;
+import org.aspectj.lang.reflect.AjTypeSystem;
 import org.aspectj.lang.reflect.PointcutExpression;
 
 /**
@@ -24,17 +26,21 @@ import org.aspectj.lang.reflect.PointcutExpression;
  */
 public class AdviceImpl implements Advice {
 
-	private final AdviceType kind;
+	private final AdviceKind kind;
 	private final Method adviceMethod;
 	private PointcutExpression pointcutExpression;
 	
-	protected AdviceImpl(Method method, String pointcut, AdviceType type) {
+	protected AdviceImpl(Method method, String pointcut, AdviceKind type) {
 		this.kind = type;
 		this.adviceMethod = method;
 		this.pointcutExpression = new PointcutExpressionImpl(pointcut);
 	}
 	
-	public AdviceType getKind() {
+	public AjType getDeclaringType() {
+		return AjTypeSystem.getAjType(adviceMethod.getDeclaringClass());
+	}
+	
+	public AdviceKind getKind() {
 		return kind;
 	}
 	
diff --git a/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/AjTypeImpl.java b/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/AjTypeImpl.java
index 71c6c7488..bb5faf655 100644
--- a/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/AjTypeImpl.java
+++ b/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/AjTypeImpl.java
@@ -35,7 +35,7 @@ import org.aspectj.lang.annotation.Before;
 import org.aspectj.lang.annotation.DeclareError;
 import org.aspectj.lang.annotation.DeclareWarning;
 import org.aspectj.lang.reflect.Advice;
-import org.aspectj.lang.reflect.AdviceType;
+import org.aspectj.lang.reflect.AdviceKind;
 import org.aspectj.lang.reflect.AjType;
 import org.aspectj.lang.reflect.AjTypeSystem;
 import org.aspectj.lang.reflect.DeclareAnnotation;
@@ -88,8 +88,9 @@ public class AjTypeImpl<T> implements AjType<T> {
 	/* (non-Javadoc)
 	 * @see org.aspectj.lang.reflect.AjType#getInterfaces()
 	 */
-	public Class[] getInterfaces() {
-		return clazz.getInterfaces();
+	public AjType<?>[] getInterfaces() {
+		Class<?>[] baseInterfaces = clazz.getInterfaces();
+		return toAjTypeArray(baseInterfaces);
 	}
 
 	/* (non-Javadoc)
@@ -98,11 +99,15 @@ public class AjTypeImpl<T> implements AjType<T> {
 	public int getModifiers() {
 		return clazz.getModifiers();
 	}
+	
+	public Class<T> getJavaClass() {
+		return clazz;
+	}
 
 	/* (non-Javadoc)
 	 * @see org.aspectj.lang.reflect.AjType#getSupertype()
 	 */
-	public AjType getSupertype() {
+	public AjType<?> getSupertype() {
 		return new AjTypeImpl(clazz.getSuperclass());
 	}
 
@@ -130,7 +135,7 @@ public class AjTypeImpl<T> implements AjType<T> {
 	/* (non-Javadoc)
 	 * @see org.aspectj.lang.reflect.AjType#getEnclosingType()
 	 */
-	public AjType getEnclosingType() {
+	public AjType<?> getEnclosingType() {
 		Class<?> enc = clazz.getEnclosingClass();
 		return enc != null ? new AjTypeImpl(enc) : null;
 	}
@@ -138,7 +143,7 @@ public class AjTypeImpl<T> implements AjType<T> {
 	/* (non-Javadoc)
 	 * @see org.aspectj.lang.reflect.AjType#getDeclaringType()
 	 */
-	public AjType getDeclaringType() {
+	public AjType<?> getDeclaringType() {
 		Class dec = clazz.getDeclaringClass();
 		return dec != null ? new AjTypeImpl(dec) : null;
 	}
@@ -148,17 +153,20 @@ public class AjTypeImpl<T> implements AjType<T> {
 			Aspect aspectAnn = clazz.getAnnotation(Aspect.class);
 			String perClause = aspectAnn.value();
 			if (perClause.equals("")) {
-				return new PerClauseImpl(PerClauseKind.SINGLETON,"");
+				if (getSupertype().isAspect()) {
+					return getSupertype().getPerClause();
+				} 
+				return new PerClauseImpl(PerClauseKind.SINGLETON);
 			} else if (perClause.startsWith("perthis(")) {
-				return new PerClauseImpl(PerClauseKind.PERTHIS,perClause.substring("perthis(".length(),perClause.length() - 1));
+				return new PointcutBasedPerClauseImpl(PerClauseKind.PERTHIS,perClause.substring("perthis(".length(),perClause.length() - 1));
 			} else if (perClause.startsWith("pertarget(")) {
-				return new PerClauseImpl(PerClauseKind.PERTARGET,perClause.substring("pertarget(".length(),perClause.length() - 1));				
+				return new PointcutBasedPerClauseImpl(PerClauseKind.PERTARGET,perClause.substring("pertarget(".length(),perClause.length() - 1));				
 			} else if (perClause.startsWith("percflow(")) {
-				return new PerClauseImpl(PerClauseKind.PERCFLOW,perClause.substring("percflow(".length(),perClause.length() - 1));								
+				return new PointcutBasedPerClauseImpl(PerClauseKind.PERCFLOW,perClause.substring("percflow(".length(),perClause.length() - 1));								
 			} else if (perClause.startsWith("percflowbelow(")) {
-				return new PerClauseImpl(PerClauseKind.PERCFLOWBELOW,perClause.substring("percflowbelow(".length(),perClause.length() - 1));
+				return new PointcutBasedPerClauseImpl(PerClauseKind.PERCFLOWBELOW,perClause.substring("percflowbelow(".length(),perClause.length() - 1));
 			} else if (perClause.startsWith("pertypewithin")) {
-				return new PerClauseImpl(PerClauseKind.PERTYPEWITHIN,perClause.substring("pertypewithin(".length(),perClause.length() - 1));				
+				return new TypePatternBasedPerClauseImpl(PerClauseKind.PERTYPEWITHIN,perClause.substring("pertypewithin(".length(),perClause.length() - 1));				
 			} else {
 				throw new IllegalStateException("Per-clause not recognized: " + perClause);
 			}
@@ -195,32 +203,24 @@ public class AjTypeImpl<T> implements AjType<T> {
 	/* (non-Javadoc)
 	 * @see org.aspectj.lang.reflect.AjType#getAspects()
 	 */
-	public AjType[] getAjTypes() {
+	public AjType<?>[] getAjTypes() {
 		Class[] classes = clazz.getClasses();
-		AjType[] ret = new AjType[classes.length];
-		for (int i = 0; i < ret.length; i++) {
-			ret[i] = new AjTypeImpl(classes[i]);
-		}
-		return ret;
+		return toAjTypeArray(classes);
 	}
 
 	/* (non-Javadoc)
 	 * @see org.aspectj.lang.reflect.AjType#getDeclaredAspects()
 	 */
-	public AjType[] getDeclaredAjTypes() {
+	public AjType<?>[] getDeclaredAjTypes() {
 		Class[] classes = clazz.getDeclaredClasses();
-		AjType[] ret = new AjType[classes.length];
-		for (int i = 0; i < ret.length; i++) {
-			ret[i] = new AjTypeImpl(classes[i]);
-		}
-		return ret;
+		return toAjTypeArray(classes);
 	}
 
 	/* (non-Javadoc)
 	 * @see org.aspectj.lang.reflect.AjType#getConstructor(java.lang.Class...)
 	 */
-	public Constructor getConstructor(Class... parameterTypes) throws NoSuchMethodException {
-		return clazz.getConstructor(parameterTypes);
+	public Constructor getConstructor(AjType<?>... parameterTypes) throws NoSuchMethodException {
+		return clazz.getConstructor(toClassArray(parameterTypes));
 	}
 
 	/* (non-Javadoc)
@@ -233,8 +233,8 @@ public class AjTypeImpl<T> implements AjType<T> {
 	/* (non-Javadoc)
 	 * @see org.aspectj.lang.reflect.AjType#getDeclaredConstructor(java.lang.Class...)
 	 */
-	public Constructor getDeclaredConstructor(Class... parameterTypes) throws NoSuchMethodException {
-		return clazz.getDeclaredConstructor(parameterTypes);
+	public Constructor getDeclaredConstructor(AjType<?>... parameterTypes) throws NoSuchMethodException {
+		return clazz.getDeclaredConstructor(toClassArray(parameterTypes));
 	}
 
 	/* (non-Javadoc)
@@ -274,7 +274,7 @@ public class AjTypeImpl<T> implements AjType<T> {
 	 * @see org.aspectj.lang.reflect.AjType#getField(java.lang.String)
 	 */
 	public Field getField(String name)  throws NoSuchFieldException {
-		Field f =  clazz.getDeclaredField(name);
+		Field f =  clazz.getField(name);
 		if (f.getName().startsWith(ajcMagic)) throw new NoSuchFieldException(name);
 		return f;
 	}
@@ -299,8 +299,8 @@ public class AjTypeImpl<T> implements AjType<T> {
 	/* (non-Javadoc)
 	 * @see org.aspectj.lang.reflect.AjType#getDeclaredMethod(java.lang.String, java.lang.Class...)
 	 */
-	public Method getDeclaredMethod(String name, Class... parameterTypes) throws NoSuchMethodException {
-		Method m =  clazz.getDeclaredMethod(name,parameterTypes);
+	public Method getDeclaredMethod(String name, AjType<?>... parameterTypes) throws NoSuchMethodException {
+		Method m =  clazz.getDeclaredMethod(name,toClassArray(parameterTypes));
 		if (!isReallyAMethod(m)) throw new NoSuchMethodException(name);
 		return m;
 	}
@@ -308,8 +308,8 @@ public class AjTypeImpl<T> implements AjType<T> {
 	/* (non-Javadoc)
 	 * @see org.aspectj.lang.reflect.AjType#getMethod(java.lang.String, java.lang.Class...)
 	 */
-	public Method getMethod(String name, Class... parameterTypes) throws NoSuchMethodException {
-		Method m =  clazz.getMethod(name,parameterTypes);
+	public Method getMethod(String name, AjType<?>... parameterTypes) throws NoSuchMethodException {
+		Method m =  clazz.getMethod(name,toClassArray(parameterTypes));
 		if (!isReallyAMethod(m)) throw new NoSuchMethodException(name);
 		return m;
 	}
@@ -367,7 +367,7 @@ public class AjTypeImpl<T> implements AjType<T> {
 	 * @see org.aspectj.lang.reflect.AjType#getPointcut(java.lang.String)
 	 */
 	public Pointcut getPointcut(String name) throws NoSuchPointcutException {
-		Pointcut[] pcs = getDeclaredPointcuts();
+		Pointcut[] pcs = getPointcuts();
 		for (Pointcut pc : pcs)
 			if (pc.getName().equals(name)) return pc;
 		throw new NoSuchPointcutException(name);
@@ -425,23 +425,23 @@ public class AjTypeImpl<T> implements AjType<T> {
 	}
 	
 	
-	public Advice[] getDeclaredAdvice(AdviceType... ofType) {
-		Set<AdviceType> types;
+	public Advice[] getDeclaredAdvice(AdviceKind... ofType) {
+		Set<AdviceKind> types;
 		if (ofType.length == 0) {
-			types = EnumSet.allOf(AdviceType.class);
+			types = EnumSet.allOf(AdviceKind.class);
 		} else {
-			types = EnumSet.noneOf(AdviceType.class);
+			types = EnumSet.noneOf(AdviceKind.class);
 			types.addAll(Arrays.asList(ofType));
 		}
 		return getDeclaredAdvice(types);
 	}
 	
-	public Advice[] getAdvice(AdviceType... ofType) {
-		Set<AdviceType> types;
+	public Advice[] getAdvice(AdviceKind... ofType) {
+		Set<AdviceKind> types;
 		if (ofType.length == 0) {
-			types = EnumSet.allOf(AdviceType.class);
+			types = EnumSet.allOf(AdviceKind.class);
 		} else {
-			types = EnumSet.noneOf(AdviceType.class);
+			types = EnumSet.noneOf(AdviceKind.class);
 			types.addAll(Arrays.asList(ofType));
 		}
 		return getAdvice(types);
@@ -487,7 +487,7 @@ public class AjTypeImpl<T> implements AjType<T> {
 	}
 
 	private void initAdvice() {
-		Method[] methods = clazz.getDeclaredMethods();
+		Method[] methods = clazz.getMethods();
 		List<Advice> adviceList = new ArrayList<Advice>();
 		for (Method method : methods) {
 			Advice advice = asAdvice(method);
@@ -519,23 +519,23 @@ public class AjTypeImpl<T> implements AjType<T> {
 	private Advice asAdvice(Method method) {
 		if (method.getAnnotations().length == 0) return null;
 		Before beforeAnn = method.getAnnotation(Before.class);
-		if (beforeAnn != null) return new AdviceImpl(method,beforeAnn.value(),AdviceType.BEFORE);
+		if (beforeAnn != null) return new AdviceImpl(method,beforeAnn.value(),AdviceKind.BEFORE);
 		After afterAnn = method.getAnnotation(After.class);
-		if (afterAnn != null) return new AdviceImpl(method,afterAnn.value(),AdviceType.AFTER);
+		if (afterAnn != null) return new AdviceImpl(method,afterAnn.value(),AdviceKind.AFTER);
 		AfterReturning afterReturningAnn = method.getAnnotation(AfterReturning.class);
 		if (afterReturningAnn != null) {
 			String pcExpr = afterReturningAnn.pointcut();
 			if (pcExpr.equals("")) pcExpr = afterReturningAnn.value();
-			return new AdviceImpl(method,pcExpr,AdviceType.AFTER_RETURNING);
+			return new AdviceImpl(method,pcExpr,AdviceKind.AFTER_RETURNING);
 		}
 		AfterThrowing afterThrowingAnn = method.getAnnotation(AfterThrowing.class);
 		if (afterThrowingAnn != null) {
 			String pcExpr = afterThrowingAnn.pointcut();
 			if (pcExpr == null) pcExpr = afterThrowingAnn.value();
-			return new AdviceImpl(method,pcExpr,AdviceType.AFTER_THROWING);
+			return new AdviceImpl(method,pcExpr,AdviceKind.AFTER_THROWING);
 		}
 		Around aroundAnn = method.getAnnotation(Around.class);
-		if (aroundAnn != null) return new AdviceImpl(method,aroundAnn.value(),AdviceType.AROUND);
+		if (aroundAnn != null) return new AdviceImpl(method,aroundAnn.value(),AdviceKind.AROUND);
 		return null;
 	}
 	
@@ -543,7 +543,7 @@ public class AjTypeImpl<T> implements AjType<T> {
 	 * @see org.aspectj.lang.reflect.AjType#getDeclaredITDMethod(java.lang.String, java.lang.Class, java.lang.Class...)
 	 */
 	public InterTypeMethodDeclaration getDeclaredITDMethod(String name,
-			Class target, Class... parameterTypes) {
+			AjType<?> target, AjType<?>... parameterTypes) {
 		// TODO Auto-generated method stub
 		return null;
 	}
@@ -559,8 +559,8 @@ public class AjTypeImpl<T> implements AjType<T> {
 	/* (non-Javadoc)
 	 * @see org.aspectj.lang.reflect.AjType#getITDMethod(java.lang.String, java.lang.Class, java.lang.Class...)
 	 */
-	public InterTypeMethodDeclaration getITDMethod(String name, Class target,
-			Class... parameterTypes) {
+	public InterTypeMethodDeclaration getITDMethod(String name, AjType<?> target,
+			AjType<?>... parameterTypes) {
 		// TODO Auto-generated method stub
 		return null;
 	}
@@ -577,7 +577,7 @@ public class AjTypeImpl<T> implements AjType<T> {
 	 * @see org.aspectj.lang.reflect.AjType#getDeclaredITDConstructor(java.lang.Class, java.lang.Class...)
 	 */
 	public InterTypeConstructorDeclaration getDeclaredITDConstructor(
-			Class target, Class... parameterTypes) {
+			AjType<?> target, AjType<?>... parameterTypes) {
 		// TODO Auto-generated method stub
 		return null;
 	}
@@ -593,8 +593,8 @@ public class AjTypeImpl<T> implements AjType<T> {
 	/* (non-Javadoc)
 	 * @see org.aspectj.lang.reflect.AjType#getITDConstructor(java.lang.Class, java.lang.Class...)
 	 */
-	public InterTypeConstructorDeclaration getITDConstructor(Class target,
-			Class... parameterTypes) {
+	public InterTypeConstructorDeclaration getITDConstructor(AjType<?> target,
+			AjType<?>... parameterTypes) {
 		// TODO Auto-generated method stub
 		return null;
 	}
@@ -611,7 +611,7 @@ public class AjTypeImpl<T> implements AjType<T> {
 	 * @see org.aspectj.lang.reflect.AjType#getDeclaredITDField(java.lang.String, java.lang.Class)
 	 */
 	public InterTypeFieldDeclaration getDeclaredITDField(String name,
-			Class target) {
+			AjType<?> target) {
 		// TODO Auto-generated method stub
 		return null;
 	}
@@ -627,7 +627,7 @@ public class AjTypeImpl<T> implements AjType<T> {
 	/* (non-Javadoc)
 	 * @see org.aspectj.lang.reflect.AjType#getITDField(java.lang.String, java.lang.Class)
 	 */
-	public InterTypeFieldDeclaration getITDField(String name, Class target) {
+	public InterTypeFieldDeclaration getITDField(String name, AjType<?> target) {
 		// TODO Auto-generated method stub
 		return null;
 	}
@@ -651,14 +651,14 @@ public class AjTypeImpl<T> implements AjType<T> {
 					 DeclareWarning dw = field.getAnnotation(DeclareWarning.class);
 					 if (Modifier.isPublic(field.getModifiers()) && Modifier.isStatic(field.getModifiers())) {
 						 String message = (String) field.get(null);
-						 DeclareErrorOrWarningImpl deow = new DeclareErrorOrWarningImpl(dw.value(),message,false);
+						 DeclareErrorOrWarningImpl deow = new DeclareErrorOrWarningImpl(dw.value(),message,false,this);
 						 deows.add(deow);
 					 } 
 				} else if (field.isAnnotationPresent(DeclareError.class)) {
 					 DeclareError de = field.getAnnotation(DeclareError.class);
 					 if (Modifier.isPublic(field.getModifiers()) && Modifier.isStatic(field.getModifiers())) {
 						 String message = (String) field.get(null);
-						 DeclareErrorOrWarningImpl deow = new DeclareErrorOrWarningImpl(de.value(),message,true);
+						 DeclareErrorOrWarningImpl deow = new DeclareErrorOrWarningImpl(de.value(),message,true,this);
 						 deows.add(deow);
 					 } 				
 				}
@@ -671,7 +671,7 @@ public class AjTypeImpl<T> implements AjType<T> {
 		for (Method method : clazz.getDeclaredMethods()) {
 			if (method.isAnnotationPresent(ajcDeclareEoW.class)) {
 				ajcDeclareEoW deowAnn = method.getAnnotation(ajcDeclareEoW.class);
-				DeclareErrorOrWarning deow = new DeclareErrorOrWarningImpl(deowAnn.pointcut(),deowAnn.message(),deowAnn.isError());
+				DeclareErrorOrWarning deow = new DeclareErrorOrWarningImpl(deowAnn.pointcut(),deowAnn.message(),deowAnn.isError(),this);
 				deows.add(deow);
 			}
 		}
@@ -803,5 +803,21 @@ public class AjTypeImpl<T> implements AjType<T> {
 	public int hashCode() {
 		return clazz.hashCode();
 	}
+	
+	private AjType<?>[] toAjTypeArray(Class<?>[] classes) {
+		AjType<?>[] ajtypes = new AjType<?>[classes.length];
+		for (int i = 0; i < ajtypes.length; i++) {
+			ajtypes[i] = AjTypeSystem.getAjType(classes[i]);
+		}
+		return ajtypes;
+	}
+	
+	private Class<?>[] toClassArray(AjType<?>[] ajTypes) {
+		Class<?>[] classes = new Class<?>[ajTypes.length];
+		for (int i = 0; i < classes.length; i++) {
+			classes[i] = ajTypes[i].getJavaClass();
+		}
+		return classes;
+	}
 
 }
diff --git a/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/DeclareErrorOrWarningImpl.java b/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/DeclareErrorOrWarningImpl.java
index 03ea6d40c..f474698ea 100644
--- a/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/DeclareErrorOrWarningImpl.java
+++ b/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/DeclareErrorOrWarningImpl.java
@@ -11,6 +11,7 @@
  * ******************************************************************/
 package org.aspectj.internal.lang.reflect;
 
+import org.aspectj.lang.reflect.AjType;
 import org.aspectj.lang.reflect.DeclareErrorOrWarning;
 import org.aspectj.lang.reflect.PointcutExpression;
 
@@ -23,13 +24,17 @@ public class DeclareErrorOrWarningImpl implements DeclareErrorOrWarning {
 	private PointcutExpression pc;
 	private String msg;
 	private boolean isError;
+	private AjType declaringType;
 	
-	public DeclareErrorOrWarningImpl(String pointcut, String message, boolean isError) {
+	public DeclareErrorOrWarningImpl(String pointcut, String message, boolean isError, AjType decType) {
 		this.pc = new PointcutExpressionImpl(pointcut);
 		this.msg = message;
 		this.isError = isError;
+		this.declaringType = decType;
 	}
 	
+	public AjType getDeclaringType() { return this.declaringType; }
+	
 	/* (non-Javadoc)
 	 * @see org.aspectj.lang.reflect.DeclareErrorOrWarning#getPointcutExpression()
 	 */
diff --git a/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/PerClauseImpl.java b/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/PerClauseImpl.java
index 819d044bf..779e3a46e 100644
--- a/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/PerClauseImpl.java
+++ b/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/PerClauseImpl.java
@@ -13,7 +13,6 @@ package org.aspectj.internal.lang.reflect;
 
 import org.aspectj.lang.reflect.PerClause;
 import org.aspectj.lang.reflect.PerClauseKind;
-import org.aspectj.lang.reflect.PointcutExpression;
 
 /**
  * @author colyer
@@ -22,11 +21,9 @@ import org.aspectj.lang.reflect.PointcutExpression;
 public class PerClauseImpl implements PerClause {
 
 	private final PerClauseKind kind;
-	private final PointcutExpression pointcutExpression;
 	
-	protected PerClauseImpl(PerClauseKind kind, String pointcutExpression) {
+	protected PerClauseImpl(PerClauseKind kind) {
 		this.kind = kind;
-		this.pointcutExpression = new PointcutExpressionImpl(pointcutExpression);
 	}
 	
 	/* (non-Javadoc)
@@ -36,11 +33,4 @@ public class PerClauseImpl implements PerClause {
 		return kind;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.PerClause#getPointcutExpression()
-	 */
-	public PointcutExpression getPointcutExpression() {
-		return pointcutExpression;
-	}
-
 }
diff --git a/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/PointcutBasedPerClauseImpl.java b/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/PointcutBasedPerClauseImpl.java
new file mode 100644
index 000000000..3e3eb2f8e
--- /dev/null
+++ b/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/PointcutBasedPerClauseImpl.java
@@ -0,0 +1,37 @@
+/* *******************************************************************
+ * Copyright (c) 2005 Contributors.
+ * All rights reserved. 
+ * This program and the accompanying materials are made available 
+ * under the terms of the Eclipse Public License v1.0 
+ * which accompanies this distribution and is available at 
+ * http://eclipse.org/legal/epl-v10.html 
+ *  
+ * Contributors: 
+ *   Adrian Colyer			Initial implementation
+ * ******************************************************************/
+package org.aspectj.internal.lang.reflect;
+
+import org.aspectj.lang.reflect.PerClauseKind;
+import org.aspectj.lang.reflect.PointcutBasedPerClause;
+import org.aspectj.lang.reflect.PointcutExpression;
+
+/**
+ * @author colyer
+ *
+ */
+public class PointcutBasedPerClauseImpl extends PerClauseImpl implements
+		PointcutBasedPerClause {
+
+	private final PointcutExpression pointcutExpression;
+
+	public PointcutBasedPerClauseImpl(PerClauseKind kind,
+			String pointcutExpression) {
+		super(kind);
+		this.pointcutExpression = new PointcutExpressionImpl(pointcutExpression);
+	}
+	
+	public PointcutExpression getPointcutExpression() {
+		return pointcutExpression;
+	}
+
+}
diff --git a/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/PointcutExpressionImpl.java b/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/PointcutExpressionImpl.java
index e31bd1949..facf7d99d 100644
--- a/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/PointcutExpressionImpl.java
+++ b/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/PointcutExpressionImpl.java
@@ -24,7 +24,9 @@ public class PointcutExpressionImpl implements PointcutExpression {
 		this.expression = aPointcutExpression;
 	}
 	
-	public String toString() {
+	public String asString() {
 		return expression;
 	}
+	
+	public String toString() { return asString(); }
 }
diff --git a/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/PointcutImpl.java b/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/PointcutImpl.java
index defae8c59..63c8764a3 100644
--- a/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/PointcutImpl.java
+++ b/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/PointcutImpl.java
@@ -15,6 +15,7 @@ import java.lang.reflect.Method;
 import java.util.StringTokenizer;
 
 import org.aspectj.lang.reflect.AjType;
+import org.aspectj.lang.reflect.AjTypeSystem;
 import org.aspectj.lang.reflect.Pointcut;
 import org.aspectj.lang.reflect.PointcutExpression;
 
@@ -53,8 +54,13 @@ public class PointcutImpl implements Pointcut {
 		return baseMethod.getModifiers();
 	}
 
-	public Class<?>[] getParameterTypes() {
-		return baseMethod.getParameterTypes();
+	public AjType<?>[] getParameterTypes() {
+		Class<?>[] baseParamTypes =  baseMethod.getParameterTypes();
+		AjType<?>[] ajParamTypes = new AjType<?>[baseParamTypes.length];
+		for (int i = 0; i < ajParamTypes.length; i++) {
+			ajParamTypes[i] = AjTypeSystem.getAjType(baseParamTypes[i]);
+		}
+		return ajParamTypes;
 	}
 
 	public AjType getDeclaringType() {
diff --git a/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/SignaturePatternImpl.java b/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/SignaturePatternImpl.java
new file mode 100644
index 000000000..9820667d8
--- /dev/null
+++ b/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/SignaturePatternImpl.java
@@ -0,0 +1,37 @@
+/* *******************************************************************
+ * Copyright (c) 2005 Contributors.
+ * All rights reserved. 
+ * This program and the accompanying materials are made available 
+ * under the terms of the Eclipse Public License v1.0 
+ * which accompanies this distribution and is available at 
+ * http://eclipse.org/legal/epl-v10.html 
+ *  
+ * Contributors: 
+ *   Adrian Colyer			Initial implementation
+ * ******************************************************************/
+package org.aspectj.internal.lang.reflect;
+
+import org.aspectj.lang.reflect.SignaturePattern;
+
+/**
+ * Basic implementation of signature pattern
+ *
+ */
+public class SignaturePatternImpl implements SignaturePattern {
+
+	private String sigPattern;
+	
+	public SignaturePatternImpl(String pattern) {
+		this.sigPattern = pattern;
+	}
+
+	/* (non-Javadoc)
+	 * @see org.aspectj.lang.reflect.SignaturePattern#asString()
+	 */
+	public String asString() {
+		return sigPattern;
+	}
+	
+	public String toString() { return asString(); }
+
+}
diff --git a/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/TypePatternBasedPerClauseImpl.java b/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/TypePatternBasedPerClauseImpl.java
new file mode 100644
index 000000000..df80a0e08
--- /dev/null
+++ b/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/TypePatternBasedPerClauseImpl.java
@@ -0,0 +1,39 @@
+/* *******************************************************************
+ * Copyright (c) 2005 Contributors.
+ * All rights reserved. 
+ * This program and the accompanying materials are made available 
+ * under the terms of the Eclipse Public License v1.0 
+ * which accompanies this distribution and is available at 
+ * http://eclipse.org/legal/epl-v10.html 
+ *  
+ * Contributors: 
+ *   Adrian Colyer			Initial implementation
+ * ******************************************************************/
+package org.aspectj.internal.lang.reflect;
+
+import org.aspectj.lang.reflect.PerClauseKind;
+import org.aspectj.lang.reflect.TypePattern;
+import org.aspectj.lang.reflect.TypePatternBasedPerClause;
+
+/**
+ * @author colyer
+ *
+ */
+public class TypePatternBasedPerClauseImpl extends PerClauseImpl implements
+		TypePatternBasedPerClause {
+
+	private TypePattern typePattern;
+
+	public TypePatternBasedPerClauseImpl(PerClauseKind kind, String pattern) {
+		super(kind);
+		this.typePattern = new TypePatternImpl(pattern);
+	}
+
+	/* (non-Javadoc)
+	 * @see org.aspectj.lang.reflect.TypePatternBasedPerClause#getTypePattern()
+	 */
+	public TypePattern getTypePattern() {
+		return this.typePattern;
+	}
+
+}
diff --git a/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/TypePatternImpl.java b/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/TypePatternImpl.java
new file mode 100644
index 000000000..9973ed3bf
--- /dev/null
+++ b/aspectj5rt/java5-src/org/aspectj/internal/lang/reflect/TypePatternImpl.java
@@ -0,0 +1,37 @@
+/* *******************************************************************
+ * Copyright (c) 2005 Contributors.
+ * All rights reserved. 
+ * This program and the accompanying materials are made available 
+ * under the terms of the Eclipse Public License v1.0 
+ * which accompanies this distribution and is available at 
+ * http://eclipse.org/legal/epl-v10.html 
+ *  
+ * Contributors: 
+ *   Adrian Colyer			Initial implementation
+ * ******************************************************************/
+package org.aspectj.internal.lang.reflect;
+
+import org.aspectj.lang.reflect.TypePattern;
+
+/**
+ * Default impl of a type pattern.
+ *
+ */
+public class TypePatternImpl implements TypePattern {
+
+	private String typePattern;
+	
+	public TypePatternImpl(String pattern) {
+		this.typePattern = pattern;
+	}
+
+	/* (non-Javadoc)
+	 * @see org.aspectj.lang.reflect.TypePattern#asString()
+	 */
+	public String asString() {
+		return this.typePattern;
+	}
+	
+	public String toString() { return asString(); }
+
+}
diff --git a/aspectj5rt/java5-src/org/aspectj/lang/reflect/Advice.java b/aspectj5rt/java5-src/org/aspectj/lang/reflect/Advice.java
index 4792a3ba9..581c5a5fb 100644
--- a/aspectj5rt/java5-src/org/aspectj/lang/reflect/Advice.java
+++ b/aspectj5rt/java5-src/org/aspectj/lang/reflect/Advice.java
@@ -11,11 +11,32 @@
  * ******************************************************************/
 package org.aspectj.lang.reflect;
 
+/**
+ * Runtime representation of an advice declaration inside an aspect
+ */
 public interface Advice {
 
-	AdviceType getKind();
+	/**
+	 * The declaring aspect
+	 */
+	AjType getDeclaringType();
 	
+	/**
+	 * The kind of advice (before, after-returning, after-throwing, etc.)
+	 */
+	AdviceKind getKind();
+	
+	/**
+	 * Returns the advice name, or the empty string if the advice is anonymous.
+	 * If using the @AspectJ annotations, the advice name is the name of the
+	 * annotated advice method. If using the code style, the advice is
+	 * anonymous, unless the advice is annotated with the @AdviceName annotation,
+	 * in which case the name given in the annotation is returned. 
+	 */
 	String getName();
 	
+	/**
+	 * The pointcut expression associated with the advice declaration.
+	 */
 	PointcutExpression getPointcutExpression();
 }
diff --git a/aspectj5rt/java5-src/org/aspectj/lang/reflect/AdviceType.java b/aspectj5rt/java5-src/org/aspectj/lang/reflect/AdviceKind.java
index 541334853..82351db88 100644
--- a/aspectj5rt/java5-src/org/aspectj/lang/reflect/AdviceType.java
+++ b/aspectj5rt/java5-src/org/aspectj/lang/reflect/AdviceKind.java
@@ -12,10 +12,9 @@
 package org.aspectj.lang.reflect;
 
 /**
- * The different types of advice in AspectJ
- *
+ * The different kinds of advice in AspectJ
  */
-public enum AdviceType {
+public enum AdviceKind {
 	BEFORE,
 	AFTER,
 	AFTER_RETURNING,
diff --git a/aspectj5rt/java5-src/org/aspectj/lang/reflect/AjType.java b/aspectj5rt/java5-src/org/aspectj/lang/reflect/AjType.java
index 095db2172..e2db1407f 100644
--- a/aspectj5rt/java5-src/org/aspectj/lang/reflect/AjType.java
+++ b/aspectj5rt/java5-src/org/aspectj/lang/reflect/AjType.java
@@ -11,7 +11,7 @@
  * ******************************************************************/
 package org.aspectj.lang.reflect;
 
-import java.lang.annotation.Annotation;
+import java.lang.reflect.AnnotatedElement;
 import java.lang.reflect.Constructor;
 import java.lang.reflect.Field;
 import java.lang.reflect.Method;
@@ -22,160 +22,359 @@ import java.lang.reflect.TypeVariable;
  * The runtime representation of a type (Aspect, Class, Interface, Annotation, Enum, or Array) in an AspectJ
  * program.
  */
-public interface AjType<T> extends Type {
+public interface AjType<T> extends Type, AnnotatedElement {
 	
+	/**
+	 * The name of this type, in the same format as returned by Class.getName()
+	 */
 	public String getName();
 	
+	/**
+	 * The package in which this type is declared
+	 */
 	public Package getPackage();
 	
-	public Class[] getInterfaces();
+	/**
+	 * The interfaces implemented by this type
+	 */
+	public AjType<?>[] getInterfaces();
 		
+	/**
+	 * The modifiers declared for this type. The return value can be interpreted
+	 * using java.lang.reflect.Modifier
+	 */
 	public int getModifiers();
+	
+	/**
+	 * The java.lang.Class that corresponds to this AjType
+	 */
+	public Class<T> getJavaClass();
 
 	// scope
 	
-	public AjType getSupertype();
+	/**
+	 * The supertype of this type. If this type represents Object or a primitive type
+	 * then null is returned.
+	 */
+	public AjType<?> getSupertype();
 
+	/**
+	 * The generic supertype of this type, as defined by Class.getGenericSupertype
+	 */
 	public Type getGenericSupertype();
 
+	/**
+	 * If this type represents a local or anonymous type declared within a method, return 
+	 * then enclosing Method object.
+	 */
 	public Method getEnclosingMethod();
 	
+	/**
+	 * If this type represents a local or anonymous type declared within a constructor, return 
+	 * then enclosing Method object.
+	 */
 	public Constructor getEnclosingConstructor();
 
-	public AjType getEnclosingType();
-	
-	public AjType getDeclaringType();
+	/**
+	 * Returns the immediately enclosing type of this type.
+	 */
+	public AjType<?> getEnclosingType();
+	
+	/**
+	 * If this type is a member of another type, return the AjType representing the type
+	 * in which it was declared.
+	 */
+	public AjType<?> getDeclaringType();
 
+	/**
+	 * If this type represents an aspect, returns the associated per-clause.
+	 * Returns null for non-aspect types.
+	 */
 	public PerClause getPerClause(); 
 	
-	// annotations
-	
-	public boolean isAnnotationPresent(Class<? extends Annotation> annotationType);
-	
-	public <A extends Annotation> A getAnnotation(Class<A> annotationType);
-	
-	public Annotation[] getAnnotations();
-	
-	public Annotation[] getDeclaredAnnotations();
-	
 	// inner types
+	/**
+	 * Returns an array containing all the public types that are members of this type
+	 */
+	public AjType<?>[] getAjTypes();
 	
-	public AjType[] getAjTypes();
-	
-	public AjType[] getDeclaredAjTypes();
+	/**
+	 * Returns an array containing all the types declared by this type
+	 */
+	public AjType<?>[] getDeclaredAjTypes();
 	
 	// constructors
 	
-	public Constructor getConstructor(Class... parameterTypes) throws NoSuchMethodException;
+	/**
+	 * Returns the constructor object for the specified public constructor of this type
+	 */
+	public Constructor getConstructor(AjType<?>... parameterTypes) throws NoSuchMethodException;
 	
+	/**
+	 * Returns all of the public constructors of this type
+	 */
 	public Constructor[] getConstructors();
 	
-	public Constructor getDeclaredConstructor(Class... parameterTypes) throws NoSuchMethodException;
-	
+	/**
+	 * Returns the constructor object for the specified constructor of this type
+	 */
+	public Constructor getDeclaredConstructor(AjType<?>... parameterTypes) throws NoSuchMethodException;
+
+	/**
+	 * Returns all the constructors declared in this type
+	 */
 	public Constructor[] getDeclaredConstructors();
 	
 	// fields
 	
+	/**
+	 * Return the field declared in this type with the given name
+	 */
 	public Field getDeclaredField(String name) throws NoSuchFieldException;
 	
+	/** 
+	 * Returns all the fields declared in this type
+	 */
 	public Field[] getDeclaredFields();
 	
+	/**
+	 * Return the public field with the given name 
+	 */
 	public Field getField(String name) throws NoSuchFieldException;
 	
+	/**
+	 * Return the public fields declared by this type
+	 */
 	public Field[] getFields();
 	
 	// methods
-	
-	public Method getDeclaredMethod(String name, Class... parameterTypes) throws NoSuchMethodException;
-	
-	public Method getMethod(String name, Class... parameterTypes) throws NoSuchMethodException;
-	
+
+	/**
+	 * Return the method object for the specified method declared in this type
+	 */
+	public Method getDeclaredMethod(String name, AjType<?>... parameterTypes) throws NoSuchMethodException;
+	
+	/**
+	 * Return the method object for the specified public method declared in this type 
+	 */
+	public Method getMethod(String name, AjType<?>... parameterTypes) throws NoSuchMethodException;
+	
+	/**
+	 * Return all the methods declared by this type
+	 */
 	public Method[] getDeclaredMethods();
 	
+	/**
+	 * Returns all the public methods of this type
+	 */
 	public Method[] getMethods();
 	
 	// pointcuts
 	
+	/**
+	 * Return the pointcut object representing the specified pointcut declared by this type
+	 */
 	public Pointcut getDeclaredPointcut(String name) throws NoSuchPointcutException;
 	
+	/**
+	 * Return the pointcut object representing the specified public pointcut
+	 */
 	public Pointcut getPointcut(String name) throws NoSuchPointcutException;
-	
+
+	/**
+	 * Returns all of the pointcuts declared by this type
+	 */
 	public Pointcut[] getDeclaredPointcuts();
-	
+
+	/**
+	 * Returns all of the public pointcuts of this type
+	 */
 	public Pointcut[] getPointcuts();
 	
 	// advice
-	
-	public Advice[] getDeclaredAdvice(AdviceType... ofTypes);
-	
-	public Advice[] getAdvice(AdviceType... ofTypes);
-	
+
+	/**
+	 * Returns all of the advice declared by this type, of an advice kind contained in the
+	 * parameter list.
+	 */
+	public Advice[] getDeclaredAdvice(AdviceKind... ofTypes);
+	
+	/**
+	 * Returns all of the advice for this type, of an advice kind contained in the parameter
+	 * list. 
+	 */
+	public Advice[] getAdvice(AdviceKind... ofTypes);
+	
+	/**
+	 * Returns the advice with the given name. For an @AspectJ declared advice member,
+	 * this is the name of the annotated method. For a code-style advice declaration, this
+	 * is the name given in the @AdviceName annotation if present.
+	 */
 	public Advice getAdvice(String name) throws NoSuchAdviceException;
 	
+	/**
+	 * Returns the advice declared in this type with the given name. For an @AspectJ declared advice member,
+	 * this is the name of the annotated method. For a code-style advice declaration, this
+	 * is the name given in the @AdviceName annotation if present.
+	 */
 	public Advice getDeclaredAdvice(String name) throws NoSuchAdviceException;
 		
 	// inter-type declarations
 	
-	public InterTypeMethodDeclaration getDeclaredITDMethod(String name, Class target, Class... parameterTypes);
+	/**
+	 * Return the inter-type method declared by this type matching the given specification
+	 */
+	public InterTypeMethodDeclaration getDeclaredITDMethod(String name, AjType<?> target, AjType<?>... parameterTypes);
 	
+	/**
+	 * Return all of the inter-type methods declared by this type
+	 */
 	public InterTypeMethodDeclaration[] getDeclaredITDMethods();
-	
-	public InterTypeMethodDeclaration getITDMethod(String name, Class target, Class... parameterTypes);
-	
+
+	/**
+	 * Return the public inter-type method of this type matching the given specification
+	 */
+	public InterTypeMethodDeclaration getITDMethod(String name, AjType<?> target, AjType<?>... parameterTypes);
+	
+	/**
+	 * Return all of the public inter-type declared methods of this type
+	 */
 	public InterTypeMethodDeclaration[] getITDMethods();
 		
-	public InterTypeConstructorDeclaration getDeclaredITDConstructor(Class target, Class... parameterTypes);
-	
+	/**
+	 * Return the inter-type constructor declared by this type matching the given specification
+	 */
+	public InterTypeConstructorDeclaration getDeclaredITDConstructor(AjType<?> target, AjType<?>... parameterTypes);
+	
+	/**
+	 * Returns all of the inter-type constructors declared by this type
+	 */
 	public InterTypeConstructorDeclaration[] getDeclaredITDConstructors();
 
-	public InterTypeConstructorDeclaration getITDConstructor(Class target, Class... parameterTypes);
-	
+	/**
+	 * Return the public inter-type constructor matching the given specification
+	 */
+	public InterTypeConstructorDeclaration getITDConstructor(AjType<?> target, AjType<?>... parameterTypes);
+
+	/**
+	 * Return all of the public inter-type constructors of this type
+	 */
 	public InterTypeConstructorDeclaration[] getITDConstructors();
-	
-	public InterTypeFieldDeclaration getDeclaredITDField(String name, Class target);
-	
+
+	/**
+	 * Return the inter-type field declared in this type with the given specification
+	 */
+	public InterTypeFieldDeclaration getDeclaredITDField(String name, AjType<?> target);
+
+	/**
+	 * Return all of the inter-type fields declared in this type
+	 */
 	public InterTypeFieldDeclaration[] getDeclaredITDFields();
-	
-	public InterTypeFieldDeclaration getITDField(String name, Class target);
-	
+
+	/**
+	 * Return the public inter-type field matching the given specification
+	 */
+	public InterTypeFieldDeclaration getITDField(String name, AjType<?> target);
+
+	/**
+	 * Return all of the public inter-type fields for this type
+	 */
 	public InterTypeFieldDeclaration[] getITDFields();
 		
 	// declare statements
-	
+	/**
+	 * Returns all of the declare error and declare warning members of this type,
+	 * including declare error/warning members inherited from super-types
+	 */
 	public DeclareErrorOrWarning[] getDeclareErrorOrWarnings();
 	
+	/**
+	 * Returns all of the declare parents members of this type, including
+	 * declare parent members inherited from super-types
+	 */
 	public DeclareParents[] getDeclareParents();
 	
+	/**
+	 * Return all of the declare soft members of this type, including declare
+	 * soft members inherited from super-types
+	 */
 	public DeclareSoft[] getDeclareSofts();
-	
+
+	/**
+	 * Return all of the declare annotation members of this type, including declare
+	 * annotation members inherited from super-types
+	 */
 	public DeclareAnnotation[] getDeclareAnnotations();
 	
+	/**
+	 * Return all of the declare precedence members of this type, including declare
+	 * precedence members inherited from super-types
+	 */
 	public DeclarePrecedence[] getDeclarePrecedence();
 	
 	// misc
 	
+	/**
+	 * Returns the elements of this enum class, or null if this type does not represent
+	 * an enum type.
+	 */
     public T[] getEnumConstants();
 	
+    /**
+     * Returns an array of TypeVariable objects that represent the type variables declared by
+     * this type (if any)
+     */
 	public TypeVariable<Class<T>>[] getTypeParameters();
-	
+
+	/**
+	 * True if this is an enum type
+	 */
 	public boolean isEnum();
-	
+
+	/**
+	 * True if the given object is assignment-compatible with an object of the type represented
+	 * by this AjType
+	 */
 	public boolean isInstance(Object o);
-	
+
+	/**
+	 * True if this is an interface type
+	 */
 	public boolean isInterface();
-	
+
+	/**
+	 * Returns true if and only if the underlying type is a local class
+	 */
 	public boolean isLocalClass();
 	
+	/**
+	 * Returns true if and only if the underlying type is a member class
+	 */
 	public boolean isMemberClass();
 	
+	/**
+	 * Return true if this is an array type
+	 */
 	public boolean isArray();
-	
+
+	/**
+	 * Return true if this object represents a primitive type
+	 */
 	public boolean isPrimitive();
-	
+
+	/**
+	 * Return true if this is an aspect type
+	 */
 	public boolean isAspect();
 	
+	/**
+	 * Returns true if and only if the underlying type is a member aspect
+	 */
 	public boolean isMemberAspect();
-	
+
+	/**
+	 * Returns true if and only if the underlying type is a privileged aspect
+	 */
 	public boolean isPrivileged();
 	
 }
diff --git a/aspectj5rt/java5-src/org/aspectj/lang/reflect/AjTypeSystem.java b/aspectj5rt/java5-src/org/aspectj/lang/reflect/AjTypeSystem.java
index 7b1599549..fbd9a6644 100644
--- a/aspectj5rt/java5-src/org/aspectj/lang/reflect/AjTypeSystem.java
+++ b/aspectj5rt/java5-src/org/aspectj/lang/reflect/AjTypeSystem.java
@@ -11,15 +11,43 @@
  * ******************************************************************/
 package org.aspectj.lang.reflect;
 
+import java.lang.ref.WeakReference;
+import java.util.Map;
+import java.util.WeakHashMap;
+
 import org.aspectj.internal.lang.reflect.AjTypeImpl;
 
 /**
- * @author colyer
- *
+ * This is the anchor for the AspectJ runtime type system. 
+ * Typical usage to get the AjType representation of a given type
+ * at runtime is to call <code>AjType<Foo> fooType = AjTypeSystem.getAjType(Foo.class);</code>
  */
 public class AjTypeSystem {
+	
+		private static Map<Class, WeakReference<AjType>> ajTypes = new WeakHashMap<Class,WeakReference<AjType>>();
 
+		/**
+		 * Return the AspectJ runtime type representation of the given Java type.
+		 * Unlike java.lang.Class, AjType understands pointcuts, advice, declare statements,
+		 * and other AspectJ type members. AjType is the recommended reflection API for
+		 * AspectJ programs as it offers everything that java.lang.reflect does, with 
+		 * AspectJ-awareness on top.
+		 */
 		public static <T> AjType<T> getAjType(Class<T> fromClass) {
-			return new AjTypeImpl<T>(fromClass);
+			if (ajTypes.containsKey(fromClass)) {
+				WeakReference<AjType> weakRefToAjType = ajTypes.get(fromClass);
+				AjType<T> theAjType = weakRefToAjType.get();
+				if (theAjType != null) {
+					return theAjType;
+				} else {
+					theAjType = new AjTypeImpl<T>(fromClass);
+					ajTypes.put(fromClass, new WeakReference<AjType>(theAjType));
+					return theAjType;
+				}
+			}
+			// neither key nor value was found
+			AjType<T> theAjType =  new AjTypeImpl<T>(fromClass);
+			ajTypes.put(fromClass, new WeakReference<AjType>(theAjType));
+			return theAjType;
 		}
 }
diff --git a/aspectj5rt/java5-src/org/aspectj/lang/reflect/DeclareAnnotation.java b/aspectj5rt/java5-src/org/aspectj/lang/reflect/DeclareAnnotation.java
index cd594e9da..4e0f78aa7 100644
--- a/aspectj5rt/java5-src/org/aspectj/lang/reflect/DeclareAnnotation.java
+++ b/aspectj5rt/java5-src/org/aspectj/lang/reflect/DeclareAnnotation.java
@@ -12,7 +12,7 @@
 package org.aspectj.lang.reflect;
 
 /**
- * @author colyer
+ * The AspectJ runtime representation of a declare annotation member in an aspect.
  *
  */
 public interface DeclareAnnotation {
diff --git a/aspectj5rt/java5-src/org/aspectj/lang/reflect/DeclareErrorOrWarning.java b/aspectj5rt/java5-src/org/aspectj/lang/reflect/DeclareErrorOrWarning.java
index c8539c166..a6a5abc53 100644
--- a/aspectj5rt/java5-src/org/aspectj/lang/reflect/DeclareErrorOrWarning.java
+++ b/aspectj5rt/java5-src/org/aspectj/lang/reflect/DeclareErrorOrWarning.java
@@ -12,12 +12,29 @@
 package org.aspectj.lang.reflect;
 
 /**
- * @author colyer
- *
+ * AspectJ runtime representation of a declare error or declare warning member
+ * in an aspect.
  */
 public interface DeclareErrorOrWarning {
+	
+	/**
+	 * The type that declared this declare warning or declare error member. 
+	 */
+	AjType getDeclaringType();
+	
+	/**
+	 * The pointcut expression associated with the warning or error
+	 */
 	PointcutExpression getPointcutExpression();
+	
+	/**
+	 * The message associated with the declare warning / declare error
+	 */
 	String getMessage();
+	
+	/**
+	 * True if this is a declare error member, false if it is declare warning
+	 */
 	boolean isError();
 	
 }
diff --git a/aspectj5rt/java5-src/org/aspectj/lang/reflect/DeclareParents.java b/aspectj5rt/java5-src/org/aspectj/lang/reflect/DeclareParents.java
index 6b1d6f5b3..f8ee5c99d 100644
--- a/aspectj5rt/java5-src/org/aspectj/lang/reflect/DeclareParents.java
+++ b/aspectj5rt/java5-src/org/aspectj/lang/reflect/DeclareParents.java
@@ -12,9 +12,34 @@
 package org.aspectj.lang.reflect;
 
 /**
- * @author colyer
- *
+ * A declare parents member defined inside an aspect
  */
 public interface DeclareParents {
 
+	/**
+	 * The declaring aspect
+	 */
+	AjType getDeclaringType();
+	
+	/**
+	 * The target type pattern
+	 */
+	TypePattern getTargetTypesPattern();
+	
+	/**
+	 * True if this is a declare parents...extends member declaration
+	 */
+	boolean isExtends();
+	
+	/**
+	 * True if this is a declare parents...implements member declaration
+	 */
+	boolean isImplements();
+	
+	/**
+	 * The set of types that the types matching getTargetTypesPattern are 
+	 * declared to implement or extend
+	 */
+	AjType[] getParentTypes();
+	
 }
diff --git a/aspectj5rt/java5-src/org/aspectj/lang/reflect/DeclarePrecedence.java b/aspectj5rt/java5-src/org/aspectj/lang/reflect/DeclarePrecedence.java
index ad7086d95..894580b70 100644
--- a/aspectj5rt/java5-src/org/aspectj/lang/reflect/DeclarePrecedence.java
+++ b/aspectj5rt/java5-src/org/aspectj/lang/reflect/DeclarePrecedence.java
@@ -12,9 +12,21 @@
 package org.aspectj.lang.reflect;
 
 /**
- * @author colyer
- *
+ * AspectJ runtime representation of a declare precedence statement as 
+ * declared in an aspect.
  */
 public interface DeclarePrecedence {
 
+	/**
+	 * The declaring aspect
+	 */
+	AjType getDeclaringType();
+	
+	/**
+	 * Returns an ordered set of type patterns. An aspect matching
+	 * a type pattern at a lower index in the array takes precedence
+	 * over an aspect that only matches a type pattern at a higher
+	 * index in the array.
+	 */
+	TypePattern[] getPrecedenceOrder();
 }
diff --git a/aspectj5rt/java5-src/org/aspectj/lang/reflect/DeclareSoft.java b/aspectj5rt/java5-src/org/aspectj/lang/reflect/DeclareSoft.java
index ffb392c3f..b397c94f3 100644
--- a/aspectj5rt/java5-src/org/aspectj/lang/reflect/DeclareSoft.java
+++ b/aspectj5rt/java5-src/org/aspectj/lang/reflect/DeclareSoft.java
@@ -12,9 +12,23 @@
 package org.aspectj.lang.reflect;
 
 /**
- * @author colyer
- *
+ * AspectJ runtime representation of a declare soft member within an aspect.
  */
 public interface DeclareSoft {
+	
+	/**
+	 * The aspect that declared this member
+	 */
+	AjType getDeclaringType();
+	
+	/**
+	 * The softened exception type
+	 */
+	AjType getSoftenedExceptionType();
+	
+	/**
+	 * The pointcut determining the join points at which the exception is to be softened.
+	 */
+	PointcutExpression getPointcutExpression();
 
 }
diff --git a/aspectj5rt/java5-src/org/aspectj/lang/reflect/NoSuchAdviceException.java b/aspectj5rt/java5-src/org/aspectj/lang/reflect/NoSuchAdviceException.java
index e14dfb7d3..6b1ca8fa0 100644
--- a/aspectj5rt/java5-src/org/aspectj/lang/reflect/NoSuchAdviceException.java
+++ b/aspectj5rt/java5-src/org/aspectj/lang/reflect/NoSuchAdviceException.java
@@ -12,8 +12,8 @@
 package org.aspectj.lang.reflect;
 
 /**
- * @author colyer
- *
+ * Thrown when AjType.getDeclaredAdvice is called with an advice name and no matching
+ * advice declaration can be found.
  */
 public class NoSuchAdviceException extends Exception {
 
@@ -24,6 +24,9 @@ public class NoSuchAdviceException extends Exception {
 		this.name = name;
 	}
 	
+	/**
+	 * The advice name that could not be found.
+	 */
 	public String getName() {
 		return name;
 	}
diff --git a/aspectj5rt/java5-src/org/aspectj/lang/reflect/NoSuchPointcutException.java b/aspectj5rt/java5-src/org/aspectj/lang/reflect/NoSuchPointcutException.java
index df1bf9189..0274b74b4 100644
--- a/aspectj5rt/java5-src/org/aspectj/lang/reflect/NoSuchPointcutException.java
+++ b/aspectj5rt/java5-src/org/aspectj/lang/reflect/NoSuchPointcutException.java
@@ -12,8 +12,8 @@
 package org.aspectj.lang.reflect;
 
 /**
- * @author colyer
- *
+ * Thrown when AjType.getDeclaredPointcut is called with a pointcut name, and no
+ * matching pointcut declaration can be found.
  */
 public class NoSuchPointcutException extends Exception {
 
@@ -24,6 +24,9 @@ public class NoSuchPointcutException extends Exception {
 		this.name = name;
 	}
 	
+	/**
+	 * The name of the pointcut that could not be found.
+	 */
 	public String getName() {
 		return name;
 	}
diff --git a/aspectj5rt/java5-src/org/aspectj/lang/reflect/PerClause.java b/aspectj5rt/java5-src/org/aspectj/lang/reflect/PerClause.java
index c3396c548..c16feda33 100644
--- a/aspectj5rt/java5-src/org/aspectj/lang/reflect/PerClause.java
+++ b/aspectj5rt/java5-src/org/aspectj/lang/reflect/PerClause.java
@@ -12,10 +12,12 @@
 package org.aspectj.lang.reflect;
 
 /**
- * @author colyer
- *
+ * AspectJ runtime representation of the per-clause associated with an aspect.
  */
 public interface PerClause {
+	/**
+	 * The kind of per-clause (singleton, perthis, pertarget,...)
+	 */
 	PerClauseKind getKind();
-	PointcutExpression getPointcutExpression();
+
 }
diff --git a/aspectj5rt/java5-src/org/aspectj/lang/reflect/PerClauseKind.java b/aspectj5rt/java5-src/org/aspectj/lang/reflect/PerClauseKind.java
index 03313d8c5..1e2d42ecd 100644
--- a/aspectj5rt/java5-src/org/aspectj/lang/reflect/PerClauseKind.java
+++ b/aspectj5rt/java5-src/org/aspectj/lang/reflect/PerClauseKind.java
@@ -12,8 +12,8 @@
 package org.aspectj.lang.reflect;
 
 /**
- * @author colyer
- * The different perclauses (aspect instantiation models)
+ * The different per-clauses (aspect instantiation models)
+ * supported by AspectJ
  */
 public enum PerClauseKind {
 	SINGLETON,
diff --git a/aspectj5rt/java5-src/org/aspectj/lang/reflect/Pointcut.java b/aspectj5rt/java5-src/org/aspectj/lang/reflect/Pointcut.java
index c514bea01..dfec7ccbd 100644
--- a/aspectj5rt/java5-src/org/aspectj/lang/reflect/Pointcut.java
+++ b/aspectj5rt/java5-src/org/aspectj/lang/reflect/Pointcut.java
@@ -11,17 +11,42 @@
  * ******************************************************************/
 package org.aspectj.lang.reflect;
 
+/**
+ * AspectJ runtime representation of a pointcut member inside a class or aspect.
+ */
 public interface Pointcut {
-
-	PointcutExpression getPointcutExpression();
 	
+	/**
+	 * The declared name of the pointcut.
+	 */
 	String getName();
 	
+	/**
+	 * The modifiers associated with the pointcut declaration. 
+	 * Use java.lang.reflect.Modifier to interpret the return value
+	 */
 	int getModifiers();
 	
-	Class<?>[] getParameterTypes();
+	/**
+	 * The pointcut parameter types.
+	 */
+	AjType<?>[] getParameterTypes();
 	
+	/**
+	 * The pointcut parameter names. Returns an array of empty strings
+	 * of length getParameterTypes().length if parameter names are not
+	 * available at runtime.
+	 */
 	String[] getParameterNames();
 	
+	/**
+	 * The type that declared this pointcut
+	 */
 	AjType getDeclaringType();
+
+	/**
+	 * The pointcut expression associated with this pointcut.
+	 */
+	PointcutExpression getPointcutExpression();
+
 }
diff --git a/aspectj5rt/java5-src/org/aspectj/lang/reflect/PointcutBasedPerClause.java b/aspectj5rt/java5-src/org/aspectj/lang/reflect/PointcutBasedPerClause.java
new file mode 100644
index 000000000..db040ea62
--- /dev/null
+++ b/aspectj5rt/java5-src/org/aspectj/lang/reflect/PointcutBasedPerClause.java
@@ -0,0 +1,25 @@
+/* *******************************************************************
+ * Copyright (c) 2005 Contributors.
+ * All rights reserved. 
+ * This program and the accompanying materials are made available 
+ * under the terms of the Eclipse Public License v1.0 
+ * which accompanies this distribution and is available at 
+ * http://eclipse.org/legal/epl-v10.html 
+ *  
+ * Contributors: 
+ *   Adrian Colyer			Initial implementation
+ * ******************************************************************/
+package org.aspectj.lang.reflect;
+
+/**
+ * Representation of a pointcut based per-clause associated with an aspect
+ * (perthis/target/cflow/cflowbelow)
+ *
+ */
+public interface PointcutBasedPerClause extends PerClause {
+
+	/**
+	 * Get the associated pointcut expression
+	 */
+	PointcutExpression getPointcutExpression();
+}
diff --git a/aspectj5rt/java5-src/org/aspectj/lang/reflect/PointcutExpression.java b/aspectj5rt/java5-src/org/aspectj/lang/reflect/PointcutExpression.java
index b2ab44d7c..e229ba1f0 100644
--- a/aspectj5rt/java5-src/org/aspectj/lang/reflect/PointcutExpression.java
+++ b/aspectj5rt/java5-src/org/aspectj/lang/reflect/PointcutExpression.java
@@ -20,5 +20,5 @@ public interface PointcutExpression {
 	/**
 	 * Returns a String representation of the pointcut expression 
 	 */
-	String toString();
+	String asString();
 }
diff --git a/aspectj5rt/java5-src/org/aspectj/lang/reflect/SignaturePattern.java b/aspectj5rt/java5-src/org/aspectj/lang/reflect/SignaturePattern.java
new file mode 100644
index 000000000..99ba44dda
--- /dev/null
+++ b/aspectj5rt/java5-src/org/aspectj/lang/reflect/SignaturePattern.java
@@ -0,0 +1,23 @@
+/* *******************************************************************
+ * Copyright (c) 2005 Contributors.
+ * All rights reserved. 
+ * This program and the accompanying materials are made available 
+ * under the terms of the Eclipse Public License v1.0 
+ * which accompanies this distribution and is available at 
+ * http://eclipse.org/legal/epl-v10.html 
+ *  
+ * Contributors: 
+ *   Adrian Colyer			Initial implementation
+ * ******************************************************************/
+package org.aspectj.lang.reflect;
+
+/**
+ * AspectJ runtime representation of a signature pattern as used in various
+ * aspect members (for example, declare @method, declare @field).
+ */
+public interface SignaturePattern {
+
+	/** return a String representation of this pattern */
+	String asString();
+	
+}
diff --git a/aspectj5rt/java5-src/org/aspectj/lang/reflect/TypePattern.java b/aspectj5rt/java5-src/org/aspectj/lang/reflect/TypePattern.java
new file mode 100644
index 000000000..f3b69b421
--- /dev/null
+++ b/aspectj5rt/java5-src/org/aspectj/lang/reflect/TypePattern.java
@@ -0,0 +1,22 @@
+/* *******************************************************************
+ * Copyright (c) 2005 Contributors.
+ * All rights reserved. 
+ * This program and the accompanying materials are made available 
+ * under the terms of the Eclipse Public License v1.0 
+ * which accompanies this distribution and is available at 
+ * http://eclipse.org/legal/epl-v10.html 
+ *  
+ * Contributors: 
+ *   Adrian Colyer			Initial implementation
+ * ******************************************************************/
+package org.aspectj.lang.reflect;
+
+/**
+ * AspectJ runtime representation of a type pattern as used in member declarations
+ * such as declare parents.
+ */
+public interface TypePattern {
+
+	/** a string representation of the pattern */
+	String asString();
+}
diff --git a/aspectj5rt/java5-src/org/aspectj/lang/reflect/TypePatternBasedPerClause.java b/aspectj5rt/java5-src/org/aspectj/lang/reflect/TypePatternBasedPerClause.java
new file mode 100644
index 000000000..402b883b9
--- /dev/null
+++ b/aspectj5rt/java5-src/org/aspectj/lang/reflect/TypePatternBasedPerClause.java
@@ -0,0 +1,26 @@
+/* *******************************************************************
+ * Copyright (c) 2005 Contributors.
+ * All rights reserved. 
+ * This program and the accompanying materials are made available 
+ * under the terms of the Eclipse Public License v1.0 
+ * which accompanies this distribution and is available at 
+ * http://eclipse.org/legal/epl-v10.html 
+ *  
+ * Contributors: 
+ *   Adrian Colyer			Initial implementation
+ * ******************************************************************/
+package org.aspectj.lang.reflect;
+
+/**
+ * AspectJ runtime representation of a type pattern based per-clause associated
+ * with an aspect (pertypewithin).
+ *
+ */
+public interface TypePatternBasedPerClause {
+
+	/**
+	 * Get the associated type pattern
+	 */
+	TypePattern getTypePattern();
+	
+}