Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.gdal.ogr
Class Layer

    java.lang.Object
      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` | `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.
`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.
`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()`
`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` | `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 actually an alias for GetLayerDefn().GetName().

  Returns:
    the layer name

### 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.

  - OLCRandomRead / "RandomRead": true if the GetFeature() method is implemented in an optimized way for this layer, as opposed to the default implementation using ResetReading() and GetNextFeature() to find the requested feature id.

  - OLCSequentialWrite / "SequentialWrite": true if the CreateFeature() method works for this layer. Note this means that this particular layer is writable. The same Layer class may returned false for other layer instances that are effectively read-only.

  - OLCRandomWrite / "RandomWrite": true if the SetFeature() method is operational on this layer. Note this means that this particular layer is writable. The same Layer class may returned false for other layer instances that are effectively read-only.

  - OLCFastSpatialFilter / "FastSpatialFilter": true if this layer implements spatial filtering efficiently. Layers that effectively read all features, and test them with the Feature intersection methods should return false. This can be used as a clue by the application whether it should build and maintain it's own spatial index for features in this layer.

  - OLCFastFeatureCount / "FastFeatureCount": true if this layer can return a feature count (via GetFeatureCount()) efficiently ... ie. without counting the features. In some cases this will return true until a spatial filter is installed after which it will return false.

  - OLCFastGetExtent / "FastGetExtent": true if this layer can return its data extent (via GetExtent()) efficiently ... ie. without scanning all the features. In some cases this will return true until a spatial filter is installed after which it will return false.

  - OLCFastSetNextByIndex / "FastSetNextByIndex": true if this layer can perform the SetNextByIndex() call efficiently, otherwise false.

  - OLCCreateField / "CreateField": true if this layer can create new fields on the current layer using CreateField(), otherwise false.

  - OLCDeleteFeature / "DeleteFeature": true if the DeleteFeature() method is supported on this layer, otherwise false.

  - OLCStringsAsUTF8 / "StringsAsUTF8": true if values of OFTString fields are assured to be in UTF-8 format. If false the encoding of fields is uncertain, though it might still be UTF-8.

  - OLCStringsAsUTF8 / "StringsAsUTF8": true if values of OFTString fields are assured to be in UTF-8 format. If false the encoding of fields is uncertain, though it might still be UTF-8.

  - OLCTransactions / "Transactions": true if the StartTransaction(), CommitTransaction() and RollbackTransaction() methods work in a meaningful way, otherwise false.

  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.

  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)`

### 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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD