Implement AbstractProcessor, adding annotations and an interface it depends on.

2013-02-21  Andrew John Hughes  <gnu_andrew@member.fsf.org>

	* javax/annotation/processing/AbstractProcessor.java:
	New class added.
	(processingEnv): Added.
	(initialized): Likewise.
	(AbstractProcessor()): Implemented.
	(getCompletions(Element,AnnotationMirror,ExecutableElement,
	String)): Likewise.
	(getSupportedAnnotationTypes()):Likewise.
	(getSupportedOptions()): Likewise.
	(getSupportedSourceVersion()): Likewise.
	(init(ProcessingEnvironment)): Likewise.
	(isInitialized()): Likewise.
	(process(Set,RoundEnvironment)): Likewise.
	* javax/annotation/processing/Completion.java:
	New interface added.
	(getValue()): Added.
	(getMessage()): Likewise.
	* javax/annotation/processing/Processor.java:
	(getCompletions(Element,AnnotationMirror,ExecutableElement,
	String)): Added.
	* javax/annotation/processing/SupportedAnnotationTypes.java:
	New annotation added.
	(value()): Added.
	* javax/annotation/processing/SupportedOptions.java:
	New annotation added.
	(value()): Added.
	* javax/annotation/processing/SupportedSourceVersion.java:
	Reference AbstractProcessor in documentation.

Signed-off-by: Andrew John Hughes <gnu_andrew@member.fsf.org>

7 files changed, 473 insertions, 2 deletions

diff --git a/ChangeLog b/ChangeLog
index 906a439bd..fe04fe283 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,34 @@
+2013-02-21  Andrew John Hughes  <gnu_andrew@member.fsf.org>
+
+	* javax/annotation/processing/AbstractProcessor.java:
+	New class added.
+	(processingEnv): Added.
+	(initialized): Likewise.
+	(AbstractProcessor()): Implemented.
+	(getCompletions(Element,AnnotationMirror,ExecutableElement,
+	String)): Likewise.
+	(getSupportedAnnotationTypes()):Likewise.
+	(getSupportedOptions()): Likewise.
+	(getSupportedSourceVersion()): Likewise.
+	(init(ProcessingEnvironment)): Likewise.
+	(isInitialized()): Likewise.
+	(process(Set,RoundEnvironment)): Likewise.
+	* javax/annotation/processing/Completion.java:
+	New interface added.
+	(getValue()): Added.
+	(getMessage()): Likewise.
+	* javax/annotation/processing/Processor.java:
+	(getCompletions(Element,AnnotationMirror,ExecutableElement,
+	String)): Added.
+	* javax/annotation/processing/SupportedAnnotationTypes.java:
+	New annotation added.
+	(value()): Added.
+	* javax/annotation/processing/SupportedOptions.java:
+	New annotation added.
+	(value()): Added.
+	* javax/annotation/processing/SupportedSourceVersion.java:
+	Reference AbstractProcessor in documentation.
+
 2013-02-18  Andrew John Hughes  <gnu_andrew@member.fsf.org>
 
 	* javax/lang/model/SourceVersion.java,
