io.jenetics.jpx

Class GPX

java.lang.Object

io.jenetics.jpx.GPX

All Implemented Interfaces:

Serializable

public final class GPX
extends Object
implements Serializable

GPX documents contain a metadata header, followed by way-points, routes, and tracks. You can add your own elements to the extensions section of the GPX document.

Examples

Creating a GPX object with one track-segment and 3 track-points

 final GPX gpx = GPX.builder()
     .addTrack(track -> track
         .addSegment(segment -> segment
             .addPoint(p -> p.lat(48.2081743).lon(16.3738189).ele(160))
             .addPoint(p -> p.lat(48.2081743).lon(16.3738189).ele(161))
             .addPoint(p -> p.lat(48.2081743).lon(16.3738189).ele(162))))
     .build();
 

Reading a GPX file

 final GPX gpx = GPX.read("track.xml");
 

Reading erroneous GPX files

 final boolean lenient = true;
 final GPX gpx = GPX.read("track.xml", lenient);
 

This allows to read otherwise invalid GPX files, like

 <?xml version="1.0" encoding="UTF-8"?>
 <gpx version="1.1" creator="GPSBabel - http://www.gpsbabel.org" xmlns="http://www.topografix.com/GPX/1/0">
     <metadata>
         <time>2015-11-13T15:22:42.140Z</time>
         <bounds minlat="-37050536.000000000" minlon="-0.000000000" maxlat="48.359161377" maxlon="16.448385239"/>
     </metadata>
     <trk>
         <name>track-1</name>
         <desc>Log every 3 sec, 0 m</desc>
         <trkseg>
             <trkpt></trkpt>
             <trkpt lat="48.199352264" lon="16.403341293">
                 <ele>4325376.000000</ele>
                 <time>2015-10-23T17:07:08Z</time>
                 <speed>2.650000</speed>
                 <name>TP000001</name>
             </trkpt>
             <trkpt lat="6.376383781" lon="-0.000000000">
                 <ele>147573952589676412928.000000</ele>
                 <time>1992-07-19T10:10:58Z</time>
                 <speed>464.010010</speed>
                 <name>TP000002</name>
             </trkpt>
             <trkpt lat="-37050536.000000000" lon="0.000475423">
                 <ele>0.000000</ele>
                 <time>2025-12-17T05:10:27Z</time>
                 <speed>56528.671875</speed>
                 <name>TP000003</name>
             </trkpt>
             <trkpt></trkpt>
         </trkseg>
     </trk>
 </gpx>
 

which is read as

 <?xml version="1.0" encoding="UTF-8"?>
 <gpx xmlns="http://www.topografix.com/GPX/1/1" version="1.1" creator="JPX" >
     <metadata>
         <time>2015-11-13T15:22:42.140Z</time>
     </metadata>
     <trk>
         <name>track-1</name>
         <desc>Log every 3 sec, 0 m</desc>
         <trkseg>
             <trkpt lat="48.199352264" lon="16.403341293">
                 <ele>4325376.000000</ele>
                 <time>2015-10-23T17:07:08Z</time>
                 <speed>2.650000</speed>
                 <name>TP000001</name>
             </trkpt>
             <trkpt lat="6.376383781" lon="-0.000000000">
                 <ele>147573952589676412928.000000</ele>
                 <time>1992-07-19T10:10:58Z</time>
                 <speed>464.010010</speed>
                 <name>TP000002</name>
             </trkpt>
         </trkseg>
     </trk>
 </gpx>
 

Since:

1.0

Version:

1.1

Author:

Franz Wilhelmstötter

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	GPX.Builder Builder class for creating immutable GPX objects.

Field Summary

Fields

Modifier and Type	Field and Description
static String	CREATOR The default creator string.
static String	VERSION The default version number: 1.1.

Method Summary

