org.gdal.ogr
Class Layer

java.lang.Object
  extended by org.gdal.ogr.Layer

public class Layer
extends Object

This class represents a layer of simple features, with access methods.

The Layer class is a binding for the C++ OGRLayer class.


Method Summary
 int AlterFieldDefn(int iField, FieldDefn newFieldDefn, int nFlags)
          Alter the definition of an existing field on a layer.
 int CommitTransaction()
          For datasources which support transactions, CommitTransaction commits a transaction.
 int CreateFeature(Feature feature)
          Create and write a new feature within a layer.
 int CreateField(FieldDefn field_def)
          Create a new field on a layer.
 int CreateField(FieldDefn field_def, int approx_ok)
          Create a new field on a layer.
 void delete()
          Deprecated. Do not do anything...
 int DeleteFeature(int fid)
          Delete feature from layer.
 int DeleteField(int iField)
          Delete an existing field on a layer.
 boolean equals(Object obj)
           
 double[] GetExtent()
          Fetch the extent of this layer.
 double[] GetExtent(boolean force)
          Fetch the extent of this layer.
 int GetExtent(double[] extent, int force)
          Fetch the extent of this layer.
 Feature GetFeature(int fid)
          Fetch a feature by its identifier.
 int GetFeatureCount()
          Fetch the feature count in this layer.
 int GetFeatureCount(int force)
          Fetch the feature count in this layer.
 long GetFeaturesRead()
          Return the total number of features read.
 String GetFIDColumn()
          Returns the name of the FID column.
 String GetGeometryColumn()
          Returns the name of the geometry column.
 int GetGeomType()
          Return the layer geometry type.
 FeatureDefn GetLayerDefn()
          Fetch the schema information for this layer.
 String GetName()
          Return the layer name.
 Feature GetNextFeature()
          Fetch the next available feature from this layer.
 int GetRefCount()
          Fetch reference count.
 Geometry GetSpatialFilter()
          Return the current spatial filter for this layer.
 SpatialReference GetSpatialRef()
          Fetch the spatial reference system for this layer.
 int hashCode()
           
 int ReorderField(int iOldFieldPos, int iNewFieldPos)
          Reorder an existing field on a layer.
 int ReorderFields(int[] panMap)
          Reorder all the fields of a layer.
 void ResetReading()
          Reset feature reading to start on the first feature.
 int RollbackTransaction()
          For datasources which support transactions, RollbackTransaction will roll back a datasource to its state before the start of the current transaction.
 int SetAttributeFilter(String filter_string)
          Set a new attribute query.
 int SetFeature(Feature feature)
          Rewrite an existing feature.
 int SetIgnoredFields(Vector fieldNames)
          Set which fields can be omitted when retrieving features from the layer.
 int SetNextByIndex(int new_index)
          Move read cursor to the new_index'th feature in the current resultset.
 void SetSpatialFilter(Geometry filter)
          Set a new spatial filter.
 void SetSpatialFilterRect(double minx, double miny, double maxx, double maxy)
          Set a new rectangular spatial filter.
 int StartTransaction()
          For datasources which support transactions, StartTransaction creates a transaction.
 int SyncToDisk()
          Flush pending changes to disk.
 boolean TestCapability(String cap)
          Test if this layer supported the named capability.
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

delete

public void delete()
Deprecated. Do not do anything...


equals

public boolean equals(Object obj)
Overrides:
equals in class Object

hashCode

public int hashCode()
Overrides:
hashCode in class Object

GetExtent

public double[] GetExtent(boolean force)
Fetch the extent of this layer.

Returns the extent (MBR) of the data in the layer. If force is false, and it would be expensive to establish the extent then a null value will be returned indicating that the extent isn't know. If force is true then some implementations will actually scan the entire layer once to compute the MBR of all the features in the layer.

Depending on the drivers, the returned extent may or may not take the spatial filter into account. So it is safer to call GetExtent() without setting a spatial filter.

Layers without any geometry may return a null value just indicating that no meaningful extents could be collected.

Parameters:
force - Flag indicating whether the extent should be computed even if it is expensive
Returns:
an allocated array of 4 doubles in which the extent value or null in case of failure
Since:
Java bindings 1.7.0

GetExtent

public double[] GetExtent()
Fetch the extent of this layer. Same as below with force == true.

Since:
Java bindings 1.7.0
See Also:
GetExtent(boolean force)

GetRefCount

public int GetRefCount()
Fetch reference count.

