Package org.gdal.ogr

Class DataSource

java.lang.Object

org.gdal.gdal.MajorObject

org.gdal.ogr.DataSource

public class DataSource
extends MajorObject

This class represents a data source.

The DataSource class is a binding for the C++ OGRDataSource class.

A data source potentially consists of many layers (Layer). A data source normally consists of one, or a related set of files, though the name doesn't have to be a real item in the file system. When an DataSource is destroyed, all it's associated Layer objects are also destroyed.

Method Summary

Modifier and Type	Method	Description
int	AbortSQL()
SWIGTYPE_p_CPLErr	Close()
int	CommitTransaction()
Layer	CopyLayer(Layer src_layer, String new_name)	Duplicate an existing layer.
Layer	CopyLayer(Layer src_layer, String new_name, Vector options)	Duplicate an existing layer.
Layer	CreateLayer(String name)	Create a new layer on the data source with the indicated name.
Layer	CreateLayer(String name, SpatialReference srs)	Create a new layer on the data source with the indicated name, coordinate system.
Layer	CreateLayer(String name, SpatialReference srs, int geom_type)	Create a new layer on the data source with the indicated name, coordinate system, geometry type.
Layer	CreateLayer(String name, SpatialReference srs, int geom_type, Vector options)	Create a new layer on the data source with the indicated name, coordinate system, geometry type.
void	delete()	Frees the native resource associated to a DataSource object and close the file.
int	DeleteLayer(int index)	Delete the indicated layer from the datasource.
boolean	equals(Object obj)
Layer	ExecuteSQL(String statement)	Execute an SQL statement against the data store.
Layer	ExecuteSQL(String statement, Geometry spatialFilter)	Execute an SQL statement against the data store.
Layer	ExecuteSQL(String statement, Geometry spatialFilter, String dialect)	Execute an SQL statement against the data store.
void	FlushCache()
Driver	GetDriver()	Returns the driver that the dataset was opened with.
Layer	GetLayer(int index)	Fetch a layer by index.
Layer	GetLayer(String layer_name)	Fetch a layer by name.
Layer	GetLayerByIndex(int index)	Fetch a layer by index.
Layer	GetLayerByName(String layer_name)	Fetch a layer by name.
int	GetLayerCount()	Get the number of layers in this data source.
String	getName()	Returns the name of the data source.
String	GetName()	Returns the name of the data source.
int	GetRefCount()	Fetch reference count.
StyleTable	GetStyleTable()
int	GetSummaryRefCount()	Fetch reference count of datasource and all owned layers.
int	hashCode()
void	ReleaseResultSet(Layer layer)	Release results of ExecuteSQL().
int	RollbackTransaction()
void	SetStyleTable(StyleTable table)
int	StartTransaction()
int	StartTransaction(int force)
int	SyncToDisk()	Flush pending changes to disk.
boolean	TestCapability(String cap)	Test if capability is available.

Methods inherited from class org.gdal.gdal.MajorObject

GetDescription, GetMetadata_Dict, GetMetadata_Dict, GetMetadata_List, GetMetadata_List, GetMetadataDomainList, GetMetadataItem, GetMetadataItem, SetDescription, SetMetadata, SetMetadata, SetMetadata, SetMetadata, SetMetadata, SetMetadata, SetMetadataItem, SetMetadataItem

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, toString, wait, wait, wait

Method Details

delete

public void delete()

Frees the native resource associated to a DataSource object and close the file.

This method will delete the underlying C++ object. After it has been called, all native resources will have been destroyed, so it will be illegal (and likely to cause JVM crashes) to use any method on this object or any derived objects, such as Layer objects of this Dataset.

The delete() method must be called when a datasource has been opened in update or creation mode, otherwise data might not be properly flushed to the disk. You cannot rely on the finalization to call delete().

Overrides:

delete in class MajorObject

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

GetLayer

public Layer GetLayer(int index)

Fetch a layer by index.

The returned layer remains owned by the DataSource and should not be deleted by the application.

Parameters:

index - a layer number between 0 and GetLayerCount()-1.

Returns:

the layer, or null if index is out of range or an error occurs.

Since:

Java bindings 1.7.0

GetLayer

public Layer GetLayer(String layer_name)

