8173676: Improvements to javax.annotation.processing and javax.lang.model doc

Reviewed-by: anazarov
2026-02-01 22:18:23 +00:00 · 2017-02-01 11:25:56 -08:00 · 2017-02-01 11:25:56 -08:00 · ae44237a42
commit ae44237a42
parent 88d92662cd
20 changed files with 67 additions and 72 deletions
--- a/langtools/src/java.compiler/share/classes/javax/annotation/processing/Filer.java
+++ b/langtools/src/java.compiler/share/classes/javax/annotation/processing/Filer.java
@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2017, 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
@ -264,7 +264,7 @@ public interface Filer {
     * @param moduleAndPkg module and/or package relative to which the file
     *           should be named, or the empty string if none
     * @param relativeName final pathname components of the file
-     * @param originatingElements type or package elements causally
+     * @param originatingElements type or package or module elements causally
     * associated with the creation of this file, may be elided or
     * {@code null}
     * @return a {@code FileObject} to write the new resource
--- a/langtools/src/java.compiler/share/classes/javax/annotation/processing/FilerException.java
+++ b/langtools/src/java.compiler/share/classes/javax/annotation/processing/FilerException.java
@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2012, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2017, 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
@ -31,7 +31,7 @@ import java.io.IOException;
 * Indicates a {@link Filer} detected an attempt to open a file that
 * would violate the guarantees provided by the {@code Filer}.  Those
 * guarantees include not creating the same file more than once, not
- * creating multiple files corresponding to the same type, and not
+ * creating multiple files corresponding to the same type or package, and not
 * creating files for types with invalid names.
 *
 * @author Joseph D. Darcy
--- a/langtools/src/java.compiler/share/classes/javax/annotation/processing/Processor.java
+++ b/langtools/src/java.compiler/share/classes/javax/annotation/processing/Processor.java
@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2017, 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
@ -194,7 +194,7 @@ import javax.lang.model.SourceVersion;
 * <p>The {@link Filer} interface discusses restrictions on how
 * processors can operate on files.
 *
- * <p>Note that implementors of this interface may find it convenient
+ * @apiNote Implementors of this interface may find it convenient
 * to extend {@link AbstractProcessor} rather than implementing this
 * interface directly.
 *
@ -315,7 +315,7 @@ public interface Processor {
     * is returned, the annotation types are unclaimed and subsequent
     * processors may be asked to process them.  A processor may
     * always return the same boolean value or may vary the result
-     * based on chosen criteria.
+     * based on its own chosen criteria.
     *
     * <p>The input set will be empty if the processor supports {@code
     * "*"} and the root elements have no annotations.  A {@code
@ -343,8 +343,8 @@ public interface Processor {
    * <p>Since incomplete programs are being modeled, some of the
    * parameters may only have partial information or may be {@code
    * null}.  At least one of {@code element} and {@code userText}
-    * must be non-{@code null}.  If {@code element} is non-{@code
-    * null}, {@code annotation} and {@code member} may be {@code
+    * must be non-{@code null}.  If {@code element} is non-{@code null},
+    * {@code annotation} and {@code member} may be {@code
    * null}.  Processors may not throw a {@code NullPointerException}
    * if some parameters are {@code null}; if a processor has no
    * completions to offer based on the provided information, an
--- a/langtools/src/java.compiler/share/classes/javax/annotation/processing/RoundEnvironment.java
+++ b/langtools/src/java.compiler/share/classes/javax/annotation/processing/RoundEnvironment.java
@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2017, 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
@ -65,7 +65,7 @@ public interface RoundEnvironment {
    boolean errorRaised();

    /**
-     * Returns the root elements for annotation processing generated
+     * Returns the {@linkplain Processor root elements} for annotation processing generated
     * by the prior round.
     *
     * @return the root elements for annotation processing generated
--- a/langtools/src/java.compiler/share/classes/javax/lang/model/AnnotatedConstruct.java
+++ b/langtools/src/java.compiler/share/classes/javax/lang/model/AnnotatedConstruct.java
@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2013, 2017, 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
@ -62,7 +62,7 @@ import javax.lang.model.type.*;
 *
 * If there are multiple annotations of type <i>AT</i> present on
 * <i>C</i>, then if <i>AT</i> is repeatable annotation type, an
- * annotation of type <i>ATC</i> is implicitly declared on <i>C</i>.
+ * annotation of type <i>ATC</i> is {@linkplain javax.lang.model.util.Elements#getOrigin(AnnotatedConstruct, AnnotationMirror) implicitly declared} on <i>C</i>.
 *
 * <li> A representation of <i>A</i> appears in the executable output
 * for <i>C</i>, such as the {@code RuntimeVisibleAnnotations} or
--- a/langtools/src/java.compiler/share/classes/javax/lang/model/UnknownEntityException.java
+++ b/langtools/src/java.compiler/share/classes/javax/lang/model/UnknownEntityException.java
@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2009, 2017, 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
@ -32,8 +32,9 @@ package javax.lang.model;
 * this exception may be thrown by visitors to indicate that the
 * visitor was created for a prior version of the language.
 *
- * <p>A common superclass for those exceptions allows a single catch
- * block to have code handling them uniformly.
+ * @apiNote A common superclass for exceptions specific to different
+ * kinds of unknown entities allows a single catch block to easily
+ * provide uniform handling of those related conditions.
 *
 * @author Joseph D. Darcy
 * @see javax.lang.model.element.UnknownElementException
--- a/langtools/src/java.compiler/share/classes/javax/lang/model/element/Element.java
+++ b/langtools/src/java.compiler/share/classes/javax/lang/model/element/Element.java
@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2017, 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
@ -37,7 +37,7 @@ import javax.lang.model.util.*;


 /**
- * Represents a program element such as a package, class, or method.
+ * Represents a program element such as a module, package, class, or method.
 * Each element represents a static, language-level construct
 * (and not, for example, a runtime construct of the virtual machine).
 *
@ -180,7 +180,7 @@ public interface Element extends javax.lang.model.AnnotatedConstruct {
     * any elements; however, that may change as this API or the
     * programming language evolves.
     *
-     * <p>Note that elements of certain kinds can be isolated using
+     * @apiNote Elements of certain kinds can be isolated using
     * methods in {@link ElementFilter}.
     *
     * @return the enclosed elements, or an empty list if none
@ -197,7 +197,7 @@ public interface Element extends javax.lang.model.AnnotatedConstruct {
     * Returns {@code true} if the argument represents the same
     * element as {@code this}, or {@code false} otherwise.
     *
-     * <p>Note that the identity of an element involves implicit state
+     * @apiNote The identity of an element involves implicit state
     * not directly accessible from the element's methods, including
     * state about the presence of unrelated types.  Element objects
     * created by different implementations of these interfaces should
--- a/langtools/src/java.compiler/share/classes/javax/lang/model/element/ModuleElement.java
+++ b/langtools/src/java.compiler/share/classes/javax/lang/model/element/ModuleElement.java
@ -37,17 +37,18 @@ import java.util.List;
 public interface ModuleElement extends Element, QualifiedNameable {

    /**
-     * Returns the fully qualified name of this module.
+     * Returns the fully qualified name of this module.  For an
+     * {@linkplain #isUnnamed() unnamed module}, an empty name is returned.
     *
-     * @return the qualified name of this module, or an
+     * @return the fully qualified name of this module, or an
     * empty name if this is an unnamed module
     */
    @Override
    Name getQualifiedName();

    /**
-     * Returns the simple name of this module.  For an unnamed
-     * module, an empty name is returned.
+     * Returns the simple name of this module.  For an {@linkplain
+     * #isUnnamed() unnamed module}, an empty name is returned.
     *
     * @return the simple name of this module or an empty name if
     * this is an unnamed module
--- a/langtools/src/java.compiler/share/classes/javax/lang/model/element/NestingKind.java
+++ b/langtools/src/java.compiler/share/classes/javax/lang/model/element/NestingKind.java
@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2017, 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
@ -89,25 +89,29 @@ public enum NestingKind {

    /**
     * A type that is a named member of another type.
+     * @jls 8.5 Member Type Declarations
     */
    MEMBER,

    /**
     * A named type declared within a construct other than a type.
+     * @jls 14.3 Local Class Declarations
     */
    LOCAL,

    /**
     * A type without a name.
+     * @jls 15.9.5 Anonymous Class Declarations
     */
    ANONYMOUS;

    /**
     * Does this constant correspond to a nested type element?
     * A <i>nested</i> type element is any that is not top-level.
-     * An <i>inner</i> type element is any nested type element that
+     * More specifically, an <i>inner</i> type element is any nested type element that
     * is not {@linkplain Modifier#STATIC static}.
     * @return whether or not the constant is nested
+     * @jls 14.3 Inner Classes and Enclosing Instances
     */
    public boolean isNested() {
        return this != TOP_LEVEL;
--- a/langtools/src/java.compiler/share/classes/javax/lang/model/element/PackageElement.java
+++ b/langtools/src/java.compiler/share/classes/javax/lang/model/element/PackageElement.java
@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2017, 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
@ -42,6 +42,7 @@ public interface PackageElement extends Element, QualifiedNameable {
    /**
     * Returns the fully qualified name of this package.
     * This is also known as the package's <i>canonical</i> name.
+     * For an {@linkplain #isUnnamed() unnamed package}, an empty name is returned.
     *
     * @return the fully qualified name of this package, or an
     * empty name if this is an unnamed package
@ -50,8 +51,8 @@ public interface PackageElement extends Element, QualifiedNameable {
    Name getQualifiedName();

    /**
-     * Returns the simple name of this package.  For an unnamed
-     * package, an empty name is returned.
+     * Returns the simple name of this package.  For an {@linkplain
+     * #isUnnamed() unnamed package}, an empty name is returned.
     *
     * @return the simple name of this package or an empty name if
     * this is an unnamed package
--- a/langtools/src/java.compiler/share/classes/javax/lang/model/element/Parameterizable.java
+++ b/langtools/src/java.compiler/share/classes/javax/lang/model/element/Parameterizable.java
@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2009, 2017, 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
@ -35,7 +35,7 @@ import java.util.List;
 */
 public interface Parameterizable extends Element {
    /**
-     * Returns the formal type parameters of the type element in
+     * Returns the formal type parameters of an element in
     * declaration order.
     *
     * @return the formal type parameters, or an empty list
--- a/langtools/src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java
+++ b/langtools/src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java
@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2017, 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
@ -67,14 +67,14 @@ public interface TypeElement extends Element, Parameterizable, QualifiedNameable
     * the implicit {@code values} and {@code valueOf} methods of an
     * enum type.
     *
-     * <p> Note that as a particular instance of the {@linkplain
+     * @apiNote As a particular instance of the {@linkplain
     * javax.lang.model.element general accuracy requirements} and the
     * ordering behavior required of this interface, the list of
     * enclosed elements will be returned in the natural order for the
     * originating source of information about the type.  For example,
     * if the information about the type is originating from a source
     * file, the elements will be returned in source code order.
-     * (However, in that case the the ordering of synthesized
+     * (However, in that case the the ordering of {@linkplain Elements.Origin#MANDATED mandated}
     * elements, such as a default constructor, is not specified.)
     *
     * @return the enclosed elements in proper order, or an empty list if none
--- a/langtools/src/java.compiler/share/classes/javax/lang/model/element/UnknownAnnotationValueException.java
+++ b/langtools/src/java.compiler/share/classes/javax/lang/model/element/UnknownAnnotationValueException.java
@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2009, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2017, 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
@ -79,7 +79,7 @@ public class UnknownAnnotationValueException extends UnknownEntityException {
    /**
     * Returns the additional argument.
     *
-     * @return the additional argument
+     * @return the additional argument, or {@code null} if unavailable
     */
    public Object getArgument() {
        return parameter;
--- a/langtools/src/java.compiler/share/classes/javax/lang/model/element/UnknownElementException.java
+++ b/langtools/src/java.compiler/share/classes/javax/lang/model/element/UnknownElementException.java
@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2009, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2017, 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
@ -77,7 +77,7 @@ public class UnknownElementException extends UnknownEntityException {
    /**
     * Returns the additional argument.
     *
-     * @return the additional argument
+     * @return the additional argument, or {@code null} if unavailable
     */
    public Object getArgument() {
        return parameter;
--- a/langtools/src/java.compiler/share/classes/javax/lang/model/element/package-info.java
+++ b/langtools/src/java.compiler/share/classes/javax/lang/model/element/package-info.java
@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2017, 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
@ -87,14 +87,14 @@
 * If a program is syntactically valid but erroneous in some other
 * fashion, any returned model must have no less information than if
 * all the method bodies in the program were replaced by {@code "throw
- * new RuntimeException();"}.  If a program refers to a missing type XYZ,
+ * new RuntimeException();"}.  If a program refers to a missing type Xyz,
 * the returned model must contain no less information than if the
- * declaration of type XYZ were assumed to be {@code "class XYZ {}"},
- * {@code "interface XYZ {}"}, {@code "enum XYZ {}"}, or {@code
- * "@interface XYZ {}"}. If a program refers to a missing type {@code
- * XYZ<K1, ... ,Kn>}, the returned model must contain no less
- * information than if the declaration of XYZ were assumed to be
- * {@code "class XYZ<T1, ... ,Tn> {}"} or {@code "interface XYZ<T1,
+ * declaration of type Xyz were assumed to be {@code "class Xyz {}"},
+ * {@code "interface Xyz {}"}, {@code "enum Xyz {}"}, or {@code
+ * "@interface Xyz {}"}. If a program refers to a missing type {@code
+ * Xyz<K1, ... ,Kn>}, the returned model must contain no less
+ * information than if the declaration of Xyz were assumed to be
+ * {@code "class Xyz<T1, ... ,Tn> {}"} or {@code "interface Xyz<T1,
 * ... ,Tn> {}"}
 *
 * <p> Unless otherwise specified in a particular implementation, the
--- a/langtools/src/java.compiler/share/classes/javax/lang/model/type/IntersectionType.java
+++ b/langtools/src/java.compiler/share/classes/javax/lang/model/type/IntersectionType.java
@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2017, 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
@ -33,14 +33,12 @@ import java.util.List;
 * <p>An intersection type can be either implicitly or explicitly
 * declared in a program. For example, the bound of the type parameter
 * {@code <T extends Number & Runnable>} is an (implicit) intersection
- * type.  As of {@link javax.lang.model.SourceVersion#RELEASE_8
- * RELEASE_8}, this is represented by an {@code IntersectionType} with
+ * type.  This is represented by an {@code IntersectionType} with
 * {@code Number} and {@code Runnable} as its bounds.
 *
- * @implNote Also as of {@link
- * javax.lang.model.SourceVersion#RELEASE_8 RELEASE_8}, in the
- * reference implementation an {@code IntersectionType} is used to
- * model the explicit target type of a cast expression.
+ * @implNote In the reference implementation an {@code
+ * IntersectionType} is used to model the explicit target type of a
+ * cast expression.
 *
 * @since 1.8
 */
@ -49,7 +47,7 @@ public interface IntersectionType extends TypeMirror {
    /**
     * Return the bounds comprising this intersection type.
     *
-     * @return the bounds of this intersection types.
+     * @return the bounds of this intersection type
     */
    List<? extends TypeMirror> getBounds();
 }
--- a/langtools/src/java.compiler/share/classes/javax/lang/model/type/UnionType.java
+++ b/langtools/src/java.compiler/share/classes/javax/lang/model/type/UnionType.java
@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2017, 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
@ -30,9 +30,8 @@ import java.util.List;
 /**
 * Represents a union type.
 *
- * As of the {@link javax.lang.model.SourceVersion#RELEASE_7
- * RELEASE_7} source version, union types can appear as the type
- * of a multi-catch exception parameter.
+ * Union types can appear as the type of a multi-catch exception
+ * parameter.
 *
 * @since 1.7
 */
--- a/langtools/src/java.compiler/share/classes/javax/lang/model/type/UnknownTypeException.java
+++ b/langtools/src/java.compiler/share/classes/javax/lang/model/type/UnknownTypeException.java
@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2009, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2017, 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
@ -77,7 +77,7 @@ public class UnknownTypeException extends UnknownEntityException {
    /**
     * Returns the additional argument.
     *
-     * @return the additional argument
+     * @return the additional argument, or {@code null} if unavailable
     */
    public Object getArgument() {
        return parameter;
--- a/langtools/src/java.compiler/share/classes/javax/lang/model/util/ElementFilter.java
+++ b/langtools/src/java.compiler/share/classes/javax/lang/model/util/ElementFilter.java
@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2017, 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
@ -55,15 +55,6 @@ import javax.lang.model.element.ModuleElement.UsesDirective;
 * arguments to methods in this class, a {@code NullPointerException}
 * will be thrown.
 *
- * <p>Note that a <i>static import</i> statement can make the text of
- * calls to the methods in this class more concise; for example:
- *
- * <blockquote><pre>
- *     import static javax.lang.model.util.ElementFilter.*;
- *     ...
- *         {@code List<VariableElement>} fs = fieldsIn(someClass.getEnclosedElements());
- * </pre></blockquote>
- *
 * @author Joseph D. Darcy
 * @author Scott Seligman
 * @author Peter von der Ah&eacute;
--- a/langtools/src/java.compiler/share/classes/javax/lang/model/util/Elements.java
+++ b/langtools/src/java.compiler/share/classes/javax/lang/model/util/Elements.java
@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2017, 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
@ -348,7 +348,7 @@ public interface Elements {
     * declared directly.  For a class the result also includes its
     * constructors, but not local or anonymous classes.
     *
-     * <p>Note that elements of certain kinds can be isolated using
+     * @apiNote Elements of certain kinds can be isolated using
     * methods in {@link ElementFilter}.
     *
     * @param type  the type being examined