diff --git a/javax/annotation/processing/AbstractProcessor.java b/javax/annotation/processing/AbstractProcessor.java
new file mode 100644
index 000000000..b86ed3ce3
--- /dev/null
+++ b/javax/annotation/processing/AbstractProcessor.java
@@ -0,0 +1,206 @@
+/* AbstractProcessor.java -- Base Processor implementation using annotations.
+   Copyright (C) 2012  Free Software Foundation, Inc.
+
+This file is part of GNU Classpath.
+
+GNU Classpath is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2, or (at your option)
+any later version.
+
+GNU Classpath is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with GNU Classpath; see the file COPYING.  If not, write to the
+Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+02110-1301 USA.
+
+Linking this library statically or dynamically with other modules is
+making a combined work based on this library.  Thus, the terms and
+conditions of the GNU General Public License cover the whole
+combination.
+
+As a special exception, the copyright holders of this library give you
+permission to link this library with independent modules to produce an
+executable, regardless of the license terms of these independent
+modules, and to copy and distribute the resulting executable under
+terms of your choice, provided that you also meet, for each linked
+independent module, the terms and conditions of the license of that
+module.  An independent module is a module which is not derived from
+or based on this library.  If you modify this library, you may extend
+this exception to your version of the library, but you are not
+obligated to do so.  If you do not wish to do so, delete this
+exception statement from your version. */
+
+package javax.annotation.processing;
+
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.Set;
+
+import javax.lang.model.SourceVersion;
+
+import javax.lang.model.element.AnnotationMirror;
+import javax.lang.model.element.Element;
+import javax.lang.model.element.ExecutableElement;
+import javax.lang.model.element.TypeElement;
+
+import javax.tools.Diagnostic;
+
+/**
+ * This class provides a base implementation of an
+ * annotation {@link Processor}, using annotations to
+ * determine the supported options, annotations and
+ * source version.  The getter methods may issue warnings
+ * using the diagnostic facilities provided after
+ * processor initialization.
+
+ * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
+ * @since 1.6
+ */
+public abstract class AbstractProcessor
+  implements Processor
+{
+
+  /** The processing environment used by the processor framework. */
+  protected ProcessingEnvironment processingEnv;
+
+  /** True if the processor has been initialized. */
+  private boolean initialized = false;
+
+  /**
+   * Constructs a new {@link AbstractProcessor}.
+   */
+  protected AbstractProcessor() { }
+
+  /**
+   * Returns an empty {@link Iterable} of {@link Completion}s.
+   *
+   * @param element the element being annotated.
+   * @param annotation the annotation (possibly partial) being applied to the element.
+   * @param member the annotation member to return completions for.
+   * @param userText the source code text to be completed.
+   * @return an empty {@code Iterable}.
+   */
+  @Override
+  public Iterable<? extends Completion> getCompletions(Element element,
+						       AnnotationMirror annotation,
+						       ExecutableElement member,
+						       String userText)
+  {
+    return Collections.emptyList();
+  }
+
+  /**
+   * Uses the {@link SupportedAnnotationTypes} annotation to provide an
+   * unmodifiable set of {@link String}s representing the supported
+   * annotation types.  If the annotation is not present on the processor
+   * class, the empty set is returned.
+   *
+   * @return the annotation types supported by this processor.
+   * @see SupportedAnnotationTypes
+   */
+  @Override
+  public Set<String> getSupportedAnnotationTypes()
+  {
+    SupportedAnnotationTypes types = getClass().getAnnotation(SupportedAnnotationTypes.class);
+    if (types == null)
+      {
+	if (processingEnv != null)
+	  processingEnv.getMessager().printMessage(Diagnostic.Kind.WARNING,
+						   "Could not retrieve supported annotation types.");
+	return Collections.emptySet();
+      }
+
+    String[] supported = types.value();
+    Set<String> supportedTypes = new HashSet<String>();
+    for (String s : supported)
+      supportedTypes.add(s);
+
+    return Collections.unmodifiableSet(supportedTypes);
+  }
+
+  /**
+   * Uses the {@link SupportedOptions} annotation to provide an
+   * unmodifiable set of {@link String}s representing the supported
+   * options.  If the annotation is not present on the processor
+   * class, the empty set is returned.
+   *
+   * @return the options supported by this processor.
+   * @see SupportedOptions
+   */
+  @Override
+  public Set<String> getSupportedOptions()
+  {
+    SupportedOptions options = getClass().getAnnotation(SupportedOptions.class);
+    if (options == null)
+      {
+	if (processingEnv != null)
+	  processingEnv.getMessager().printMessage(Diagnostic.Kind.WARNING,
+						   "Could not retrieve supported options.");
+	return Collections.emptySet();
+      }
+
+    String[] supported = options.value();
+    Set<String> supportedOptions = new HashSet<String>();
+    for (String s : supported)
+      supportedOptions.add(s);
+
+    return Collections.unmodifiableSet(supportedOptions);
+  }
+
+  /**
+   * Uses the {@link SupportedSourceVersion} annotation to provide
+   * the source version supported by this processor.  If the annotation
+   * is not present on the processor class, {@link SourceVersion#RELEASE_6}
+   * is returned.
+   *
+   * @return the source version supported by this processor.
+   * @see SupportedVersion
+   */
+  @Override
+  public SourceVersion getSupportedSourceVersion()
+  {
+    SupportedSourceVersion version = getClass().getAnnotation(SupportedSourceVersion.class);
+    if (version == null)
+      return SourceVersion.RELEASE_6;
+    return version.value();
+  }
+
+  /**
+   * Initialises the processor by setting {@link #processingEnv} to the supplied
+   * processing environment.  This method can only be run once.  If invoked a
+   * second time (i.e.{@link #isInitialized()} returns {@code true}), an
+   * {@link IllegalStateException} will be thrown.
+   *
+   * @param env the environment to initialise the processor with.
+   * @throws IllegalStateException if the processor has been initialised.
+   */
+  public void init(ProcessingEnvironment env)
+  {
+    if (isInitialized())
+      throw new IllegalStateException("The processor has already been initialised.");
+    processingEnv = env;
+    initialized = true;
+  }
+
+  /**
+   * Returns true if this processor has been initialized i.e.
+   * {@link #init(ProcessingEnvironment)}has been run.
+   *
+   * @return {@code true} if the processor has been initialised.
+   */
+  protected boolean isInitialized()
+  {
+    return initialized;
+  }
+
+  /**
+   * @inheritDoc
+   */
+  public abstract boolean process(Set<? extends TypeElement> types, RoundEnvironment roundEnv);
+
+}
diff --git a/javax/annotation/processing/Completion.java b/javax/annotation/processing/Completion.java
new file mode 100644
index 000000000..a865d3174
--- /dev/null
+++ b/javax/annotation/processing/Completion.java
@@ -0,0 +1,65 @@
+/* Completion.java -- Suggested completion for an annotation.
+   Copyright (C) 2013  Free Software Foundation, Inc.
+
+This file is part of GNU Classpath.
+
+GNU Classpath is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2, or (at your option)
+any later version.
+
+GNU Classpath is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with GNU Classpath; see the file COPYING.  If not, write to the
+Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+02110-1301 USA.
+
+Linking this library statically or dynamically with other modules is
+making a combined work based on this library.  Thus, the terms and
+conditions of the GNU General Public License cover the whole
+combination.
+
+As a special exception, the copyright holders of this library give you
+permission to link this library with independent modules to produce an
+executable, regardless of the license terms of these independent
+modules, and to copy and distribute the resulting executable under
+terms of your choice, provided that you also meet, for each linked
+independent module, the terms and conditions of the license of that
+module.  An independent module is a module which is not derived from
+or based on this library.  If you modify this library, you may extend
+this exception to your version of the library, but you are not
+obligated to do so.  If you do not wish to do so, delete this
+exception statement from your version. */
+
+package javax.annotation.processing;
+
+/**
+ * A suggested completion for an annotation.  It contains
+ * text which may be used in an annotation, together with
+ * an optional message describing it.
+ *
+ * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
+ * @since 1.6
+ */
+public interface Completion
+{
+
+  /**
+   * Returns the suggested annotation text.
+   *
+   * @return the suggested text.
+   */
+  String getValue();
+
+  /**
+   * Returns a description of the suggested completion.
+   *
+   * @return a message about the completion.
+   */
+  String getMessage();
+
+}
diff --git a/javax/annotation/processing/Processor.java b/javax/annotation/processing/Processor.java
index af790546c..588cbda32 100644
--- a/javax/annotation/processing/Processor.java
+++ b/javax/annotation/processing/Processor.java
@@ -1,5 +1,5 @@
 /* Processor.java -- An annotation processor.
-   Copyright (C) 2012  Free Software Foundation, Inc.
+   Copyright (C) 2012, 2013  Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -40,6 +40,9 @@ package javax.annotation.processing;
 import java.util.Set;
 
 import javax.lang.model.SourceVersion;
+import javax.lang.model.element.AnnotationMirror;
+import javax.lang.model.element.Element;
+import javax.lang.model.element.ExecutableElement;
 import javax.lang.model.element.TypeElement;
 
 /**
@@ -186,5 +189,42 @@ public interface Processor
    */
   boolean process(Set<? extends TypeElement> types, RoundEnvironment roundEnv);
 