Fetch a layer by name. The returned layer remains owned by the DataSource and should not be deleted by the application.

Parameters:

layer_name - the layer name of the layer to fetch.

Returns:

the layer, or null if index is out of range or an error occurs.

Since:

Java bindings 1.7.0

getName

public String getName()

Returns the name of the data source.

This string should be sufficient to open the data source if passed to the same Driver that this data source was opened with, but it need not be exactly the same string that was used to open the data source. Normally this is a filename.

Returns:

name of the data source

Close

public SWIGTYPE_p_CPLErr Close()

GetRefCount

public int GetRefCount()

Fetch reference count.

Returns:

the current reference count for the datasource object itself.

GetSummaryRefCount

public int GetSummaryRefCount()

Fetch reference count of datasource and all owned layers.

Returns:

the current summary reference count for the datasource and its layers.

GetLayerCount

public int GetLayerCount()

Get the number of layers in this data source.

Returns:

layer count.

GetDriver

public Driver GetDriver()

Returns the driver that the dataset was opened with.

Returns:

null if driver info is not available, or the driver

GetName

public String GetName()

Returns the name of the data source.

This string should be sufficient to open the data source if passed to the same Driver that this data source was opened with, but it need not be exactly the same string that was used to open the data source. Normally this is a filename.

Returns:

name of the data source

DeleteLayer

public int DeleteLayer(int index)

Delete the indicated layer from the datasource.

If this method is supported the ODsCDeleteLayer capability will test true on the DataSource.

Parameters:

index - the index of the layer to delete.

Returns:

0 on success. Otherwise throws a RuntimeException if deleting layers is not supported for this datasource (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 datasource 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 data sources do not implement this method, and will still return ogr.OGRERR_NONE. An error is only returned if an error occurs while attempting to flush to disk.

The default implementation of this method just calls the SyncToDisk() method on each of the layers. Conceptionally, calling SyncToDisk() on a datasource should include any work that might be accomplished by calling SyncToDisk() on layers in that data source.

In any event, you should always close any opened datasource with delete() that will ensure all data is correctly flushed.

Returns:

ogr.OGRERR_NONE if no error occurs (even if nothing is done) or an error code.

FlushCache

public void FlushCache()

CreateLayer

public Layer CreateLayer(String name,
 SpatialReference srs,
 int geom_type,
 Vector options)

Create a new layer on the data source with the indicated name, coordinate system, geometry type.

The options argument can be used to control driver specific creation options. These options are normally documented in the format specific documentation.

Example:

        Layer layer;
        Vector options = new Vector();

        if( !ds.TestCapability( ogr.ODsCCreateLayer ) )
        {
            ...
        }

        options.add("DIM=2");
        layer = ds.CreateLayer( "NewLayer", null, ogr.wkbUnknown,
                                options );

        if( layer == null )
        {
            ...
        }

Parameters:

name - the name for the new layer. This should ideally not match any existing layer on the datasource.

srs - the coordinate system to use for the new layer, or null if no coordinate system is available.

geom_type - the geometry type for the layer. Use ogr.wkbUnknown if there are no constraints on the types geometry to be written.

options - a vector of strings of the format name=value. Options are driver specific, and driver information can be found at the following url: OGR Formats

Returns:

null is returned on failure, or a new Layer on success.

CreateLayer

public Layer CreateLayer(String name,
 SpatialReference srs,
 int geom_type)

Create a new layer on the data source with the indicated name, coordinate system, geometry type.

Same as below with options == null.

Since:

Java bindings 1.7.0

See Also:

• CreateLayer(String name, SpatialReference srs, int geom_type, java.util.Vector options)

CreateLayer

public Layer CreateLayer(String name,
 SpatialReference srs)

Create a new layer on the data source with the indicated name, coordinate system.

Same as below with geom_type == ogr.wkbUnknown and options == null.

Since:

Java bindings 1.7.0

See Also:

• CreateLayer(String name, SpatialReference srs, int geom_type, java.util.Vector options)

CreateLayer

public Layer CreateLayer(String name)

Create a new layer on the data source with the indicated name.

Same as below with srs == null, geom_type == ogr.wkbUnknown and options == null.

Since:

Java bindings 1.7.0

See Also:

• CreateLayer(String name, SpatialReference srs, int geom_type, java.util.Vector options)

CopyLayer

public Layer CopyLayer(Layer src_layer,
 String new_name,
 Vector options)

Duplicate an existing layer.

This function creates a new layer, duplicate the field definitions of the source layer and then duplicate each features of the source layer. The papszOptions argument can be used to control driver specific creation options. These options are normally documented in the format specific documentation. The source layer may come from another dataset.

Parameters:

src_layer - source layer.

new_name - the name of the layer to create.

options - a StringList of name=value options. Options are driver specific, and driver information can be found at the following url: OGR Formats

Returns:

a new layer, or null if an error occurs.

CopyLayer

public Layer CopyLayer(Layer src_layer,
 String new_name)

Duplicate an existing layer.

Same as below with options == null.

Since:

Java bindings 1.7.0

See Also:

• CopyLayer(Layer src_layer, String new_name, java.util.Vector options)

GetLayerByIndex

public Layer GetLayerByIndex(int index)

Fetch a layer by index.

The returned layer remains owned by the DataSource and should not be deleted by the application.

Parameters:

index - a layer number between 0 and GetLayerCount()-1.

Returns:

the layer, or null if index is out of range or an error occurs.

GetLayerByName

public Layer GetLayerByName(String layer_name)

Fetch a layer by name.

The returned layer remains owned by the DataSource and should not be deleted by the application.

Parameters:

layer_name - the layer name of the layer to fetch.

Returns:

the layer, or null if index is out of range or an error occurs.

TestCapability

public boolean TestCapability(String cap)

Test if capability is available.

One of the following data source capability names can be passed into this method, and a true or false value will be returned indicating whether or not the capability is available for this object.

• ODsCCreateLayer: True if this datasource can create new layers.

• ODsCDeleteLayer: True if this datasource can delete existing layers.

The constant forms of the capability names should be used in preference to the strings themselves to avoid misspelling.

Parameters:

cap - the capability to test.

Returns:

true if capability available otherwise false.

ExecuteSQL

public Layer ExecuteSQL(String statement,
 Geometry spatialFilter,
 String dialect)

Execute an SQL statement against the data store.

The result of an SQL query is either null for statements that are in error, or that have no results set, or a Layer representing a results set from the query. Note that this Layer is in addition to the layers in the data store and must be destroyed with ReleaseResultsSet() before the data source is closed (destroyed).

For more information on the SQL dialect supported internally by OGR review the OGR SQL document. Some drivers (i.e. Oracle and PostGIS) pass the SQL directly through to the underlying RDBMS.

Parameters:

statement - the SQL statement to execute.

spatialFilter - geometry which represents a spatial filter.

dialect - allows control of the statement dialect. By default it is assumed to be "generic" SQL, whatever that is.

Returns:

a Layer containing the results of the query. Deallocate with ReleaseResultsSet().

ExecuteSQL

public Layer ExecuteSQL(String statement,
 Geometry spatialFilter)

Execute an SQL statement against the data store.

Same as below with dialect = ""

Since:

Java bindings 1.7.0

See Also:

• ExecuteSQL(String statement, Geometry spatialFilter, String dialect)

ExecuteSQL

public Layer ExecuteSQL(String statement)

Execute an SQL statement against the data store.

Same as below with spatialFilter == null and dialect = ""

Since:

Java bindings 1.7.0

See Also:

• ExecuteSQL(String statement, Geometry spatialFilter, String dialect)

AbortSQL

public int AbortSQL()

ReleaseResultSet

public void ReleaseResultSet(Layer layer)

Release results of ExecuteSQL().

This method should only be used to deallocate Layers resulting from an ExecuteSQL() call on the same DataSource. Failure to deallocate a results set before destroying the DataSource may cause errors.

Parameters:

layer - the result of a previous ExecuteSQL() call.

GetStyleTable

public StyleTable GetStyleTable()

SetStyleTable

public void SetStyleTable(StyleTable table)

StartTransaction

public int StartTransaction(int force)

StartTransaction

public int StartTransaction()

CommitTransaction

public int CommitTransaction()

RollbackTransaction

public int RollbackTransaction()