changeset 19017:c76282450dce

More javadoc cleanup
author alanb
date Tue, 07 Feb 2017 13:11:14 +0000
parents d21f2b0f6713
children 5c4843cc0b4b
files src/java.base/share/classes/java/lang/module/ModuleDescriptor.java src/java.base/share/classes/java/lang/module/ModuleReader.java src/java.base/share/classes/java/lang/reflect/AccessibleObject.java test/java/lang/module/ModuleDescriptorTest.java
diffstat 4 files changed, 102 insertions(+), 47 deletions(-) [+]
line wrap: on
line diff
--- a/src/java.base/share/classes/java/lang/module/ModuleDescriptor.java	Mon Feb 06 18:26:54 2017 +0000
+++ b/src/java.base/share/classes/java/lang/module/ModuleDescriptor.java	Tue Feb 07 13:11:14 2017 +0000
@@ -311,9 +311,9 @@
         }
 
         /**
-         * Returns a string describing module dependence.
+         * Returns a string describing this module dependence.
          *
-         * @return A string describing module dependence
+         * @return A string describing this module dependence
          */
         @Override
         public String toString() {
@@ -330,7 +330,7 @@
 
 
     /**
-     * <p> Represents an exported package, may be qualified or unqualified. </p>
+     * <p> A package exported by a module, may be qualified or unqualified. </p>
      *
      * @see ModuleDescriptor#exports()
      * @since 9
@@ -520,9 +520,9 @@
         }
 
         /**
-         * Returns a string describing module export.
+         * Returns a string describing the exported package.
          *
-         * @return A string describing module export
+         * @return A string describing the exported package
          */
         @Override
         public String toString() {
@@ -536,7 +536,7 @@
 
 
     /**
-     * <p> Represents an open package, may be qualified or unqualified. </p>
+     * <p> A package opened by a module, may be qualified or unqualified. </p>
      *
      * <p> The <em>opens</em> directive in a module declaration declares a
      * package to be open to allow all types in the package, and all their
@@ -731,9 +731,9 @@
         }
 
         /**
-         * Returns a string describing module opens.
+         * Returns a string describing the open package.
          *
-         * @return A string describing module opens
+         * @return A string describing the open package
          */
         @Override
         public String toString() {
@@ -1284,7 +1284,7 @@
     }
 
     /**
-     * <p> The module name. </p>
+     * <p> Returns the module name. </p>
      *
      * @return The module name
      */
@@ -1293,7 +1293,7 @@
     }
 
     /**
-     * <p> The set of module modifiers. </p>
+     * <p> Returns the set of module modifiers. </p>
      *
      * @return A possibly-empty unmodifiable set of modifiers
      */
@@ -1326,7 +1326,7 @@
     }
 
     /**
-     * <p> The dependences of this module. </p>
+     * <p> Returns the set of module dependences. </p>
      *
      * <p> The set includes a dependency on "{@code java.base}" when this
      * module is not named "{@code java.base}". If this module is an automatic
@@ -1340,7 +1340,7 @@
     }
 
     /**
-     * <p> The set of exported packages. </p>
+     * <p> Returns the set of exported packages. </p>
      *
      * <p> If this module is an automatic module then the set of exports
      * is empty. </p>
@@ -1352,7 +1352,7 @@
     }
 
     /**
-     * <p> The set of open packages. </p>
+     * <p> Returns the set of open packages. </p>
      *
      * <p> If this module is an open module or an automatic module then the
      * set of open packages is empty. </p>
@@ -1364,7 +1364,7 @@
     }
 
     /**
-     * <p> The service dependences of this module. </p>
+     * <p> Returns the set of service dependences. </p>
      *
      * <p> If this module is an automatic module then the set of service
      * dependences is empty. </p>
@@ -1377,7 +1377,7 @@
     }
 
     /**
-     * <p> The services that this module provides. </p>
+     * <p> Returns the set of services that the module provides. </p>
      *
      * @return The possibly-empty unmodifiable set of the services that this
      *         module provides
@@ -1387,7 +1387,7 @@
     }
 
     /**
-     * Returns this module's version.
+     * <p> Returns the module version. </p>
      *
      * @return This module's version
      */
