SimpleFeatureBuilder (Geotools modules 20-SNAPSHOT API)

Object
- FeatureBuilder<FeatureType,Feature>
- - SimpleFeatureBuilder

public class SimpleFeatureBuilder
extends FeatureBuilder<FeatureType,Feature>

A builder for features.

Simple Usage:

  //type of features we would like to build ( assume schema = (geom:Point,name:String) )
  SimpleFeatureType featureType = ...  
 
   //create the builder
  SimpleFeatureBuilder builder = new SimpleFeatureBuilder();
  
  //set the type of created features
  builder.setType( featureType );
  
  //add the attributes
  builder.add( new Point( 0 , 0 ) );
  builder.add( "theName" );
  
  //build the feature
  SimpleFeature feature = builder.buildFeature( "fid" );

This builder builds a feature by maintaining state. Each call to add(Object) creates a new attribute for the feature and stores it locally. When using the add method to add attributes to the feature, values added must be added in the same order as the attributes as defined by the feature type. The methods set(String, Object) and set(int, Object) are used to add attributes out of order.

Each time the builder builds a feature with a call to buildFeature(String) the internal state is reset.

This builder can be used to copy features as well. The following code sample demonstrates:

  //original feature
  SimpleFeature original = ...;
 
  //create and initialize the builder
  SimpleFeatureBuilder builder = new SimpleFeatureBuilder();
  builder.init(original);
 
  //create the new feature
  SimpleFeature copy = builder.buildFeature( original.getID() );

The builder also provides a number of static "short-hand" methods which can be used when its not ideal to instantiate a new builder, thought this will trigger some extra object allocations. In time critical code sections it's better to instantiate the builder once and use it to build all the required features.

   SimpleFeatureType type = ..;
   Object[] values = ...;
   
   //build a new feature
   SimpleFeature feature = SimpleFeatureBuilder.build( type, values, "fid" );
   
   ...
   
   SimpleFeature original = ...;
   
   //copy the feature
   SimpleFeature feature = SimpleFeatureBuilder.copy( original );

This class is not thread safe nor should instances be shared across multiple threads.

Author:: Justin Deoliveira, Jody Garnett

Constructor Summary

Constructors
Constructor and Description
`SimpleFeatureBuilder(SimpleFeatureType featureType)`
`SimpleFeatureBuilder(SimpleFeatureType featureType, FeatureFactory factory)`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`add(Object value)` Adds an attribute.
`void`	`addAll(List<Object> values)` Adds a list of attributes.
`void`	`addAll(Object[] values)` Adds an array of attributes.
`static SimpleFeature`	`build(SimpleFeatureType type, List<Object> values, String id)` * Static method to build a new feature.
`static SimpleFeature`	`build(SimpleFeatureType type, Object[] values, String id)` Static method to build a new feature.
`SimpleFeature`	`buildFeature(String id)` Builds the feature.
`SimpleFeature`	`buildFeature(String id, Object[] values)` Quickly builds the feature using the specified values and id
`static SimpleFeature`	`copy(SimpleFeature original)` Copy an existing feature (the values are reused so be careful with mutable values).
`static SimpleFeature`	`deep(SimpleFeature original)` Perform a "deep copy" an existing feature resuling in a duplicate of any geometry attributes.
`SimpleFeatureBuilder`	`featureUserData(Object key, Object value)` Sets a feature wide use data key/value pair.
`SimpleFeatureType`	`getFeatureType()` Returns the simple feature type used by this builder as a feature template
`void`	`init(SimpleFeature feature)` Initialize the builder with the provided feature.
`boolean`	`isValidating()`
`void`	`reset()`
`static SimpleFeature`	`retype(SimpleFeature feature, SimpleFeatureBuilder builder)` Copies an existing feature, retyping it in the process.
`static SimpleFeature`	`retype(SimpleFeature feature, SimpleFeatureType featureType)` Copies an existing feature, retyping it in the process.
`void`	`set(int index, Object value)` Adds an attribute value by index. * This method can be used to add attribute values out of order.
`void`	`set(Name name, Object value)` Adds an attribute value by name.
`void`	`set(String name, Object value)` Adds an attribute value by name.
`SimpleFeatureBuilder`	`setUserData(int index, Object key, Object value)`
`void`	`setValidating(boolean validating)`
`static SimpleFeature`	`template(SimpleFeatureType featureType, String featureId)` Builds a new feature whose attribute values are the default ones
`SimpleFeatureBuilder`	`userData(Object key, Object value)` Adds some user data to the next attributed added to the feature.

Methods inherited from class FeatureBuilder
convert, createDefaultFeatureId, createDefaultFeatureIdentifier

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - SimpleFeatureBuilder
```
public SimpleFeatureBuilder(SimpleFeatureType featureType)
```
  - SimpleFeatureBuilder
```
public SimpleFeatureBuilder(SimpleFeatureType featureType,
                            FeatureFactory factory)
```
- Method Detail
  - reset
```
public void reset()
```
  - getFeatureType
```
public SimpleFeatureType getFeatureType()
```
    Returns the simple feature type used by this builder as a feature template
    
    Overrides:
    
    getFeatureType in class FeatureBuilder<FeatureType,Feature>
    
    Returns:
  - init
```
public void init(SimpleFeature feature)
```
    Initialize the builder with the provided feature.
    This method adds all the attributes from the provided feature. It is useful when copying a feature.
  - add
```
public void add(Object value)
```
    Adds an attribute.
    This method should be called repeatedly for the number of attributes as specified by the type of the feature.
  - addAll
```
public void addAll(List<Object> values)
```
    Adds a list of attributes.
  - addAll
```
public void addAll(Object[] values)
```
    Adds an array of attributes.
  - set