Modifier and Type	Method and Description
static GPX.Builder	builder() Create a new GPX builder.
static GPX.Builder	builder(String creator) Create a new GPX builder with the given GPX creator string.
static GPX.Builder	builder(String version, String creator) Create a new GPX builder with the given GPX version and creator string.
boolean	equals(Object obj)
String	getCreator() Return the name or URL of the software that created your GPX document.
Optional<Metadata>	getMetadata() Return the metadata of the GPX file.
List<Route>	getRoutes() Return an unmodifiable list of the GPX routes.
List<Track>	getTracks() Return an unmodifiable list of the GPX tracks.
String	getVersion() Return the version number of the GPX file.
List<WayPoint>	getWayPoints() Return an unmodifiable list of the GPX way-points.
int	hashCode()
static GPX	of(String creator, Metadata metadata, List<WayPoint> wayPoints, List<Route> routes, List<Track> tracks) Create a new GPX object with the given data.
static GPX	of(String version, String creator, Metadata metadata, List<WayPoint> wayPoints, List<Route> routes, List<Track> tracks) Create a new GPX object with the given data.
static GPX	read(InputStream input) Read an GPX object from the given input stream.
static GPX	read(InputStream input, boolean lenient) Read an GPX object from the given input stream.
static GPX	read(Path path) Read an GPX object from the given input stream.
static GPX	read(Path path, boolean lenient) Read an GPX object from the given input stream.
static GPX	read(String path) Read an GPX object from the given input stream.
static GPX	read(String path, boolean lenient) Read an GPX object from the given input stream.
Stream<Route>	routes() Return a stream of the GPX routes.
GPX.Builder	toBuilder() Convert the immutable GPX object into a mutable builder initialized with the current GPX values.
String	toString()
Stream<Track>	tracks() Return a stream of the GPX tracks.
Stream<WayPoint>	wayPoints() Return a stream with all WayPoints of this GPX object.
static void	write(GPX gpx, OutputStream output) Writes the given gpx object (in GPX XML format) to the given output stream.
static void	write(GPX gpx, OutputStream output, String indent) Writes the given gpx object (in GPX XML format) to the given output stream.
static void	write(GPX gpx, Path path) Writes the given gpx object (in GPX XML format) to the given output stream.
static void	write(GPX gpx, Path path, String indent) Writes the given gpx object (in GPX XML format) to the given output stream.
static void	write(GPX gpx, String path) Writes the given gpx object (in GPX XML format) to the given output stream.
static void	write(GPX gpx, String path, String indent) Writes the given gpx object (in GPX XML format) to the given output stream.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

VERSION

public static final String VERSION

The default version number: 1.1.

See Also:

Constant Field Values

CREATOR

public static final String CREATOR

The default creator string.

See Also:

Constant Field Values

Method Detail

getVersion

public String getVersion()

Return the version number of the GPX file.

Returns:

the version number of the GPX file

getCreator

public String getCreator()

Return the name or URL of the software that created your GPX document. This allows others to inform the creator of a GPX instance document that fails to validate.

Returns:

the name or URL of the software that created your GPX document

getMetadata

public Optional<Metadata> getMetadata()

Return the metadata of the GPX file.

Returns:

the metadata of the GPX file

getWayPoints

public List<WayPoint> getWayPoints()

Return an unmodifiable list of the GPX way-points.

Returns:

an unmodifiable list of the GPX way-points.

wayPoints

public Stream<WayPoint> wayPoints()

Return a stream with all WayPoints of this GPX object.

Returns:

a stream with all WayPoints of this GPX object

getRoutes

public List<Route> getRoutes()

Return an unmodifiable list of the GPX routes.

Returns:

an unmodifiable list of the GPX routes.

routes

public Stream<Route> routes()

Return a stream of the GPX routes.

Returns:

a stream of the GPX routes.

getTracks

public List<Track> getTracks()

Return an unmodifiable list of the GPX tracks.

Returns:

an unmodifiable list of the GPX tracks.

tracks

public Stream<Track> tracks()

Return a stream of the GPX tracks.

Returns:

a stream of the GPX tracks.

toBuilder

public GPX.Builder toBuilder()

Convert the immutable GPX object into a mutable builder initialized with the current GPX values.

Returns:

a new track builder initialized with the values of this GPX object

Since:

1.1

toString

public String toString()

Overrides:

toString in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

builder

public static GPX.Builder builder(String version,
                                  String creator)

Create a new GPX builder with the given GPX version and creator string.

Parameters:

version - the GPX version string

creator - the GPX creator

Returns:

new GPX builder

Throws:

NullPointerException - if one of the arguments is null

builder

public static GPX.Builder builder(String creator)

Create a new GPX builder with the given GPX creator string.

Parameters:

creator - the GPX creator

Returns:

new GPX builder

Throws:

NullPointerException - if the given arguments is null

builder

public static GPX.Builder builder()

Create a new GPX builder.

Returns:

new GPX builder

of

public static GPX of(String creator,
                     Metadata metadata,
                     List<WayPoint> wayPoints,
                     List<Route> routes,
                     List<Track> tracks)

Create a new GPX object with the given data.

Parameters:

creator - the name or URL of the software that created your GPX document. This allows others to inform the creator of a GPX instance document that fails to validate.

metadata - the metadata about the GPS file

wayPoints - the way-points

routes - the routes

tracks - the tracks

Returns:

a new GPX object with the given data

Throws:

NullPointerException - if the creator, {code wayPoints}, routes or tracks is null

of

public static GPX of(String version,
                     String creator,
                     Metadata metadata,
                     List<WayPoint> wayPoints,
                     List<Route> routes,
                     List<Track> tracks)

Create a new GPX object with the given data.

Parameters:

creator - the name or URL of the software that created your GPX document. This allows others to inform the creator of a GPX instance document that fails to validate.

