sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1792065 - in /sis/branches/JDK8/core: sis-feature/src/main/java/org/apache/sis/feature/builder/ sis-metadata/src/main/java/org/apache/sis/metadata/iso/ sis-utility/src/main/java/org/apache/sis/util/iso/
Date Thu, 20 Apr 2017 14:10:40 GMT
Author: desruisseaux
Date: Thu Apr 20 14:10:40 2017
New Revision: 1792065

URL: http://svn.apache.org/viewvc?rev=1792065&view=rev
Log:
Javadoc.

Modified:
    sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/builder/FeatureTypeBuilder.java
    sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/builder/TypeBuilder.java
    sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/builder/package-info.java
    sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/DefaultMetadata.java
    sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/iso/ResourceInternationalString.java

Modified: sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/builder/FeatureTypeBuilder.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/builder/FeatureTypeBuilder.java?rev=1792065&r1=1792064&r2=1792065&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/builder/FeatureTypeBuilder.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/builder/FeatureTypeBuilder.java
[UTF-8] Thu Apr 20 14:10:40 2017
@@ -53,8 +53,49 @@ import org.opengis.feature.Operation;
  * This builder can create the arguments to be given to the
  * {@linkplain DefaultFeatureType#DefaultFeatureType feature type constructor}
  * from simpler parameters given to this builder.
+ * The main methods provided in this class are:
  *
- * <p>{@code FeatureTypeBuilder} should be short lived.
+ * <ul>
+ *   <li>Various {@link #setName(CharSequence) setName(...)} methods for specifying
the feature type name (mandatory).</li>
+ *   <li>Methods for optionally setting {@linkplain #setDesignation designation}, {@linkplain
#setDefinition definition} or
+ *       {@linkplain #setDescription description} texts, or the {@linkplain #setDeprecated
deprecation status}.</li>
+ *   <li>Methods for optionally specifying the feature type hierarchy: its {@linkplain
#setSuperTypes super types}
+ *       and whether the feature type is {@linkplain #setAbstract abstract}.</li>
+ *   <li>Convenience methods for setting the {@linkplain #setNameSpace name space}
and the
+ *       {@linkplain #setDefaultCardinality default cardinality} of properties to be added
to the feature type.</li>
+ *   <li>Methods for {@linkplain #addAttribute(Class) adding an attribute}, {@linkplain
#addAssociation(FeatureType)
+ *       an association} or {@linkplain #addProperty an operation}.</li>
+ *   <li>Method for listing the previously added {@linkplain #properties() properties}.</li>
+ *   <li>A {@link #build()} method for creating the {@code FeatureType} instance from
all previous information.</li>
+ * </ul>
+ *
+ * The following example creates a city named "Utopia" by default:
+ *
+ * {@preformat java
+ *     FeatureTypeBuilder builder;
+ *
+ *     // Create a feature type for a city, which contains a name and a population.
+ *     builder = new FeatureTypeBuilder() .setName("City");
+ *     builder.addAttribute(String.class) .setName("name").setDefaultValue("Utopia");
+ *     builder.addAttribute(Integer.class).setName("population");
+ *     FeatureType city = builder.build();
+ * }
+ *
+ * A call to {@code System.out.println(city)} prints the following table:
+ *
+ * {@preformat text
+ *   City
+ *   ┌────────────┬─────────┬─────────────┬───────────────┐
+ *   │ Name       │ Type    │ Cardinality │ Default value │
+ *   ├────────────┼─────────┼─────────────┼───────────────┤
+ *   │ name       │ String  │ [1 … 1]     │ Utopia        │
+ *   │ population │ Integer │ [1 … 1]     │               │
+ *   └────────────┴─────────┴─────────────┴───────────────┘
+ * }
+ *
+ *
+ *
+ * <p>{@code FeatureTypeBuilder} instances should be short lived.
  * After the {@code FeatureType} has been created, the builder should be discarded.</p>
  *
  * @author  Johann Sorel (Geomatys)
@@ -333,12 +374,21 @@ public class FeatureTypeBuilder extends
      * Sets the namespace of the next names to be created by {@code setName(CharSequence...)}
method calls.
      * This method applies only to the next calls to {@link #setName(CharSequence)} or
      * {@link #setName(CharSequence...)} methods; the result of all previous calls stay unmodified.
+     * Example:
+     *
+     * {@preformat java
+     *     FeatureTypeBuilder builder = new FeatureTypeBuilder().setNameSpace("MyNameSpace").setName("City");
+     *     FeatureType city = builder.build();
+     *
+     *     System.out.println(city.getName());                              // Prints "City"
+     *     System.out.println(city.getName().toFullyQualifiedName());       // Prints "MyNameSpace:City"
+     * }
      *
-     * <p>There is different conventions about the use of name spaces. ISO 19109 suggests
that the namespace of all
+     * There is different conventions about the use of name spaces. ISO 19109 suggests that
the namespace of all
      * {@code AttributeType} names is the name of the enclosing {@code FeatureType}, but
this is not mandatory.
      * Users who want to apply this convention can invoke {@code setNameSpace(featureName)}
after
      * <code>{@linkplain #setName(CharSequence) FeatureTypeBuilder.setName}(featureName)</code>
but before
-     * <code>{@linkplain AttributeTypeBuilder#setName(CharSequence) AttributeTypeBuilder.setName}(attributeName)</code>.</p>
+     * <code>{@linkplain AttributeTypeBuilder#setName(CharSequence) AttributeTypeBuilder.setName}(attributeName)</code>.
      *
      * @param  ns  the new namespace, or {@code null} if none.
      * @return {@code this} for allowing method calls chaining.

Modified: sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/builder/TypeBuilder.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/builder/TypeBuilder.java?rev=1792065&r1=1792064&r2=1792065&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/builder/TypeBuilder.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/builder/TypeBuilder.java
[UTF-8] Thu Apr 20 14:10:40 2017
@@ -50,6 +50,10 @@ import org.opengis.feature.PropertyNotFo
  *   <li>the description — information beyond that required for concise definition
of the element.</li>
  * </ul>
  *
+ * The name is mandatory and can be specified as either {@link org.opengis.util.LocalName},
+ * {@link org.opengis.util.ScopedName}, {@link String} or {@link InternationalString} instance.
+ * All other properties are optional.
+ *
  * <div class="section">Default namespace</div>
  * In many cases, the names of all {@code AttributeType}s and {@code AssociationRole}s to
create
  * within a {@code FeatureType} share the same namespace.
@@ -59,6 +63,15 @@ import org.opengis.feature.PropertyNotFo
  * Note that namespaces will not be visible in the name {@linkplain org.apache.sis.util.iso.DefaultLocalName#toString()
  * string representation} unless the {@linkplain org.apache.sis.util.iso.DefaultLocalName#toFullyQualifiedName()
fully
  * qualified name} is requested.
+ * Example:
+ *
+ * {@preformat java
+ *     FeatureTypeBuilder builder = new FeatureTypeBuilder().setNameSpace("MyNameSpace").setName("City");
+ *     FeatureType city = builder.build();
+ *
+ *     System.out.println(city.getName());                              // Prints "City"
+ *     System.out.println(city.getName().toFullyQualifiedName());       // Prints "MyNameSpace:City"
+ * }
  *
  * @author  Johann Sorel (Geomatys)
  * @author  Martin Desruisseaux (Geomatys)

Modified: sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/builder/package-info.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/builder/package-info.java?rev=1792065&r1=1792064&r2=1792065&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/builder/package-info.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/builder/package-info.java
[UTF-8] Thu Apr 20 14:10:40 2017
@@ -25,9 +25,11 @@
  * named "Utopia" by default:</p>
  *
  * {@preformat java
+ *     FeatureTypeBuilder builder;
+ *
  *     // Create a feature type for a city, which contains a name and a population.
- *     FeatureTypeBuilder builder = new FeatureTypeBuilder().setName("City");
- *     builder.addAttribute(String.class).setName("name").setDefaultValue("Utopia");
+ *     builder = new FeatureTypeBuilder() .setName("City");
+ *     builder.addAttribute(String.class) .setName("name").setDefaultValue("Utopia");
  *     builder.addAttribute(Integer.class).setName("population");
  *     FeatureType city = builder.build();
  *

Modified: sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/DefaultMetadata.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/DefaultMetadata.java?rev=1792065&r1=1792064&r2=1792065&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/DefaultMetadata.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/DefaultMetadata.java
[UTF-8] Thu Apr 20 14:10:40 2017
@@ -518,6 +518,9 @@ public class DefaultMetadata extends ISO
 
     /**
      * Returns the character coding standard used for the metadata set.
+     * ISO 19115:2014 represents character sets by references to the
+     * <a href="http://www.iana.org/assignments/character-sets">IANA Character Set
register</a>,
+     * which is represented in Java by {@link java.nio.charset.Charset}.
      * Instances can be obtained by a call to {@link Charset#forName(String)}.
      *
      * <div class="note"><b>Examples:</b>

Modified: sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/iso/ResourceInternationalString.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/iso/ResourceInternationalString.java?rev=1792065&r1=1792064&r2=1792065&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/iso/ResourceInternationalString.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/iso/ResourceInternationalString.java
[UTF-8] Thu Apr 20 14:10:40 2017
@@ -138,10 +138,12 @@ public class ResourceInternationalString
      *
      * @param  locale  the locale for which to get the resource bundle.
      * @return the resource bundle for the given locale.
+     * @throws MissingResourceException if no resource bundle can be found for the base name
specified
+     *         at {@linkplain #ResourceInternationalString(String, String) construction time}.
      *
      * @see ResourceBundle#getBundle(String, Locale, ClassLoader)
      */
-    protected ResourceBundle getBundle(final Locale locale) {
+    protected ResourceBundle getBundle(final Locale locale) throws MissingResourceException
{
         return ResourceBundle.getBundle(resources, locale);
     }
 
@@ -157,7 +159,8 @@ public class ResourceInternationalString
      *
      * @param  locale  the desired locale for the string to be returned.
      * @return the string in the specified locale, or in a fallback locale.
-     * @throws MissingResourceException if the key given to the constructor is invalid.
+     * @throws MissingResourceException if no resource can be found for the base name or
for the key
+     *         specified at {@linkplain #ResourceInternationalString(String, String) construction
time}.
      */
     @Override
     public String toString(Locale locale) throws MissingResourceException {



Mime
View raw message