Should be of little use in Java...

Returns:
the current reference count for the layer object itself.

SetSpatialFilter

public void SetSpatialFilter(Geometry filter)
Set a new spatial filter.

This method set the geometry to be used as a spatial filter when fetching features via the GetNextFeature() method. Only features that geometrically intersect the filter geometry will be returned.

Currently this test is may be inaccurately implemented, but it is guaranteed that all features who's envelope (as returned by Geometry.getEnvelope()) overlaps the envelope of the spatial filter will be returned. This can result in more shapes being returned that should strictly be the case.

This method makes an internal copy of the passed geometry. The passed geometry remains the responsibility of the caller, and may be safely destroyed.

For the time being the passed filter geometry should be in the same SRS as the layer (as returned by GetSpatialRef()). In the future this may be generalized.

Parameters:
filter - the geometry to use as a filtering region. null may be passed indicating that the current spatial filter should be cleared, but no new one instituted.

SetSpatialFilterRect

public void SetSpatialFilterRect(double minx,
                                 double miny,
                                 double maxx,
                                 double maxy)
Set a new rectangular spatial filter. This method set rectangle to be used as a spatial filter when fetching features via the GetNextFeature() method method. Only features that geometrically intersect the given rectangle will be returned.

The x/y values should be in the same coordinate system as the layer as a whole (as returned by GetSpatialRef()). Internally this method is normally implemented as creating a 5 vertex closed rectangular polygon and passing it to SetSpatialFilter(). It exists as a convenience.

The only way to clear a spatial filter set with this method is to call SetSpatialFilter(null).

Parameters:
minx - the minimum X coordinate for the rectangular region.
miny - the minimum Y coordinate for the rectangular region.
maxx - the maximum X coordinate for the rectangular region.
maxy - the maximum Y coordinate for the rectangular region.

GetSpatialFilter

public Geometry GetSpatialFilter()
Return the current spatial filter for this layer.

Returns:
spatial filter geometry, or null if there isn't one.

SetAttributeFilter

public int SetAttributeFilter(String filter_string)
Set a new attribute query.

This method sets the attribute query string to be used when fetching features via the GetNextFeature() method. Only features for which the query evaluates as true will be returned.

The query string should be in the format of an SQL WHERE clause. For instance "population > 1000000 and population < 5000000" where population is an attribute in the layer. The query format is a restricted form of SQL WHERE clause as defined "eq_format=restricted_where" about half way through this document:

   Proposal 6.2: Capabilities Metadata
  
Note that installing a query string will generally result in resetting the current reading position (ala ResetReading()).

Parameters:
filter_string - query in restricted SQL WHERE format, or null to clear the current query.
Returns:
0 if successfully installed. Otherwise throws a RuntimeException (or an error code if DontUseExceptions() has been called).

ResetReading

public void ResetReading()
Reset feature reading to start on the first feature. This affects GetNextFeature().


GetName

public String GetName()
Return the layer name.

This returns the same content as GetLayerDefn().GetName(), but for a few drivers, calling GetName() directly can avoid lengthy layer definition initialization.

Returns:
the layer name

GetGeomType

public int GetGeomType()
Return the layer geometry type.

This returns the same result as GetLayerDefn().GetGeomType(), but for a few drivers, calling GetGeomType() directly can avoid lengthy layer definition initialization.

Returns:
the geometry name
Since:
OGR 1.8.0

GetGeometryColumn

public String GetGeometryColumn()
Returns the name of the geometry column.

This method returns the name of the underlying database column being used as the geometry column, or "" if not supported.

Returns:
fid column name.

GetFIDColumn

public String GetFIDColumn()
Returns the name of the FID column.

This method returns the name of the underlying database column being used as the FID column, or "" if not supported.

Returns:
fid column name.

GetFeature

public Feature GetFeature(int fid)
Fetch a feature by its identifier. This function will attempt to read the identified feature. The fid value cannot be OGRNullFID. Success or failure of this operation is unaffected by the spatial or attribute filters.

If this method returns a non-null feature, it is guaranteed that its feature id (Feature.GetFID()) will be the same as fid.

Use Layer.TestCapability(ogr.OLCRandomRead) to establish if this layer supports efficient random access reading via GetFeature(); however, the call should always work if the feature exists as a fallback implementation just scans all the features in the layer looking for the desired feature.

Sequential reads are generally considered interrupted by a GetFeature() call.

The returned feature will be properly handled by the Java garbage collector, but you can help it by explicitely calling the Feature.delete() method.