@@ -1396,10 +1396,10 @@
     }
 
     /**
-     * Returns a string containing this module's name and, if present, its
-     * version.
+     * <p> Returns a string containing the module name and, if present, its
+     * version. </p>
      *
-     * @return A string containing this module's name and, if present, its
+     * @return A string containing the module name and, if present, its
      *         version.
      */
     public String toNameAndVersion() {
@@ -1411,51 +1411,51 @@
     }
 
     /**
-     * Returns the module's main class.
+     * <p> Returns the module main class. </p>
      *
-     * @return The fully qualified class name of this module's main class
+     * @return The fully qualified class name of the module's main class
      */
     public Optional<String> mainClass() {
         return Optional.ofNullable(mainClass);
     }
 
     /**
-     * Returns the operating system name if this module is operating system
+     * Returns the operating system name if the module is operating system
      * specific.
      *
      * @return The operating system name or an empty {@code Optional}
-     *         if this module is not operating system specific
+     *         if the module is not operating system specific
      */
     public Optional<String> osName() {
         return Optional.ofNullable(osName);
     }
 
     /**
-     * Returns the operating system architecture if this module is operating
+     * Returns the operating system architecture if the module is operating
      * system architecture specific.
      *
      * @return The operating system architecture or an empty {@code Optional}
-     *         if this module is not operating system architecture specific
+     *         if the module is not operating system architecture specific
      */
     public Optional<String> osArch() {
         return Optional.ofNullable(osArch);
     }
 
     /**
-     * Returns the operating system version if this module is operating
+     * Returns the operating system version if the module is operating
      * system version specific.
      *
      * @return The operating system version or an empty {@code Optional}
-     *         if this module is not operating system version specific
+     *         if the module is not operating system version specific
      */
     public Optional<String> osVersion() {
         return Optional.ofNullable(osVersion);
     }
 
     /**
-     * Returns the names of all packages in this module.
+     * Returns the set of packages in the module.
      *
-     * @return A possibly-empty unmodifiable set of all packages in the module
+     * @return A possibly-empty unmodifiable set of the packages in the module
      */
     public Set<String> packages() {
         return packages;
@@ -1463,7 +1463,7 @@
 
 
     /**
-     * A builder used for building {@link ModuleDescriptor} objects.
+     * A builder for building {@link ModuleDescriptor} objects.
      *
      * <p> {@code ModuleDescriptor} defines the {@link #newModule newModule},
      * {@link #newOpenModule newOpenModule}, and {@link #newAutomaticModule
@@ -1496,9 +1496,6 @@
      * components are added to the builder. The rationale for this is to detect
      * errors as early as possible and not defer all validation to the
      * {@link #build build} method.
-     * A {@code Builder} cannot be used to create a module with the
-     * {@link ModuleDescriptor.Modifier#MANDATED MANDATED} or
-     * {@link ModuleDescriptor.Modifier#SYNTHETIC SYNTHETIC} modifiers.
      *
      * @since 9
      * @spec JPMS
@@ -2372,9 +2369,9 @@
     private transient int hash;  // cached hash code
 
     /**
-     * Returns a string describing this descriptor.
+     * <p> Returns a string describing the module. </p>
      *
-     * @return A string describing this descriptor
+     * @return A string describing the module
      */
     @Override
     public String toString() {
@@ -2401,6 +2398,29 @@
 
     /**
      * Instantiates a builder to build a module descriptor.
+     *
+     * @param  name
+     *         The module name
+     * @param  ms
+     *         The set of module modifiers
+     *
+     * @return A new builder
+     *
+     * @throws IllegalArgumentException
+     *         If the module name is {@code null} or is not a legal module
+     *         name, or the set of modifiers contains both {@link Modifier#OPEN
+     *         OPEN} and {@link Modifier#AUTOMATIC AUTOMATIC}
+     */
+    public static Builder newModule(String name, Set<Modifier> ms) {
+        Set<Modifier> mods = new HashSet<>(ms);
+        if (mods.contains(Modifier.OPEN) && mods.contains(Modifier.AUTOMATIC))
+            throw new IllegalArgumentException("OPEN and AUTOMATIC not allowed");
+        return new Builder(name, true, mods);
+    }
+
+    /**
+     * Instantiates a builder to build a module descriptor.
+     *
      * @param  name
      *         The module name
      *
--- a/src/java.base/share/classes/java/lang/module/ModuleReader.java	Mon Feb 06 18:26:54 2017 +0000
+++ b/src/java.base/share/classes/java/lang/module/ModuleReader.java	Tue Feb 07 13:11:14 2017 +0000
@@ -64,11 +64,11 @@
  * @implSpec Implementations of {@code ModuleReader} should take great care
  * when translating an abstract resource name to the location of a resource in
  * a packaged module or on the file system. Implementations are advised to
- * treat resource names with elements such as '{@code .}'and '{@code ..}',
- * file separators, or empty elements as "not found". More generally, if the
- * resource name is not in the stream of elements that the {@code list} method
- * returns then the resource should be treated as "not found" to avoid
- * inconsistencies.
+ * treat resource names with elements such as '{@code .},  '{@code ..}',
+ * elements containing file separators, or empty elements as "not found". More
+ * generally, if the resource name is not in the stream of elements that the
+ * {@code list} method returns then the resource should be treated as "not
+ * found" to avoid inconsistencies.
  *
  * @see ModuleReference
  * @since 9
--- a/src/java.base/share/classes/java/lang/reflect/AccessibleObject.java	Mon Feb 06 18:26:54 2017 +0000
+++ b/src/java.base/share/classes/java/lang/reflect/AccessibleObject.java	Tue Feb 07 13:11:14 2017 +0000
@@ -191,13 +191,14 @@
     }
 
     /**
-     * Set the {@code accessible} flag for this reflected object to {@code true}.
-     * This method sets the {@code accessible} flag, as if by invoking {@link
-     * #setAccessible(boolean) setAccessible(true)}, and returns the new value
-     * for the {@code accessible} flag. If access cannot be enabled, i.e. the
-     * checks or Java language access control cannot be suppressed, this method
-     * returns {@code false} as opposed to {@link #setAccessible(boolean)}
-     * which throws {@code InaccessibleObjectException} when it fails.
+     * Set the {@code accessible} flag for this reflected object to {@code true}
+     * if possible. This method sets the {@code accessible} flag, as if by
+     * invoking {@link #setAccessible(boolean) setAccessible(true)}, and returns
+     * the possibly-updated value for the {@code accessible} flag. If access
+     * cannot be enabled, i.e. the checks or Java language access control cannot
+     * be suppressed, this method returns {@code false} (as opposed to {@code
+     * setAccessible(true)} throwing {@code InaccessibleObjectException} when
+     * it fails).
      *
      * <p> This method is a no-op if the {@code accessible} flag for
      * this reflected object is {@code true}.
--- a/test/java/lang/module/ModuleDescriptorTest.java	Mon Feb 06 18:26:54 2017 +0000
+++ b/test/java/lang/module/ModuleDescriptorTest.java	Tue Feb 07 13:11:14 2017 +0000
@@ -1120,6 +1120,40 @@
     }
 
 
+    // newModule with modifiers
+
+    public void testNewModuleToBuildAutomaticModule() {
+        Set<ModuleDescriptor.Modifier> ms = Set.of(ModuleDescriptor.Modifier.AUTOMATIC);
+        ModuleDescriptor descriptor = ModuleDescriptor.newModule("foo", ms).build();
+        assertTrue(descriptor.modifiers().equals(ms));
+        assertTrue(descriptor.isAutomatic());
+
+        ms = Set.of(ModuleDescriptor.Modifier.AUTOMATIC, ModuleDescriptor.Modifier.SYNTHETIC);
+        descriptor = ModuleDescriptor.newModule("foo", ms).build();
+        assertTrue(descriptor.modifiers().equals(ms));
+        assertTrue(descriptor.isAutomatic());
+    }
+
+    public void testNewModuleToBuildOpenModule() {
+        Set<ModuleDescriptor.Modifier> ms = Set.of(ModuleDescriptor.Modifier.OPEN);
+        ModuleDescriptor descriptor = ModuleDescriptor.newModule("foo", ms).build();
+        assertTrue(descriptor.modifiers().equals(ms));
+        assertTrue(descriptor.isOpen());
+
+        ms = Set.of(ModuleDescriptor.Modifier.OPEN, ModuleDescriptor.Modifier.SYNTHETIC);
+        descriptor = ModuleDescriptor.newModule("foo", ms).build();
+        assertTrue(descriptor.modifiers().equals(ms));
+        assertTrue(descriptor.isOpen());
+    }
+
+    @Test(expectedExceptions = IllegalArgumentException.class)
+    public void testNewModuleToBuildAutomaticAndOpenModule() {
+        Set<ModuleDescriptor.Modifier> ms = Set.of(ModuleDescriptor.Modifier.AUTOMATIC,
+                                                   ModuleDescriptor.Modifier.OPEN);
+        ModuleDescriptor.newModule("foo", ms);
+    }
+
+
     // mainClass
 
     public void testMainClass() {