Package com.luciad.formats.geopackage

Class GeoPackageModelEncoder

java.lang.Object

com.luciad.formats.geopackage.GeoPackageModelEncoder

public final class GeoPackageModelEncoder
extends Object

The GeoPackageModelEncoder allows for exporting existing feature models as well as creating entirely new GeoPackage feature models.

Both can be done to an existing GeoPackage file and to a new file.

Since:

2024.0

Method Summary

Modifier and Type	Method	Description
static IFeatureModel	createEmptyGeoPackageDataSet(String path, GeoPackageFeatureModelCreateOptions options)	Creates a new empty table in the GeoPackage located at the specified path according to the data type specified in the options, and immediately decodes it as a feature model that can be edited.
static void	exportFeatureModel(String path, IFeatureModel model)	Exports the given IFeatureModel to the GeoPackage located at the specified path, using default options.
static void	exportFeatureModel(String path, IFeatureModel model, GeoPackageFeatureModelExportOptions options)	Exports the given IFeatureModel to the GeoPackage located at the specified path.
static String	getCompliantName(String name)	This function adds an underscore at the start if it starts with a digit, and converts all non alphanumeric characters to underscores.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

exportFeatureModel

public static void exportFeatureModel(@NotNull
 String path,
 @NotNull
 IFeatureModel model)
                               throws IOException

Exports the given IFeatureModel to the GeoPackage located at the specified path, using default options.

Parameters:

path - the path of the (new) GeoPackage file.

model - the IFeatureModel to export.

Throws:

IOException - when exporting fails.

exportFeatureModel

public static void exportFeatureModel(@NotNull
 String path,
 @NotNull
 IFeatureModel model,
 @NotNull
 GeoPackageFeatureModelExportOptions options)
                               throws IOException

Exports the given IFeatureModel to the GeoPackage located at the specified path.

File creation and overwriting data

If no file exists, it is created. If an error occurs during exporting, the file is deleted again.

If the file already exists, the new data is added to it. In the case of a name conflict (that is, there already exists a table with the same name as one of the data types, the existing data is only overwritten if the corresponding option is set to true. If overwriting is disabled (default) it results in an error instead and the export is aborted.

If overwriting is enabled, any deleted data isn't recovered in case of failure.

Data types with no features

Each data type with associated features gets exported; no empty feature tables are created when exporting (use createEmptyGeoPackageDataSet instead for that). Attempting to export an empty IFeatureModel, that is, one without any features, results in an error.

Multiple data types

When a single IFeatureModel contains multiple data types, a feature table is created for each. However, keep in mind that when decoding, only a single table is loaded per IFeatureModel.

Name conversions

The Data type and data property names must only consist of alphanumeric characters and underscores. Furthermore the first character must not be a digit.

If a name does not comply, it is automatically converted as described in GeoPackageModelEncoder#getCompliantName. This function can be used to do the same conversion as is done internally.

If converted names overlap this results in an error.

Coordinate reference

The coordinate reference is inferred from the features contained in the model. All features belonging to a certain data type must have the same reference, the export fails otherwise.

gpkg_geometry_columns settings

The GeoPackage feature tables are made with the least restrictive settings in the gpkg_geometry_columns table: A geometry_type_name of "GEOMETRY" and a z and m of 2 (optional).

Extensions

The rtree index and circularstring extensions are always enabled, these are official extensions that respectively improve performance and allow adding the CircularArcBy3Points geometry. The Luciad circle, ellipse and ellipticalarc extensions are only enabled if the corresponding option is set to true (which is the default).

With these extensions the geopackage accepts the following geometries:

• a Patch containing a CircleByCenterPoint
• a Patch containing a Ellipse
• an EllipticalArc

Parameters:

path - the path of the (new) GeoPackage file.

model - the IFeatureModel to export.

options - export options.

Throws:

IOException - when exporting fails.

createEmptyGeoPackageDataSet

@NotNull
public static IFeatureModel createEmptyGeoPackageDataSet(@NotNull
 String path,
 @NotNull
 GeoPackageFeatureModelCreateOptions options)
                                                  throws IOException

Creates a new empty table in the GeoPackage located at the specified path according to the data type specified in the options, and immediately decodes it as a feature model that can be edited.

File creation and overwriting data

If no file exists, it is created. If an error occurs during creation, the file is deleted again.

If the file already exists, a new table is added to it. In the case of a name conflict (that is, there already exists a table with the same name as the data type, the existing data is only overwritten if the corresponding option is set to true. If overwriting is disabled (default) it results in an error instead and the creation is aborted.

If overwriting is enabled, any deleted data isn't recovered in case of failure.

Invalid names

The Data type and data property names must only consist of alphanumeric characters and underscores. Furthermore the first character must not be a digit.

If a name does not comply with this, encoding fails.

gpkg_geometry_columns settings

The GeoPackage feature tables are made with the least restrictive settings in the gpkg_geometry_columns table: A geometry_type_name of "GEOMETRY" and a z and m of 2 (optional).

Extensions

The rtree index and circularstring extensions are always enabled, these are official extensions that respectively improve performance and allow adding the CircularArcBy3Points geometry. The Luciad circle, ellipse and ellipticalarc extensions are only enabled if the corresponding option is set to true (which is the default).

With these extensions the geopackage accepts the following geometries:

• a Patch containing a CircleByCenterPoint
• a Patch containing a Ellipse
• an EllipticalArc

Parameters:

path - the path of the (new) GeoPackage file.

options - create options.

Returns:

a decoded IFeatureModel of the new table.

Throws:

IOException - when creation fails.

getCompliantName

@NotNull
public static String getCompliantName(@NotNull
 String name)

This function adds an underscore at the start if it starts with a digit, and converts all non alphanumeric characters to underscores.

Sequences of underscores are reduced to a single underscore.

The names of data types and data properties that do not comply are changed automatically in the case of an export. This function can be used to reliably get the new names based on the old ones.

In the case of createEmptyGeoPackageDataSet, the presence of non-compliant names results in an error.

Parameters:

name - a name (of a data type or a data property).

Returns:

the name after encoding to the GeoPackage.