version - the GPX version

metadata - the metadata about the GPS file

wayPoints - the way-points

routes - the routes

tracks - the tracks

Returns:

a new GPX object with the given data

Throws:

NullPointerException - if the creator, {code wayPoints}, routes or tracks is null

write

public static void write(GPX gpx,
                         OutputStream output)
                  throws IOException

Writes the given gpx object (in GPX XML format) to the given output stream.

Parameters:

gpx - the GPX object to write to the output

output - the output stream where the GPX object is written to

Throws:

IOException - if the writing of the GPX object fails

NullPointerException - if one of the given arguments is null

write

public static void write(GPX gpx,
                         Path path)
                  throws IOException

Writes the given gpx object (in GPX XML format) to the given output stream.

Parameters:

gpx - the GPX object to write to the output

path - the output path where the GPX object is written to

Throws:

IOException - if the writing of the GPX object fails

NullPointerException - if one of the given arguments is null

Since:

1.1

write

public static void write(GPX gpx,
                         String path)
                  throws IOException

Writes the given gpx object (in GPX XML format) to the given output stream.

Parameters:

gpx - the GPX object to write to the output

path - the output path where the GPX object is written to

Throws:

IOException - if the writing of the GPX object fails

NullPointerException - if one of the given arguments is null

write

public static void write(GPX gpx,
                         OutputStream output,
                         String indent)
                  throws IOException

Writes the given gpx object (in GPX XML format) to the given output stream.

Parameters:

gpx - the GPX object to write to the output

output - the output stream where the GPX object is written to

indent - the indent string for pretty printing. If the string is null, no pretty printing is performed.

Throws:

IOException - if the writing of the GPX object fails

NullPointerException - if one of the given arguments is null

write

public static void write(GPX gpx,
                         Path path,
                         String indent)
                  throws IOException

Writes the given gpx object (in GPX XML format) to the given output stream.

Parameters:

gpx - the GPX object to write to the output

path - the output path where the GPX object is written to

indent - the indent string for pretty printing. If the string is null, no pretty printing is performed.

Throws:

IOException - if the writing of the GPX object fails

NullPointerException - if one of the given arguments is null

write

public static void write(GPX gpx,
                         String path,
                         String indent)
                  throws IOException

Writes the given gpx object (in GPX XML format) to the given output stream.

Parameters:

gpx - the GPX object to write to the output

path - the output path where the GPX object is written to

indent - the indent string for pretty printing. If the string is null, no pretty printing is performed.

Throws:

IOException - if the writing of the GPX object fails

NullPointerException - if one of the given arguments is null

read

public static GPX read(InputStream input,
                       boolean lenient)
                throws IOException

Read an GPX object from the given input stream.

Parameters:

input - the input stream from where the GPX date is read

lenient - if true, out-of-range and syntactical errors are ignored. E.g. a WayPoint with lat values not in the valid range of [-90..90] are ignored/skipped.

Returns:

the GPX object read from the input stream

Throws:

IOException - if the GPX object can't be read

NullPointerException - if the given input stream is null

Since:

1.1

read

public static GPX read(InputStream input)
                throws IOException

Read an GPX object from the given input stream.

Parameters:

input - the input stream from where the GPX date is read

Returns:

the GPX object read from the input stream

Throws:

IOException - if the GPX object can't be read

NullPointerException - if the given input stream is null

read

public static GPX read(Path path,
                       boolean lenient)
                throws IOException

Read an GPX object from the given input stream.

Parameters:

path - the input path from where the GPX date is read

lenient - if true, out-of-range and syntactical errors are ignored. E.g. a WayPoint with lat values not in the valid range of [-90..90] are ignored/skipped.

Returns:

the GPX object read from the input stream

Throws:

IOException - if the GPX object can't be read

NullPointerException - if the given input stream is null

read

public static GPX read(Path path)
                throws IOException

Read an GPX object from the given input stream.

Parameters:

path - the input path from where the GPX date is read

Returns:

the GPX object read from the input stream

Throws:

IOException - if the GPX object can't be read

NullPointerException - if the given input stream is null

read

public static GPX read(String path,
                       boolean lenient)
                throws IOException

Read an GPX object from the given input stream.

Parameters:

path - the input path from where the GPX date is read

lenient - if true, out-of-range and syntactical errors are ignored. E.g. a WayPoint with lat values not in the valid range of [-90..90] are ignored/skipped.

Returns:

the GPX object read from the input stream

Throws:

IOException - if the GPX object can't be read

NullPointerException - if the given input stream is null

read

public static GPX read(String path)
                throws IOException

Read an GPX object from the given input stream.

Parameters:

path - the input path from where the GPX date is read

Returns:

the GPX object read from the input stream

Throws:

IOException - if the GPX object can't be read

NullPointerException - if the given input stream is null