You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sis.apache.org by de...@apache.org on 2017/04/20 14:10:40 UTC
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/
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
+ * \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+ * \u2502 Name \u2502 Type \u2502 Cardinality \u2502 Default value \u2502
+ * \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524
+ * \u2502 name \u2502 String \u2502 [1 \u2026 1] \u2502 Utopia \u2502
+ * \u2502 population \u2502 Integer \u2502 [1 \u2026 1] \u2502 \u2502
+ * \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
+ * }
+ *
+ *
+ *
+ * <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 \u2014 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 {