Package org.geotools.api.feature

Representation a features on a map. A {{Feature}} may represent a single item or a {{FeatureCollection}} of many things. Features with common properties may be categorised into a {{FeatureType}}, forming a dynamic type system similar to those introduced into other aspects of computer science.

The contents of this package form a feature model in accordance with the ideas expressed in the ISO 19107, as captured in the OGC Reference Model, GML3 and related specifications.

Type Model

As mentioned above Features can make use of a FeatureType in order to describe the set of attributes, associations and operations they are expected to have.

A FeatureType represents this information in PropertyDescriptors as follows:

  • AttributeDescriptor - defines the name of the attribute and its AttributeType
  • AssociationDescriptor - defines the name of the association and its AssociationType
  • OperationDescriptor - defines the name of the operation and its OperationType
This information is often considered "metadata" in the same manner as a Class is the metadata describing a Java Object.

Naming

One of the subjects that comes up when talking about metadata is "what the names mean", the names recorded by the PropertyDescriptors may be of some significance to the problem or domain being represented.

You can represent this significance by making a "dictionary" of your names, in rare cases you can find a formal dictionary defined by an organisation. The idea of group names into a dictionary is represented by the concept of a "Namespace".

A "Namespace" used to organise the names of your FeatureTypes is called a "Schema".

Please note that "Schema" and "Namespace" above are strictly referring to spatial data. This gets especially confusing when working with spatial data in a web application - since the w3c XML technologies use similar language to describe their ideas.

Data Model

The data model is the subject of this package, and centred around the idea of a Feature, it forms a part of a larger picture and constructs defined here will be referenced from several other packages.

Feature

A Feature represents something that can be drawn onto a map. A feature acts as a model of a real world entity. As such it has many similarities to object oriented programming ideas of Class, Object, Field and Method.
  • Feature - runtime data structure (similar in use to Object)
  • Attributes - feature property that holds information about a Feature (similar to a Field)
  • Associations - feature property defining a relationships a Feature is involved in (similar to a reference or collection)
  • Operations - feature property describing functionality a feature is able to perform (similar to a Method)
The most useful aspect of a Feature is the fact that it is a dynamic data construct defined at runtime.

Traditionally the Java programming language represents dynamic data structures using java.util.Map, you could think of a Feature as a java.util.Map in which the keys (ie attribute descriptors) are well defined.

If two Features have the same set of keys they are considered to be of the same FeatureType. A FeatureType is simply a list of valid attribute descriptors. You have the same kind of ability to represent your model with FeatureType as your do with Java class, inheritance is supported (ie superType) as is aggregation (your attributes can be Features).

Record

A Record is a simple data structure (it really is exactly the same as a Map with well known keys). Once again two Records with the same set of keys are considered to belong to the same RecordType.

Records are most often used as the result of an Operation. For the a Coverage (which is a kind of Feature) a operation is defined to "sample" a specific location, the information returned as part of this sample is a Record.

SimpleFeature

The idea of a simple feature is a concept introduced within the context of the GeoAPI project, many of the Java projects we work with are interested in a more approachable model similar in spirit to an array of ordered values, or at most a java.util.Map of named values.

A Simple feature is a Feature with the following additional requirements:

  • Attributes always must occur in the same order defined in their FeatureType
  • Ideas such as inheritance and aggregation are left out of it
  • Duplicate values are not allowed
These restrictions enable us to produce an API that is far easier to work with, values can be accessed by name, or by order and so on.

There is evidence that this need is present in other contexts, GML 3 has been simplified to a "Simple Feature" profile operating with similar restrictions to the ones indicated above.

Query Model

Filter

Our {filter} constructs are used to partition values into sets. We have deliberately defined Filter to work on more than just Feature instances, allowing us to use these ideas to capture restrictions on individual attribute values.

Filter should be viewed as our query or constraint system.

Identity

Closely related to the concept of constraints is one of identity, it is difficult to think of identification as a topic apart from the definition of a feature as a representation of a real world entity. In actual fact identity is related to the the definition of a Filter, a name is just another way of separating out a partition of values, the set in this case happens to be a set of one.

The concept of Identity is a troublesome one, our model supports the concept of "feature id". In the General OGC reference model the identification of a feature is intended to be unqiue and specific to the real world entity being modeled (regardless of the particular set of attribute you are using to describe in the current context).

As an example you may wish to model a roadway with pavement type and history of repair when looking at a budget for the coming year, the same road may be modelled in the future with a collection of possible routes when planning for over a ten year period. The "road" should be the same in both situations, and have the same id.

It is very difficult to be diligent with the concept of ID, GML3 for example only restricts an ID to be unique within the scope of a single document. I would suggestion you chose a stable source of identification, in the example above it would facilitate "joining" both datasets to predict repair costs for each of the proposed routes.