All data in OpenStreetMap is stored in three fundamental data types, also called elements: nodes, ways and relations. These data types are used to describe objects that exist in the world. The different elements differ in their capability to model real world objects. For example a node can be used to model the location of a restaurant while a way, as a sequence of coordinates, can represent the path of a street.
In addition to their geometric component, elements contain data that describes the meaning of their geometry. To this purpose, any element can have tags to model properties of the object it represents. Technically, a tag is just a pair of strings, a key and a value, that assigns a value to some property of an object.
Data objects share more common traits: every object has an id, a number that identifies it uniquely within the set of objects of the same basic data type. Also, every object has some associated metadata that describes information such as the time the object has been modified the last time and the username who modified the object.
osm4j provides abstract data types for the basic OpenStreetMap elements. The core interfaces are OsmNode, OsmWay and OsmRelation. All three extend the interface OsmEntity, which offers access to the common properties of the elementary data types:
getId()returns the unique identifier of an object.
getMetadata()retrieves the OsmMetadata, that is associated with an object.
getTag(int index)give access to the tags which are represented by the OsmTag interface.
An OsmNode has the methods
getLongitude() to retrieve the coordinates of the point it represents.
An OsmWay references a sequence of nodes. It provides access to them through methods
An OsmRelation references a sequence of other objects as members. It provides access to them through methods
getMember(int n). Every member is of type OsmRelationMember and encapsulates three properties of the referenced object: its identifier, its type (node, way or relation) and its role.
An OSM dataset is basically a long list of nodes, ways and relations that is encoded using one of the basic storage file formats. osm4j provides access to data encoded in the most important of these data formats by providing OsmReader and OsmIterator implementations for them.
All basic data formats have in common, that they store their data in a specific order:
Thus, when processing an OpenStreetMap dataset, you will encounter the contained data in exactly this order. Also, when writing a dataset to some output using an OsmOutputStream it is important to feed the elements to the stream in the correct order.
It is important to understand that ways and relations reference other objects using their ids. They do not contain the data of referenced objects themselves. Hence, to work with a way or relation it is usually necessary to resolve those references and find the actual objects they reference.
For example, a way is just a sequence of node ids. To interpret the geometry of the way, you have to assemble a sequence of coordinates from the references by finding the referenced nodes by their id.