Package org.apache.sis.feature.builder

Class TypeBuilder

java.lang.Object
org.apache.sis.feature.builder.TypeBuilder
All Implemented Interfaces:
Localized
Direct Known Subclasses:
CharacteristicTypeBuilder, FeatureTypeBuilder, PropertyTypeBuilder
public abstract class TypeBuilder extends Object implements Localized
Information common to all kind of types (feature, association, characteristics). Those information are:
  • the name — a unique name which can be defined within a scope (or namespace).
  • the definition — a concise definition of the element.
  • the designation — a natural language designator for the element for user interfaces.
  • the description — information beyond that required for concise definition of the element.
The name is mandatory and can be specified as either LocalName, ScopedName, String or InternationalString instance. All other properties are optional.

Default namespace

In many cases, the names of all AttributeTypes and AssociationRoles to create within a FeatureType share the same namespace. For making name creations more convenient, the namespace can be specified once and applied automatically to all names created by the setName(CharSequence) method. Note that namespaces will not be visible in the name string representation unless the fully qualified name is requested. Example:
Since:
0.8
Version:
0.8

  • Field Details

    • identification

      private final Map<String,Object> identification
      The feature name, definition, designation and description. The name is mandatory; all other information are optional.

  • Constructor Details

  • Method Details

    • reset

      final void reset()
      Resets the identification map. After invoking this method, this TypeBuilder is in same state that after it has been constructed.
      See Also:

    • initialize

      final void initialize(AbstractIdentifiedType template)
      Initializes this builder to the value of the given type. The caller is responsible to invoke reset() (if needed) before this method.

    • putIfNonNull

      private void putIfNonNull(String key, Object value)
      Puts the given value in the identification map if the value is non-null. This method should be invoked only when the identification map is known to not contain any value for the given key.

    • identification

      final Map<String,Object> identification()
      Returns the map of properties to give to the FeatureType or PropertyType constructor. If the map does not contains a name, a default name may be generated.

    • clearCache

      abstract void clearCache()
      If the object created by the last call to build() has been cached, clears that cache.
      See Also:

    • createLocalName

      abstract org.opengis.util.GenericName createLocalName(CharSequence name)
      Creates a local name in the feature namespace.

    • createGenericName

      abstract org.opengis.util.GenericName createGenericName(CharSequence... names)
      Creates a generic name in the feature namespace.

    • getName

      public org.opengis.util.GenericName getName()
      Returns the name of the IdentifiedType to create, or null if undefined. This method returns the value built from the last call to a setName(…) method, or a default name or null if no name has been explicitly specified.
      Returns:
      the name of the IdentifiedType to create (may be a default name or null).
      See Also:

    • getDefaultName

      String getDefaultName()
      Returns a default name to use if the user did not specified a name. The first letter will be changed to lower case (unless the name looks like an acronym) for compliance with Java convention on property names.

    • getDisplayName

      final String getDisplayName()
      Returns the name to use for displaying error messages.

    • setName

      public TypeBuilder setName(org.opengis.util.GenericName name)
      Sets the IdentifiedType name as a generic name. If another name was defined before this method call, that previous value will be discarded.
      Note for subclasses: all setName(…) convenience methods in this builder delegate to this method. Consequently, this method can be used as a central place where to control the creation of all names.
      Parameters:
      name - the generic name (cannot be null).
      Returns:
      this for allowing method calls chaining.
      See Also:

    • setName

      public TypeBuilder setName(CharSequence localPart)
      Sets the IdentifiedType name as a simple string (local name). The namespace will be the value specified by the last call to FeatureTypeBuilder.setNameSpace(CharSequence), but that namespace will not be visible in the string representation unless the fully qualified name is requested.

      This convenience method creates a LocalName instance from the given CharSequence, then delegates to setName(GenericName).

      Parameters:
      localPart - the local part of the generic name as a String or InternationalString.
      Returns:
      this for allowing method calls chaining.
      See Also:

    • setName

      public TypeBuilder setName(CharSequence... components)
      Sets the IdentifiedType name as a string in the given scope. The components array must contain at least one element. The last component (the tip) will be sufficient in many cases for calls to the AbstractFeature.getProperty(String) method. The other elements before the last one are optional and can be used for resolving ambiguity. They will be visible as the name path.
      Example: a call to setName("A", "B", "C") will create a "A:B:C" name. A property built with this name can be obtained from a feature by a call to feature.getProperty("C") if there is no ambiguity, or otherwise by a call to feature.getProperty("B:C") (if non-ambiguous) or feature.getProperty("A:B:C").
      In addition to the path specified by the components array, the name may also contain a namespace specified by the last call to FeatureTypeBuilder.setNameSpace(CharSequence). But contrarily to the specified components, the namespace will not be visible in the name string representation unless the fully qualified name is requested.

      This convenience method creates a LocalName or ScopedName instance depending on whether the names array contains exactly 1 element or more than 1 element, then delegates to setName(GenericName).

      Parameters:
      components - the name components as an array of String or InternationalString instances.
      Returns:
      this for allowing method calls chaining.
      See Also:

    • getDefinition

      public CharSequence getDefinition()
      Returns a concise definition of the element.
      Returns:
      concise definition of the element, or null if none.
      See Also:

    • setDefinition

      public TypeBuilder setDefinition(CharSequence definition)
      Sets a concise definition of the element.
      Parameters:
      definition - a concise definition of the element, or null if none.
      Returns:
      this for allowing method calls chaining.
      See Also:

    • getDesignation

      public CharSequence getDesignation()
      Returns a natural language designator for the element. This can be used as an alternative to the name in user interfaces.
      Returns:
      natural language designator for the element, or null if none.
      See Also:

    • setDesignation

      public TypeBuilder setDesignation(CharSequence designation)
      Sets a natural language designator for the element. This can be used as an alternative to the name in user interfaces.
      Parameters:
      designation - a natural language designator for the element, or null if none.
      Returns:
      this for allowing method calls chaining.
      See Also:

    • getDescription

      public CharSequence getDescription()
      Returns optional information beyond that required for concise definition of the element. The description may assist in understanding the element scope and application.
      Returns:
      information beyond that required for concise definition of the element, or null if none.
      See Also:

    • setDescription

      public TypeBuilder setDescription(CharSequence description)
      Sets optional information beyond that required for concise definition of the element. The description may assist in understanding the feature scope and application. If the type is deprecated, then the description should give indication about the replacement (e.g. "superceded by …").
      Parameters:
      description - information beyond that required for concise definition of the element, or null if none.
      Returns:
      this for allowing method calls chaining.
      See Also:

    • isDeprecated

      public boolean isDeprecated()
      Returns true if the type is deprecated. If this method returns true, then the description should give indication about the replacement (e.g. "superceded by …").
      Returns:
      whether this type is deprecated.
      See Also:

    • setDeprecated

      public TypeBuilder setDeprecated(boolean deprecated)
      Sets whether the type is deprecated. If the type is deprecated, then the description should be set to an indication about the replacement (e.g. "superceded by …").
      Parameters:
      deprecated - whether this type is deprecated.
      Returns:
      this for allowing method calls chaining.
      See Also:

    • forName

      final <E extends TypeBuilder> E forName(List<E> types, String name, boolean nonAmbiguous)
      Returns the element of the given name in the given list. The given name does not need to contains all elements of a ScopedName; it can be only the tip (for example "myName" instead of "myScope:myName") provided that ignoring the name head does not create ambiguity.
      Parameters:
      types - the collection where to search for an element of the given name.
      name - name of the element to search.
      nonAmbiguous - whether to throw an exception if the given name is ambiguous.
      Returns:
      element of the given name, or null if none were found.
      Throws:
      IllegalArgumentException - if the given name is ambiguous.

    • getLocale

      public Locale getLocale()
      Returns the locale used for formatting error messages, or null if unspecified. If unspecified, the system default locale will be used.
      Specified by:
      getLocale in interface Localized
      Returns:
      the locale used for formatting error messages, or null if unspecified.

    • errors

      final Errors errors()
      Returns the resources for error messages.

    • resources

      final Resources resources()
      Returns the sis-feature specific resources for error messages.

    • ensureNonNull

      final void ensureNonNull(String name, Object value)
      Same as ArgumentChecks.ensureNonNull(String, Object), but uses the current locale in case of error.
      Parameters:
      name - the name of the argument to be checked. Used only if an exception is thrown.
      value - the user argument to check against null value.
      Throws:
      NullArgumentException - if object is null.

    • ensureAlive

      final void ensureAlive(TypeBuilder owner)
      Ensures that this instance is still alive.
      Parameters:
      owner - the owner of this instance. A value of null means that this instance should not be used any more.

    • ensureNonEmpty

      final void ensureNonEmpty(String name, CharSequence text)
      Same as ArgumentChecks.ensureNonEmpty(String, CharSequence), but uses the current locale in case of error.
      Parameters:
      name - the name of the argument to be checked. Used only if an exception is thrown.
      text - the user argument to check against null value and empty sequences.
      Throws:
      NullArgumentException - if text is null.
      IllegalArgumentException - if text is empty.

    • toString

      public String toString()
      Returns a string representation of this object. The returned string is for debugging purpose only and may change in any future SIS version.
      Overrides:
      toString in class Object
      Returns:
      a string representation of this object for debugging purpose.

    • appendStringTo

      final StringBuilder appendStringTo(StringBuilder buffer)
      Partial implementation of toString(). This method assumes that the class name has already be written in the buffer.

    • toStringInternal

      void toStringInternal(StringBuilder buffer)
      Appends a text inside the value returned by toString(), before the closing bracket.

    • remove

      void remove()
      Invoked when a type builder has been removed from its parent. Subclasses should override this method in a way that flag the builder as not usable anymore.

    • build

      public abstract AbstractIdentifiedType build() throws IllegalStateException
      Builds the feature or property type from the information specified to this builder. If a type has already been built and this builder state has not changed since the type creation, then the previously created IdentifiedType instance is returned.
      Warning: In a future SIS version, the return type may be changed to the org.opengis.feature.IdentifiedType interface. This change is pending GeoAPI revision.
      Returns:
      the feature or property type.
      Throws:
      IllegalStateException - if the builder contains inconsistent information.