8004730: Add language model support for parameter reflection

Reviewed-by: abuckley

langtools/src/share/classes/javax/lang/model/element/Element.java

@@ -179,6 +179,10 @@ public interface Element {
      * instance initializer}, an empty name is returned.
      *
      * @return the simple name of this element
+     * @see PackageElement#getSimpleName
+     * @see ExecutableElement#getSimpleName
+     * @see TypeElement#getSimpleName
+     * @see VariableElement#getSimpleName
      */
     Name getSimpleName();
 
@@ -202,6 +206,11 @@ public interface Element {
      * {@linkplain TypeParameterElement#getGenericElement the
      * generic element} of the type parameter is returned.
      *
+     * <li> If this is a {@linkplain
+     * VariableElement#getEnclosingElement method or constructor
+     * parameter}, {@linkplain ExecutableElement the executable
+     * element} which declares the parameter is returned.
+     *
      * </ul>
      *
      * @return the enclosing element, or {@code null} if there is none

langtools/src/share/classes/javax/lang/model/element/VariableElement.java

@@ -62,4 +62,29 @@ public interface VariableElement extends Element {
      * @jls 4.12.4 final Variables
      */
     Object getConstantValue();
+
+    /**
+     * Returns the simple name of this variable element.
+     *
+     * <p>For method and constructor parameters, the name of each
+     * parameter must be distinct from the names of all other
+     * parameters of the same executable.  If the original source
+     * names are not available, an implementation may synthesize names
+     * subject to the distinctness requirement above.
+     *
+     * @return the simple name of this variable element
+     */
+    @Override
+    Name getSimpleName();
+
+    /**
+     * Returns the enclosing element of this variable.
+     *
+     * The enclosing element of a method or constructor parameter is
+     * the executable declaring the parameter.
+     *
+     * @return the enclosing element of this variable
+     */
+    @Override
+    Element getEnclosingElement();
 }

langtools/src/share/classes/javax/lang/model/element/package-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2010, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2012, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -48,9 +48,12 @@
  * {@linkplain java.lang.annotation.RetentionPolicy#SOURCE source}
  * {@linkplain java.lang.annotation.Retention retention} cannot be
  * recovered from class files and class files might not be able to
- * provide source position information.  The {@linkplain
+ * provide source position information.
- * javax.lang.model.element.Modifier modifiers} on an element may
+ *
- * differ in some cases including
+ * Names of parameters may not be recoverable from class files.
+ *
+ * The {@linkplain javax.lang.model.element.Modifier modifiers} on an
+ * element may differ in some cases including:
  *
  * <ul>
  * <li> {@code strictfp} on a class or interface