Class FeatureTypeBuilder

  • All Implemented Interfaces:
    Localized

    public class FeatureTypeBuilder
    extends TypeBuilder
    Helper class for the creation of Feature­Type instances. This builder can create the arguments to be given to the feature type constructor from simpler parameters given to this builder. The main methods provided in this class are: The following example creates a city named "Utopia" by default:
    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 System​.out​.println(city) prints the following table:
    City
    ┌────────────┬─────────┬──────────────┬───────────────┐
    │ Name       │ Type    │ Multiplicity │ Default value │
    ├────────────┼─────────┼──────────────┼───────────────┤
    │ name       │ String  │   [1 … 1]    │ Utopia        │
    │ population │ Integer │   [1 … 1]    │               │
    └────────────┴─────────┴──────────────┴───────────────┘

    Feature­Type­Builder instances should be short lived. After the Feature­Type has been created, the builder should be discarded.

    Since:
    0.8
    See Also:
    Parameter­Builder

    Defined in the sis-feature module

    • Constructor Detail

      • FeatureTypeBuilder

        public FeatureTypeBuilder()
        Creates a new builder instance using the default name factory.
      • FeatureTypeBuilder

        public FeatureTypeBuilder​(DefaultFeatureType template)
        Creates a new builder instance using the given feature type as a template. This constructor initializes the list of properties, the super types and is­Abstract flag to values inferred from the given template. The properties list will contain properties declared explicitly in the given template, not including properties inherited from super types.
        Warning: The template argument type will be changed to Feature­Type if and when such interface will be defined in GeoAPI.
        Parameters:
        template - an existing feature type to use as a template, or null if none.
      • FeatureTypeBuilder

        public FeatureTypeBuilder​(NameFactory factory,
                                  GeometryLibrary library,
                                  Locale locale)
        Creates a new builder instance using the given name factory, geometry library and locale for formatting error messages.
        Parameters:
        factory - the factory to use for creating names, or null for the default factory.
        library - the library to use for creating geometric objects, or null for the default.
        locale - the locale to use for formatting error messages, or null for the default locale.
    • Method Detail

      • clear

        public FeatureTypeBuilder clear()
        Clears all setting in this builder. After invoking this method, this Feature­Type­Builder is in same state that after it has been constructed. This method can be invoked for reusing the same builder for creating other Feature­Type instances after build() invocation.
        Returns:
        this for allowing method calls chaining.
      • setAll

        public FeatureTypeBuilder setAll​(DefaultFeatureType template)
        Sets all properties of this builder to the values of the given feature type. This builder is cleared before the properties of the given type are copied. The copy is performed as documented in the constructor.
        Warning: The template argument type will be changed to Feature­Type if and when such interface will be defined in GeoAPI.
        Parameters:
        template - an existing feature type to use as a template, or null if none.
        Returns:
        this for allowing method calls chaining.
      • isAbstract

        public boolean isAbstract()
        Returns true if the feature type to create will act as an abstract super-type. Abstract types can not be instantiated.
        Returns:
        true if the feature type to create will act as an abstract super-type.
        See Also:
        Default­Feature­Type​.is­Abstract()
      • setAbstract

        public FeatureTypeBuilder setAbstract​(boolean isAbstract)
        Sets whether the feature type to create will be abstract. If this method is not invoked, then the default value is false.
        Parameters:
        is­Abstract - whether the feature type will be abstract.
        Returns:
        this for allowing method calls chaining.
      • getSuperTypes

        public DefaultFeatureType[] getSuperTypes()
        Returns the direct parents of the feature type to create.
        Warning: The return type will be changed to Feature­Type[] if and when such interface will be defined in GeoAPI.
        Returns:
        the parents of the feature type to create, or an empty array if none.
        See Also:
        Default­Feature­Type​.get­Super­Types()
      • setSuperTypes

        public FeatureTypeBuilder setSuperTypes​(DefaultFeatureType... parents)
        Sets the parent types (or super-type) from which to inherit properties. If this method is not invoked, then the default value is no parent.
        Warning: The parents argument type will be changed to Feature­Type... if and when such interface will be defined in GeoAPI.
        Parameters:
        parents - the parent types from which to inherit properties, or an empty array if none. Null elements are ignored.
        Returns:
        this for allowing method calls chaining.
      • getNameSpace

        public CharSequence getNameSpace()
        Returns the namespace of the names created by set­Name(Char­Sequence...) method calls. A null value means that the names are in the global namespace.
        Returns:
        the namespace to use when set­Name(Char­Sequence) is invoked, or null if none.
      • setNameSpace

        public FeatureTypeBuilder setNameSpace​(CharSequence ns)
        Sets the namespace of the next names to be created by set­Name(Char­Sequence...) method calls. This method applies only to the next calls to set­Name(Char­Sequence) or set­Name(Char­Sequence...) methods; the result of all previous calls stay unmodified. Example:
        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"
        There is different conventions about the use of name spaces. ISO 19109 suggests that the namespace of all Attribute­Type names is the name of the enclosing Feature­Type, but this is not mandatory. Users who want to apply this convention can invoke set­Name­Space(feature­Name) after Feature­Type­Builder​.set­Name(feature­Name) but before Attribute­Type­Builder​.set­Name(attribute­Name).
        Parameters:
        ns - the new namespace, or null if none.
        Returns:
        this for allowing method calls chaining.
      • setDefaultMultiplicity

        public FeatureTypeBuilder setDefaultMultiplicity​(int minimumOccurs,
                                                         int maximumOccurs)
        Sets the default minimum and maximum number of next attributes and associations to add. Those defaults will applied to newly created attributes or associations, for example in next calls to add­Attribute(Class). Attributes and associations added before this method call are not modified.

        If this method is not invoked, then the default multiplicity is [1 … 1].

        Parameters:
        minimum­Occurs - new default minimum number of property values.
        maximum­Occurs - new default maximum number of property values.
        Returns:
        this for allowing method calls chaining.
        Since:
        1.0
        See Also:
        Property­Type­Builder​.set­Minimum­Occurs(int), Property­Type­Builder​.set­Maximum­Occurs(int)
      • setIdentifierDelimiters

        public FeatureTypeBuilder setIdentifierDelimiters​(String delimiter,
                                                          String prefix,
                                                          String suffix)
        Sets the prefix, suffix and delimiter to use when formatting a compound identifier made of two or more attributes. The delimiter will be used only if at least two attributes have the identifier component role.

        If this method is not invoked, then the default values are the ":" delimiter and no prefix or suffix.

        Parameters:
        delimiter - the characters to use as delimiter between each single property value.
        prefix - characters to use at the beginning of the concatenated string, or null if none.
        suffix - characters to use at the end of the concatenated string, or null if none.
        Returns:
        this for allowing method calls chaining.
        See Also:
        Attribute­Role​.IDENTIFIER_COMPONENT
      • isNameUsed

        public boolean isNameUsed​(String name)
        Returns true if a property of the given name is defined or if the given name is ambiguous. Invoking this method is equivalent to testing if get­Property(name) != null except that this method does not throw exception if the given name is ambiguous.
        Parameters:
        name - the name to test.
        Returns:
        true if the given name is used by another property or is ambiguous.
        Since:
        1.0
      • getProperty

        public PropertyTypeBuilder getProperty​(String name)
        Returns the builder for the property of the given name. The given name does not need to contains all elements of a Scoped­Name; it is okay to specify only the tip (for example "my­Name" instead of "my­Scope:my­Name") provided that ignoring the name head does not create ambiguity.
        Parameters:
        name - name of the property to search.
        Returns:
        property of the given name, or null if none.
        Throws:
        Illegal­Argument­Exception - if the given name is ambiguous.
      • addAttribute

        public <V> AttributeTypeBuilder<V> addAttribute​(Class<V> valueClass)
        Creates a new Attribute­Type builder for values of the given class. The default attribute name is the name of the given type, but callers should invoke one of the Attribute­Type­Builder​.set­Name(…) methods on the returned instance with a better name.

        Usage example:

        builder.addAttribute(String.class).setName("City").setDefaultValue("Metropolis");
        The value class can not be Feature​.class since features shall be handled as associations instead than attributes.
        Type Parameters:
        V - the compile-time value of value­Class argument.
        Parameters:
        value­Class - the class of attribute values (can not be Feature​.class).
        Returns:
        a builder for an Attribute­Type.
        See Also:
        properties()
      • addAttribute

        public <V> AttributeTypeBuilder<V> addAttribute​(DefaultAttributeType<V> template)
        Creates a new Attribute­Type builder initialized to the same characteristics than the given template.
        Warning: The template argument type will be changed to Attribute­Type if and when such interface will be defined in GeoAPI.
        Type Parameters:
        V - the compile-time type of values in the template argument.
        Parameters:
        template - an existing attribute type to use as a template.
        Returns:
        a builder for an Attribute­Type, initialized with the values of the given template.
        See Also:
        properties()
      • addAttribute

        public AttributeTypeBuilder<?> addAttribute​(GeometryType type)
        Creates a new attribute for geometries of the given type. This method delegates to add­Attribute(Class) with a value­Class argument inferred from the combination of the Geometry­Type argument given to this method with the Geometry­Library argument given at builder creation time. The geometry type can be: Geometric objects outside the above list can still be used by declaring their type explicitly. However in this case there is no isolation level between the geometry types and the library that implement them.
        Example: the following code creates an attribute named "MyPoint" with values of class Point2D if the library in use is Java2D. The Coordinate Reference System (CRS) uses (longitude, latitude) axes on the WGS 84 datum. Finally that new attribute is declared the feature default geometry:
        builder.addAttribute(GeometryType.POINT).setName("MyPoint")
               .setCRS(CommonCRS.WGS84.normalizedGeographic())
               .addRole(AttributeRole.DEFAULT_GEOMETRY);
        If the library in use is JTS or ESRI instead than Java2D, then the Point class of those libraries will be used instead of Point2D. The fully-qualified class names are given in the Geometry­Library javadoc.
        Parameters:
        type - kind of geometric object (point, polyline or polygon).
        Returns:
        a builder for an Attribute­Type.
      • addAssociation

        public AssociationRoleBuilder addAssociation​(DefaultFeatureType type)
        Creates a new Feature­Association­Role builder for features of the given type. The default association name is the name of the given type, but callers should invoke one of the Association­Role­Builder​.set­Name(…) methods on the returned instance with a better name.
        Warning: The type argument type will be changed to Feature­Type if and when such interface will be defined in GeoAPI.
        Parameters:
        type - the type of feature values.
        Returns:
        a builder for a Feature­Association­Role.
        See Also:
        properties()
      • addAssociation

        public AssociationRoleBuilder addAssociation​(GenericName type)
        Creates a new Feature­Association­Role builder for features of a type of the given name. This method can be invoked as an alternative to add­Association(Feature­Type) when the Feature­Type instance is not yet available because of cyclic dependency.
        Parameters:
        type - the name of the type of feature values.
        Returns:
        a builder for a Feature­Association­Role.
        See Also:
        properties()
      • addAssociation

        public AssociationRoleBuilder addAssociation​(DefaultAssociationRole template)
        Creates a new Feature­Association­Role builder initialized to the same characteristics than the given template.
        Warning: The template argument type will be changed to Feature­Association­Role if and when such interface will be defined in GeoAPI.
        Parameters:
        template - an existing feature association to use as a template.
        Returns:
        a builder for an Feature­Association­Role, initialized with the values of the given template.
        See Also:
        properties()
      • addProperty

        public PropertyTypeBuilder addProperty​(AbstractIdentifiedType template)
        Adds the given property in the feature type properties. The given property shall be an instance of one of the following types:
        • Attribute­Type, in which case this method delegate to add­Attribute(Attribute­Type).
        • Feature­Association­Role, in which case this method delegate to add­Association(Feature­Association­Role).
        • Operation, in which case the given operation object will be added verbatim in the Feature­Type; this builder does not create new operations.
        Warning: In a future SIS version, the argument type may be changed to the org​.opengis​.feature​.Property­Type interface. This change is pending GeoAPI revision.
        Parameters:
        template - the property to add to the feature type.
        Returns:
        a builder initialized to the given builder. In the Operation case, the builder is a read-only accessor on the operation properties.
        See Also:
        properties(), get­Property(String)
      • build

        public DefaultFeatureType build()
                                 throws IllegalStateException
        Builds the feature type from the information and properties specified to this builder. One of the set­Name(…) methods must have been invoked before this build() method (mandatory). All other methods are optional, but some calls to a add method are usually needed.
        Warning: In a future SIS version, the return type may be changed to the org​.opengis​.feature​.Feature­Type interface. This change is pending GeoAPI revision.

        If a feature type has already been built and this builder state has not changed since the feature type creation, then the previously created Feature­Type instance is returned.

        Specified by:
        build in class Type­Builder
        Returns:
        the feature type.
        Throws:
        Illegal­State­Exception - if the builder contains inconsistent information.
        See Also:
        clear()