```
public void set(Name name,
                Object value)
```
    Adds an attribute value by name.
    This method can be used to add attribute values out of order.
    
    Parameters:
    
    name - The name of the attribute.
    
    value - The value of the attribute.
    
    Throws:
    
    IllegalArgumentException - If no such attribute with teh specified name exists.
  - set
```
public void set(String name,
                Object value)
```
    Adds an attribute value by name.
    This method can be used to add attribute values out of order.
    
    Parameters:
    
    name - The name of the attribute.
    
    value - The value of the attribute.
    
    Throws:
    
    IllegalArgumentException - If no such attribute with teh specified name exists.
  - set
```
public void set(int index,
                Object value)
```
    Adds an attribute value by index. *
    This method can be used to add attribute values out of order.
    
    Parameters:
    
    index - The index of the attribute.
    
    value - The value of the attribute.
  - buildFeature
```
public SimpleFeature buildFeature(String id)
```
    Builds the feature.
    The specified id may be null. In this case an id will be generated internally by the builder.
    
    After this method returns, all internal builder state is reset.
    
    Specified by:
    
    buildFeature in class FeatureBuilder<FeatureType,Feature>
    
    Parameters:
    
    id - The id of the feature, or null.
    
    Returns:
    
    The new feature.
  - buildFeature
```
public SimpleFeature buildFeature(String id,
                                  Object[] values)
```
    Quickly builds the feature using the specified values and id
    
    Parameters:
    
    id -
    
    values -
    
    Returns:
  - build
```
public static SimpleFeature build(SimpleFeatureType type,
                                  Object[] values,
                                  String id)
```
    Static method to build a new feature.
    If multiple features need to be created, this method should not be used and instead an instance should be instantiated directly.
    
    This method is a short-hand convenience which creates a builder instance internally and adds all the specified attributes.
    
    Parameters:
    
    type - SimpleFeatureType defining the structure for the created feature
    
    values - Attribute values, must be in the order defined by SimpleFeatureType
    
    id - FeatureID for the generated feature, use null to allow one to be supplied for you
  - build
```
public static SimpleFeature build(SimpleFeatureType type,
                                  List<Object> values,
                                  String id)
```
    * Static method to build a new feature.
    If multiple features need to be created, this method should not be used and instead an instance should be instantiated directly.
    
    Parameters:
    
    type - SimpleFeatureType defining the structure for the created feature
    
    values - Attribute values, must be in the order defined by SimpleFeatureType
    
    id - FeatureID for the generated feature, use null to allow one to be supplied for you
  - copy
```
public static SimpleFeature copy(SimpleFeature original)
```
    Copy an existing feature (the values are reused so be careful with mutable values).
    If multiple features need to be copied, this method should not be used and instead an instance should be instantiated directly.
    
    This method is a short-hand convenience which creates a builder instance and initializes it with the attributes from the specified feature.
  - deep
```
public static SimpleFeature deep(SimpleFeature original)
```
    Perform a "deep copy" an existing feature resuling in a duplicate of any geometry attributes.
    This method is scary, expensive and will result in a deep copy of Geometry which may take a significant amount of memory/time to perform.
    
    Parameters:
    
    original - Content
    
    Returns:
    
    copy
  - template
```
public static SimpleFeature template(SimpleFeatureType featureType,
                                     String featureId)
```
    Builds a new feature whose attribute values are the default ones
    
    Parameters:
    
    featureType -
    
    featureId -
    
    Returns:
  - retype
```
public static SimpleFeature retype(SimpleFeature feature,
                                   SimpleFeatureType featureType)
```
    Copies an existing feature, retyping it in the process.
    Be warned, this method will create its own SimpleFeatureBuilder, which will trigger a scan of the SPI looking for the current default feature factory, which is expensive and has scalability issues.
    If you need good performance consider using retype(SimpleFeature, SimpleFeatureBuilder) instead.
    If the feature type contains attributes in which the original feature does not have a value for, the value in the resulting feature is set to null.
    
    Parameters:
    
    feature - The original feature.
    
    featureType - The target feature type.
    
    Returns:
    
    The copied feature, with a new type.
  - retype
```
public static SimpleFeature retype(SimpleFeature feature,
                                   SimpleFeatureBuilder builder)
```
    Copies an existing feature, retyping it in the process.
    If the feature type contains attributes in which the original feature does not have a value for, the value in the resulting feature is set to null.
    
    Parameters:
    
    feature - The original feature.
    
    SimpleFeatureBuilder - A builder for the target feature type
    
    Returns:
    
    The copied feature, with a new type.
    
    Since:
    
    2.5.3
  - userData
```
public SimpleFeatureBuilder userData(Object key,
                                     Object value)
```
    Adds some user data to the next attributed added to the feature.
    This value is reset when the next attribute is added.
    
    Parameters:
    
    key - The key of the user data
    
    value - The value of the user data.
  - setUserData
```
public SimpleFeatureBuilder setUserData(int index,
                                        Object key,
                                        Object value)
```
  - featureUserData
```
public SimpleFeatureBuilder featureUserData(Object key,
                                            Object value)
```
    Sets a feature wide use data key/value pair. The user data map is reset when the feature is built
    
    Parameters:
    
    key -
    
    value -
    
    Returns:
  - isValidating
```
public boolean isValidating()
```
  - setValidating
```
public void setValidating(boolean validating)
```

Class SimpleFeatureBuilder

Constructor Summary

Method Summary

Methods inherited from class FeatureBuilder

Methods inherited from class Object

Constructor Detail

SimpleFeatureBuilder

SimpleFeatureBuilder

Method Detail

reset

getFeatureType

init

add

addAll

addAll

set

set

set

buildFeature

buildFeature

build

build

copy

deep

template

retype

retype

userData

setUserData

featureUserData

isValidating

setValidating