+  /**
+   * <p>
+   * Returns a series of suggested completions for an annotation or an empty
+   * {@link Iterable}.  As a completion is being requested, the information
+   * provided to the method may be incomplete, but either {@code element} or
+   * {@code userText} must be non-{@code null}.  If the processor can not
+   * provide any completions due to a lack of available information, it should
+   * not throw a {@link NullPointerException}, but instead return an empty
+   * {@code Iterable} or a single completion with an empty value string and
+   * a message explaining why completions could not be returned.
+   * </p>
+   * <p>
+   * Completions are aimed at annotation members where validity constraints reduce
+   * the range of possible values.  For example, imagine an annotation {@code RainbowColour}
+   * which takes as its value one of the following strings: {@code "RED"}, {@code "ORANGE"},
+   * {@code "YELLOW"}, {@code "GREEN"}, {@code "BLUE"}, {@code "INDIGO"} and {@code "VIOLET"}.
+   * If this annotation is passed as the annotation mirror argument to this method, then
+   * a list of {@code Completion} objects may be returned as follows:</p>
+   * <code>return Arrays.asList({@link Completions#of}("RED"), of("ORANGE"), of("YELLOW"),
+   * of("GREEN"), of("BLUE"), of("INDIGO"), of("VIOLET"));</code>.  If {@code userText}
+   * is set, it may be used to further reduce the range of possible values.  For example,
+   * if {@code userText} was "R", then {@code Arrays.asList(of("RED"))} would be returned,
+   * as only one possible value starts with {@code "R"}.  However, if {@code userText}
+   * was {@code "P"}, then {@code Collections.emptyList()} would be returned, as there
+   * are no possible values beginning with {@code "P"}.  Alternatively,
+   * {@code of("", "No colours begin with the letter " + userText)} may be used to
+   * give a more informative result.
+   * </p>
+   *
+   * @param element the element being annotated.
+   * @param annotation the annotation (possibly partial) being applied to the element.
+   * @param member the annotation member to return completions for.
+   * @param userText the source code text to be completed.
+   * @return an {@code Iterable} over suggested completions to the annotation.
+   */
+  Iterable<? extends Completion> getCompletions(Element element, AnnotationMirror annotation,
+						ExecutableElement member, String userText);
 }
 
