The OpenLR data package comprises interfaces and classes for OpenLR location references and also interfaces for encoding and decoding the internal data into a defined physical format and the other way round.
The interface LocationReference defines an OpenLR location reference. A location reference describes in a map-agnostic way a location in a digital map. The reference can be used to exchange the information about a location between several maps. These maps might differ to some extent.
This interface holds an identification of the location/location reference, the reference itself as an abstract field and if no location reference could be generated the object holds the exception. As there might be several formats for location references this object identifies itself with a data identifier and data class information.
The interface LocationReferencePoint defines the access to a location reference point (LRP). Such a LRP is a basic structure for an OpenLR location reference. It represents a line in the network and two successive LRPs represent a shortest- path being part of the location.
The location reference point consists of coordinates and attributes like form of way, functional road class and a bearing. It also holds information on the path to the next LRP like the lowest functional road class on that path and the distance of the next LRP.
The interface Offsets defines the basic structure to deal with offsets. The OpenLR method defines two offsets: positive offset and negative offset. The positive offset indicates the distance between start point of the first line and the real start point of the location. The negative offset indicates the distance between end point of the last line and the real end point of the location. Offsets are not mandatory in OpenLR and using no offsets means that the location starts at the start node of the first line and ending at the end node of the last line of the location. It is also possible to use only one offset value.
The class OpenLRProcessingException defines an exception where the total process of encoding or decoding failed due to an error. If this exception is thrown the whole process shall terminate.
The interface PhysicalEncoder needs to be implemented by all OpenLR physical format encoder. These encoder translate the internal data structure of a location reference into a defined physical format. Each encoder is identified by a data identifier string. Examples for different physical formats might be "xml" or "binary".
Encoder packages implementing this interface also need to register the implementation as a service. The service loader mechanism from Java is used by the OpenLR encoder to collect all implementation of this PhysicalEncoder interface. All implementations will be called during the encoding process.
In order to register a service one need to add a file "openlr.PhysicalEncoder" to the "META-INF/services" directory of the java package. This file must contain the fully qualified path to the implementation class, e.g. "openlr.xml.OpenLRXMLEncoder".
The interface PhysicalDecoder needs to be implemented by all OpenLR physical format decoder. These decoder translate a defined physical format for OpenLR location references into an internal representation. Each decoder is identified by a data identifier string. Examples for different physical formats might be "xml" or "binary".
Decoder packages implementing this interface also need to register the implementation as a service. The service loader mechanism from Java is used by the OpenLR decoder to collect all implementation of this PhysicalDecoder interface. The decoder will select the required physical decoder to read the physical data.
In order to register a service one need to add a file "openlr.PhysicalDecoder" to the "META-INF/services" directory of the java package. This file must contain the fully qualified path to the implementation class, e.g. "openlr.xml.OpenLRXMLDecoder".
The interface Location defines a location (in a map) which can be encoded using the OpenLR encoder and is also the result of the OpenLR decoding process.
The enumeration LocationType specifies the different types of location supported by the OpenLR method. Currently supported types are: GeoCoordinate, PointAlongLine, PoiWithAccessPoint, and LineLocation.
The enumeration Orientation defines how a point location is oriented with respect to the direction of the line from first LRP to second LRP.
A raw location reference represents an intermediate format of a location reference used by the encoder and decoder. This format is the exchange format between a specific physical format (e.g. binary) and the data format used for encoding and decoding.