OpenLR™ - Encoder package
The encoder package holds the reference implementation for the OpenLR™ encoder according to the OpenLR™ whitepaper. This encoder takes a location in a map and generates an OpenLR™ location reference for this specific location. The location reference is map independent and the OpenLR™ decoder uses this location reference for finding back the location in the decoder map. Encoder and decoder map might differ in version and might also rely on different map vendors.
The encoder package requires the OpenLR™ data and map package. The interfaces in the map package must also be implemented in order to access the application map database. The data package provides a PhysicalEncoder interface so that different physical formats can be used. The implementation of this interface needs to be registered as a service and the encoder will find all physical encoders automatically during runtime. The encoder is capable to encode a single location as well as a set of locations in a row (see code example and pom.mxl below). The encoding process is configurable using encoder properties (see configuration of the encoding process below). The implementation also offers logging functionality (log4j) which can be configured using the logging.properties file provided in the package or you need to put a file name log4j.properties in your classpath.
Details oo the encoding steps can be found in the OpenLR™ whitepaper and also in the code documentation.The following table summarizes the encoder package related links on this website.
| Links | |
|---|---|
| The encoder software package can be downloaded in the software section. | Download |
| Accessing the encoder package with Maven | Maven access |
| Encoder package reports generated by Maven | Reports |
| Encoder package API documentation | API |
Code example
The following code example shows how the OpenLR™ encoder can be used. The code uses the "TomTom OpenLR Access Layer for SQLite".
import java.io.InputStream;
import java.util.ArrayList;
import java.util.List;
import openlr.LocationReference;
import openlr.OpenLRRuntimeException;
import openlr.binary.ByteArray;
import openlr.encoder.LocationReferenceHolder;
import openlr.encoder.OpenLREncoder;
import openlr.encoder.OpenLREncoderParameter;
import openlr.location.Location;
import openlr.location.LocationFactory;
import openlr.map.Line;
import openlr.map.MapDatabase;
import openlr.map.loader.MapLoadParameter;
import openlr.map.sqlite.loader.DBFileNameParameter;
import openlr.map.sqlite.loader.SQLiteMapLoader;
import openlr.properties.OpenLRPropertiesReader;
import openlr.properties.OpenLRPropertyException;
import org.apache.commons.configuration.Configuration;
import org.apache.log4j.PropertyConfigurator;
public class EncoderExample {
/* needs to be adjusted */
private static final String PATH_TO_DB = ".../tt_utrecht_2008_04.db3";
/* needs to be adjusted */
private static final String PATH_TO_LOG_PROPERTIES = "...";
private static final InputStream ENCODER_PROPERTIES = EncoderExample.class
.getClassLoader().getResourceAsStream(
"OpenLR-Encoder-Properties.xml");
public static void main(String[] args) {
// setup logging
PropertyConfigurator.configure(PATH_TO_LOG_PROPERTIES);
// instantiate map database
MapDatabase mdb = null;
SQLiteMapLoader mapLoader = new SQLiteMapLoader();
List<MapLoadParameter> params = new ArrayList<MapLoadParameter>();
DBFileNameParameter dbFile = new DBFileNameParameter();
dbFile.setValue(PATH_TO_DB);
params.add(dbFile);
try {
mdb = mapLoader.load(params);
} catch (Exception e) {
e.printStackTrace();
System.exit(1);
}
// load location path with n lines
List<Line> path = new ArrayList<Line>();
path.add(mdb.getLine(15280002805007L));
path.add(mdb.getLine(15280002805010L));
path.add(mdb.getLine(15280002805011L));
path.add(mdb.getLine(15280002805003L));
// instantiate Location object without offsets
Location location = LocationFactory.createLineLocation("Location-1",
path);
// prepare encoding result object
LocationReferenceHolder locRef = null;
// prepare encoder parameter with map database and properties
Configuration conf = null;
try {
conf = OpenLRPropertiesReader.loadPropertiesFromStream(
ENCODER_PROPERTIES, true);
} catch (OpenLRPropertyException e1) {
e1.printStackTrace();
System.exit(2);
}
OpenLREncoderParameter encParams = new OpenLREncoderParameter.Builder()
.with(mdb).with(conf).buildParameter();
try {
// encode the location
OpenLREncoder encoder = new OpenLREncoder();
locRef = encoder.encodeLocation(encParams, location);
} catch (OpenLRRuntimeException e) {
// encoding runtime exception
e.printStackTrace();
System.exit(3);
}
// check validity of the location reference
if (!locRef.isValid()) {
// location reference is not valid, print out error code
System.out
.println("Location reference is NOT valid -- error code: "
+ locRef.getReturnCode());
} else {
// location reference is valid
// e.g. get binary format
LocationReference lr = locRef.getLocationReference("binary");
ByteArray ba = (ByteArray) lr.getLocationReferenceData();
System.out.println("Location reference is valid -- size [bytes]: "
+ ba.size());
}
}
}
Maven pom.xml for the code example
The following pom.xml can be used for the code example.
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>openlr.examples</groupId>
<artifactId>encoderExample</artifactId>
<packaging>jar</packaging>
<version>0.0.1-SNAPSHOT</version>
<name>encoderExample</name>
<build>
<plugins>
<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<source>1.6</source>
<target>1.6</target>
</configuration>
</plugin>
</plugins>
</build>
<dependencies>
<dependency>
<groupId>openlr</groupId>
<artifactId>encoder</artifactId>
<version>1.3.0</version>
</dependency>
<dependency>
<groupId>openlr</groupId>
<artifactId>binary</artifactId>
<version>1.3.0</version>
</dependency>
<dependency>
<groupId>openlr-mapLoader</groupId>
<artifactId>tt-sqlite</artifactId>
<version>1.3.0</version>
</dependency>
<dependency>
<groupId>log4j</groupId>
<artifactId>log4j</artifactId>
<version>1.2.14</version>
</dependency>
</dependencies>
<repositories>
<repository>
<id>openlr</id>
<url>http://www.openlr.org/nexus/content/repositories/releases</url>
</repository>
</repositories>
</project>
Configuring the encoding process
The OpenLR™ encoder can be configured using encoder properties in a xml-file. The following example shows the standard configuration of the encoding process.
<?xml version="1.0" encoding="UTF-8"?>
<!-- The encoder type encloses all configuration parameters for the OpenLR
encoder. -->
<p:OpenLREncoderProperties
xmlns:p="http://www.example.org/OpenLREncoderProperties/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.example.org/OpenLREncoderProperties/
properties/OpenLREncoderProperties.xsd ">
<!-- Defines the distance between the first and second point being used for
bearing calculation. The value is measured in meters and determined along
the line geometry. -->
<BearingDistance>20</BearingDistance>
<!-- Defines the maximum distance between two subsequent location reference
points. -->
<MaximumDistanceLRP>15000</MaximumDistanceLRP>
<!-- Enables/Disables the check for turn restrictions along the location
path. -->
<CheckTurnRestrictions>false</CheckTurnRestrictions>
<!-- The location reference cache can be used to store only location references where
the computation time exceeds the defined value. The time is defined in ms. This shall
help to store only complex location references and therefore to reduce the total cache size -->
<CompTime4Cache>2500</CompTime4Cache>
<!-- OPTIONAL -->
<!-- Choosing a special version for a physical format. If no choices are made then
the latest version will be used. -->
<PhysicalFormatVersions>
<PhysicalFormatVersion>
<FormatIdentifier>binary</FormatIdentifier>
<Version>3</Version>
</PhysicalFormatVersion>
</PhysicalFormatVersions>
</p:OpenLREncoderProperties>