Parameters:
fid - the feature id of the feature to read.
Returns:
a feature, or null on failure.

GetNextFeature

public Feature GetNextFeature()
Fetch the next available feature from this layer.

Only features matching the current spatial filter (set with SetSpatialFilter() will be returned.

This method implements sequential access to the features of a layer. The ResetReading() method can be used to start at the beginning again.

The returned feature will be properly handled by the Java garbage collector, but you can help it by explicitely calling the Feature.delete() method.

Returns:
a feature, or null if no more features are available.

SetNextByIndex

public int SetNextByIndex(int new_index)
Move read cursor to the new_index'th feature in the current resultset.

This method allows positioning of a layer such that the GetNextFeature() call will read the requested feature, where nIndex is an absolute index into the current result set. So, setting it to 3 would mean the next feature read with GetNextFeature() would have been the 4th feature to have been read if sequential reading took place from the beginning of the layer, including accounting for spatial and attribute filters.

Only in rare circumstances is SetNextByIndex() efficiently implemented. In all other cases the default implementation which calls ResetReading() and then calls GetNextFeature() nIndex times is used. To determine if fast seeking is available on the current layer use the TestCapability() method with a value of OLCFastSetNextByIndex.

Parameters:
new_index - the index indicating how many steps into the result set to seek.
Returns:
0 on success. Otherwise throws a RuntimeException (or an error code if DontUseExceptions() has been called).

SetFeature

public int SetFeature(Feature feature)
Rewrite an existing feature.

This method will write a feature to the layer, based on the feature id within the Feature.

Use Layer.TestCapability(ogr.OLCRandomWrite) to establish if this layer supports random access writing via SetFeature().

Parameters:
feature - the feature to write.
Returns:
0 on success. Otherwise throws a RuntimeException (or an error code if DontUseExceptions() has been called).
See Also:
CreateFeature(Feature)

CreateFeature

public int CreateFeature(Feature feature)
Create and write a new feature within a layer.

The passed feature is written to the layer as a new feature, rather than overwriting an existing one. If the feature has a feature id other than OGRNullFID, then the native implementation may use that as the feature id of the new feature, but not necessarily. Upon successful return the passed feature will have been updated with the new feature id.

Parameters:
feature - the feature to write to disk.
Returns:
0 on success. Otherwise throws a RuntimeException (or an error code if DontUseExceptions() has been called).
See Also:
SetFeature(Feature)

DeleteFeature

public int DeleteFeature(int fid)
Delete feature from layer. The feature with the indicated feature id is deleted from the layer if supported by the driver. Most drivers do not support feature deletion, and will throw a RuntimeException. The TestCapability() layer method may be called with OLCDeleteFeature to check if the driver supports feature deletion.

Parameters:
fid - the feature id to be deleted from the layer
Returns:
0 on success. Otherwise throws a RuntimeException (or an error code if DontUseExceptions() has been called).

SyncToDisk

public int SyncToDisk()
Flush pending changes to disk.

This call is intended to force the layer to flush any pending writes to disk, and leave the disk file in a consistent state. It would not normally have any effect on read-only datasources.

Some layers do not implement this method, and will still return 0. The default implementation just returns 0. An error is only returned if an error occurs while attempting to flush to disk.

Returns:
0 if no error occurs (even if nothing is done). Otherwise throws a RuntimeException (or an error code if DontUseExceptions() has been called).

GetLayerDefn

public FeatureDefn GetLayerDefn()
Fetch the schema information for this layer.

The returned FeatureDefn is owned by the Layer, and should not be modified or freed by the application. It encapsulates the attribute schema of the features of the layer.

Returns:
feature definition.

GetFeatureCount

public int GetFeatureCount(int force)
Fetch the feature count in this layer.

Returns the number of features in the layer. For dynamic databases the count may not be exact. If force is 0, and it would be expensive to establish the feature count a value of -1 may be returned indicating that the count isn't know. If force is 1 some implementations will actually scan the entire layer once to count objects.

The returned count takes the spatial filter into account.

Parameters:
force - Flag indicating whether the count should be computed even if it is expensive.
Returns:
feature count, -1 if count not known.

GetFeatureCount

public int GetFeatureCount()
Fetch the feature count in this layer.

Same as below with force == 1.

Since:
Java bindings 1.7.0
See Also:
GetFeatureCount(int force)

GetExtent

public int GetExtent(double[] extent,
                     int force)
Fetch the extent of this layer.

Returns the extent (MBR) of the data in the layer. If force is 0, and it would be expensive to establish the extent then a RuntimeException will be throwned indicating that the extent isn't know. If force is 1 then some implementations will actually scan the entire layer once to compute the MBR of all the features in the layer.

Depending on the drivers, the returned extent may or may not take the spatial filter into account. So it is safer to call GetExtent() without setting a spatial filter.

Layers without any geometry may throw a RuntimeException just indicating that no meaningful extents could be collected.

Parameters:
extent - an allocated array of 4 doubles in which the extent value will be returned.
force - Flag indicating whether the extent should be computed even if it is expensive (1 for true, 0 for false).
Returns:
0 on success. Otherwise throws a RuntimeException (or an error code if DontUseExceptions() has been called).

TestCapability

public boolean TestCapability(String cap)
Test if this layer supported the named capability.

The capability codes that can be tested are represented as strings, but ogrConstants constants exists to ensure correct spelling. Specific layer types may implement class specific capabilities, but this can't generally be discovered by the caller.

Parameters:
cap - the name of the capability to test.
Returns:
true if the layer has the requested capability, or false otherwise. Layers will return false for any unrecognised capabilities.


CreateField

public int CreateField(FieldDefn field_def,
                       int approx_ok)
Create a new field on a layer.

You must use this to create new fields on a real layer. Internally the FeatureDefn for the layer will be updated to reflect the new field. Applications should never modify the FeatureDefn used by a layer directly.

This method should not be called while there are feature objects in existance that were obtained or created with the previous layer definition.

Not all drivers support this method. You can query a layer to check if it supports it with the OLCCreateField capability. Some drivers may only support this method while there are still no features in the layer. When it is supported, the existings features of the backing file/database should be updated accordingly.

Parameters:
field_def - field definition to write to disk.
approx_ok - If 1, the field may be created in a slightly different form depending on the limitations of the format driver.
Returns:
0 on success. Otherwise throws a RuntimeException (or an error code if DontUseExceptions() has been called).

CreateField

public int CreateField(FieldDefn field_def)
Create a new field on a layer. Same as below with approx_ok == 0.

See Also:
CreateField(FieldDefn field_def, int approx_ok)

DeleteField

public int DeleteField(int iField)
Delete an existing field on a layer.

You must use this to delete existing fields on a real layer. Internally the FeatureDefn for the layer will be updated to reflect the deleted field. Applications should never modify the FeatureDefn used by a layer directly.

This method should not be called while there are feature objects in existance that were obtained or created with the previous layer definition.

Not all drivers support this method. You can query a layer to check if it supports it with the OLCDeleteField capability. Some drivers may only support this method while there are still no features in the layer. When it is supported, the existings features of the backing file/database should be updated accordingly.

Parameters:
iField - index of the field to delete.
Returns:
0 on success. Otherwise throws a RuntimeException (or an error code if DontUseExceptions() has been called).
Since:
OGR 1.9.0

ReorderField

public int ReorderField(int iOldFieldPos,
                        int iNewFieldPos)
Reorder an existing field on a layer.

This method is a conveniency wrapper of ReorderFields() dedicated to move a single field. It is a non-virtual method, so drivers should implement ReorderFields() instead.

You must use this to reorder existing fields on a real layer. Internally the FeatureDefn for the layer will be updated to reflect the reordering of the fields. Applications should never modify the FeatureDefn used by a layer directly.

This method should not be called while there are feature objects in existance that were obtained or created with the previous layer definition.

The field definition that was at initial position iOldFieldPos will be moved at position iNewFieldPos, and elements between will be shuffled accordingly.

For example, let suppose the fields were "0","1","2","3","4" initially. ReorderField(1, 3) will reorder them as "0","2","3","1","4".

Not all drivers support this method. You can query a layer to check if it supports it with the OLCReorderFields capability. Some drivers may only support this method while there are still no features in the layer. When it is supported, the existings features of the backing file/database should be updated accordingly.

Parameters:
iOldFieldPos - previous position of the field to move. Must be in the range [0,GetFieldCount()-1].
iNewFieldPos - new position of the field to move. Must be in the range [0,GetFieldCount()-1].
Returns:
0 on success. Otherwise throws a RuntimeException (or an error code if DontUseExceptions() has been called).
Since:
OGR 1.9.0

ReorderFields

public int ReorderFields(int[] panMap)
Reorder all the fields of a layer.

You must use this to reorder existing fields on a real layer. Internally the FeatureDefn for the layer will be updated to reflect the reordering of the fields. Applications should never modify the FeatureDefn used by a layer directly.

This method should not be called while there are feature objects in existance that were obtained or created with the previous layer definition.

panMap is such that,for each field definition at position i after reordering, its position before reordering was panMap[i].

For example, let suppose the fields were "0","1","2","3","4" initially. ReorderFields(new Integer[]{0,2,3,1,4}) will reorder them as "0","2","3","1","4".

Not all drivers support this method. You can query a layer to check if it supports it with the OLCReorderFields capability. Some drivers may only support this method while there are still no features in the layer. When it is supported, the existings features of the backing file/database should be updated accordingly.

Parameters:
panMap - an array of GetLayerDefn().GetFieldCount() elements which is a permutation of [0, GetLayerDefn().GetFieldCount()-1].
Returns:
0 on success. Otherwise throws a RuntimeException (or an error code if DontUseExceptions() has been called).
Since:
OGR 1.9.0

AlterFieldDefn

public int AlterFieldDefn(int iField,
                          FieldDefn newFieldDefn,
                          int nFlags)
Alter the definition of an existing field on a layer.

You must use this to alter the definition of an existing field of a real layer. Internally the FeatureDefn for the layer will be updated to reflect the altered field. Applications should never modify the FeatureDefn used by a layer directly.

This method should not be called while there are feature objects in existance that were obtained or created with the previous layer definition.

Not all drivers support this method. You can query a layer to check if it supports it with the OLCAlterFieldDefn capability. Some drivers may only support this method while there are still no features in the layer. When it is supported, the existings features of the backing file/database should be updated accordingly. Some drivers might also not support all update flags.

Parameters:
iField - index of the field whose definition must be altered.
newFieldDefn - new field definition
nFlags - combination of ALTER_NAME_FLAG, ALTER_TYPE_FLAG and ALTER_WIDTH_PRECISION_FLAG to indicate which of the name and/or type and/or width and precision fields from the new field definition must be taken into account.
Returns:
0 on success. Otherwise throws a RuntimeException (or an error code if DontUseExceptions() has been called).
Since:
OGR 1.9.0

StartTransaction

public int StartTransaction()
For datasources which support transactions, StartTransaction creates a transaction.

If starting the transaction fails, will throw a RuntimeException (or an error code if DontUseExceptions() has been called). Datasources which do not support transactions will always return 0.

Returns:
0 on success. Otherwise throws a RuntimeException (or an error code if DontUseExceptions() has been called).

CommitTransaction

public int CommitTransaction()
For datasources which support transactions, CommitTransaction commits a transaction.

If no transaction is active, or the commit fails, will throw a RuntimeException (or an error code if DontUseExceptions() has been called). Datasources which do not support transactions will always return 0.

Returns:
0 on success. Otherwise throws a RuntimeException (or an error code if DontUseExceptions() has been called).

RollbackTransaction

public int RollbackTransaction()
For datasources which support transactions, RollbackTransaction will roll back a datasource to its state before the start of the current transaction.

If no transaction is active, or the rollback fails, will throw a RuntimeException (or an error code if DontUseExceptions() has been called). Datasources which do not support transactions will always return 0.

Returns:
0 on success. Otherwise throws a RuntimeException (or an error code if DontUseExceptions() has been called).

GetSpatialRef

public SpatialReference GetSpatialRef()
Fetch the spatial reference system for this layer.

Returns:
spatial reference, or null if there isn't one.

GetFeaturesRead

public long GetFeaturesRead()
Return the total number of features read.

Note: not all drivers seem to update properly this count.

Returns:
total number of features read.
Since:
Java bindings 1.7.0

SetIgnoredFields

public int SetIgnoredFields(Vector fieldNames)
Set which fields can be omitted when retrieving features from the layer.

If the driver supports this functionality (testable using OLCIgnoreFields capability), it will not fetch the specified fields in subsequent calls to GetFeature() / GetNextFeature() and thus save some processing time and/or bandwidth.

Besides field names of the layers, the following special fields can be passed: "OGR_GEOMETRY" to ignore geometry and "OGR_STYLE" to ignore layer style.

By default, no fields are ignored.

Parameters:
fieldNames - a vector of field names. If null is passed, the ignored list is cleared.
Returns:
ogr.OGRERR_NONE if all field names have been resolved (even if the driver does not support this method)
Since:
OGR 1.8.0