diff --git a/javax/annotation/processing/SupportedAnnotationTypes.java b/javax/annotation/processing/SupportedAnnotationTypes.java
new file mode 100644
index 000000000..826de5be2
--- /dev/null
+++ b/javax/annotation/processing/SupportedAnnotationTypes.java
@@ -0,0 +1,64 @@
+/* SupportedAnnotationTypes.java -- Annotation to indicate supported annotation types.
+   Copyright (C) 2013  Free Software Foundation, Inc.
+
+This file is part of GNU Classpath.
+
+GNU Classpath is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2, or (at your option)
+any later version.
+
+GNU Classpath is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with GNU Classpath; see the file COPYING.  If not, write to the
+Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+02110-1301 USA.
+
+Linking this library statically or dynamically with other modules is
+making a combined work based on this library.  Thus, the terms and
+conditions of the GNU General Public License cover the whole
+combination.
+
+As a special exception, the copyright holders of this library give you
+permission to link this library with independent modules to produce an
+executable, regardless of the license terms of these independent
+modules, and to copy and distribute the resulting executable under
+terms of your choice, provided that you also meet, for each linked
+independent module, the terms and conditions of the license of that
+module.  An independent module is a module which is not derived from
+or based on this library.  If you modify this library, you may extend
+this exception to your version of the library, but you are not
+obligated to do so.  If you do not wish to do so, delete this
+exception statement from your version. */
+
+package javax.annotation.processing;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Indicates the annotation types supported by an
+ * annotation processor.  This can be used by 
+ * {@link Processor#getSupportedAnnotationTypes()}
+ * to obtain the supported types automatically, as is
+ * done in {@link AbstractProcessor}.  Note
+ * that the strings must comply with the grammar
+ * specified in the documentation of
+ * {@link Processor#getSupportedAnnotationTypes()}.
+ *
+ * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
+ * @since 1.6
+ */
+@Documented @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.TYPE)
+public @interface SupportedAnnotationTypes
+{
+  /** The annotation types supported. */
+  String[] value();
+}
diff --git a/javax/annotation/processing/SupportedOptions.java b/javax/annotation/processing/SupportedOptions.java
new file mode 100644
index 000000000..db31c4fd3
--- /dev/null
+++ b/javax/annotation/processing/SupportedOptions.java
@@ -0,0 +1,64 @@
+/* SupportedOptions.java -- Annotation to indicate supported processor options.
+   Copyright (C) 2013  Free Software Foundation, Inc.
+
+This file is part of GNU Classpath.
+
+GNU Classpath is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2, or (at your option)
+any later version.
+
+GNU Classpath is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with GNU Classpath; see the file COPYING.  If not, write to the
+Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+02110-1301 USA.
+
+Linking this library statically or dynamically with other modules is
+making a combined work based on this library.  Thus, the terms and
+conditions of the GNU General Public License cover the whole
+combination.
+
+As a special exception, the copyright holders of this library give you
+permission to link this library with independent modules to produce an
+executable, regardless of the license terms of these independent
+modules, and to copy and distribute the resulting executable under
+terms of your choice, provided that you also meet, for each linked
+independent module, the terms and conditions of the license of that
+module.  An independent module is a module which is not derived from
+or based on this library.  If you modify this library, you may extend
+this exception to your version of the library, but you are not
+obligated to do so.  If you do not wish to do so, delete this
+exception statement from your version. */
+
+package javax.annotation.processing;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Indicates options supported by an
+ * annotation processor.  This can be used by 
+ * {@link Processor#getSupportedOptions()}
+ * to obtain the supported options automatically, as is
+ * done in {@link AbstractProcessor}.  Note
+ * that the strings must comply with the grammar
+ * specified in the documentation of
+ * {@link Processor#getSupportedOptions()}.
+ *
+ * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
+ * @since 1.6
+ */
+@Documented @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.TYPE)
+public @interface SupportedOptions
+{
+  /** The annotation types supported. */
+  String[] value();
+}
diff --git a/javax/annotation/processing/SupportedSourceVersion.java b/javax/annotation/processing/SupportedSourceVersion.java
index a5bde9642..3508a9cd1 100644
--- a/javax/annotation/processing/SupportedSourceVersion.java
+++ b/javax/annotation/processing/SupportedSourceVersion.java
@@ -48,7 +48,8 @@ import javax.lang.model.SourceVersion;
 /**
  * Indicates the latest source version supported.
  * This can be used by {@link Processor#getSupportedSourceVersion()}
- * to obtain the supported source version automatically.
+ * to obtain the supported source version automatically,
+ * as is done in {@link AbstractProcessor}.
  *
  * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
  * @since 1.6