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.20100).lon(16.31651).ele(283))
             .addPoint(p -> p.lat(48.20112).lon(16.31639).ele(278))
             .addPoint(p -> p.lat(48.20126).lon(16.31601).ele(274))))
     .build();

Writing a GPX file

 final var indent = new GPX.Writer.Indent("    ");
 GPX.Writer.of(indent).write(gpx, Path.of("points.gpx"));

This will produce the following output.

 <gpx version="1.1" creator="JPX - https://github.com/jenetics/jpx" xmlns="http://www.topografix.com/GPX/1/1">
     <trk>
         <trkseg>
             <trkpt lat="48.201" lon="16.31651">
                 <ele>283</ele>
             </trkpt>
             <trkpt lat="48.20112" lon="16.31639">
                 <ele>278</ele>
             </trkpt>
             <trkpt lat="48.20126" lon="16.31601">
                 <ele>274</ele>
             </trkpt>
         </trkseg>
     </trk>
 </gpx>

Reading a GPX file

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

Reading erroneous GPX files

final GPX gpx = GPX.Reader.of(GPX.Reader.Mode.LENIENT).read("track.xml");

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/1">
   <metadata>
     <time>2019-12-31T21:36:04.134Z</time>
     <bounds minlat="48.175186667" minlon="16.299580000" maxlat="48.199555000" maxlon="16.416933333"/>
   </metadata>
   <trk>
     <trkseg>
       <trkpt lat="48.184298333" lon="16.299580000">
         <ele>0.000</ele>
         <time>2011-03-20T09:47:16Z</time>
         <geoidheight>43.5</geoidheight>
         <fix>2d</fix>
         <sat>3</sat>
         <hdop>4.200000</hdop>
         <vdop>1.000000</vdop>
         <pdop>4.300000</pdop>
       </trkpt>
       <trkpt lat="48.175186667" lon="16.303916667">
         <ele>0.000</ele>
         <time>2011-03-20T09:51:31Z</time>
         <geoidheight>43.5</geoidheight>
         <fix>2d</fix>
         <sat>3</sat>
         <hdop>16.600000</hdop>
         <vdop>0.900000</vdop>
         <pdop>16.600000</pdop>
       </trkpt>
     </trkseg>
   </trk>
 </gpx>

which is read as (if you write it again)

 <?xml version="1.0" encoding="UTF-8"?>
 <gpx version="1.1" creator="GPSBabel - http://www.gpsbabel.org" xmlns="http://www.topografix.com/GPX/1/1">
     <metadata>
         <time>2019-12-31T21:36:04.134Z</time>
         <bounds minlat="48.175187" minlon="16.29958" maxlat="48.199555" maxlon="16.416933"></bounds>
     </metadata>
     <trk>
         <trkseg>
             <trkpt lat="48.184298" lon="16.29958">
                 <ele>0</ele>
                 <time>2011-03-20T09:47:16Z</time>
                 <geoidheight>43.5</geoidheight>
                 <fix>2d</fix>
                 <sat>3</sat>
                 <hdop>4.2</hdop>
                 <vdop>1</vdop>
                 <pdop>4.3</pdop>
             </trkpt>
             <trkpt lat="48.175187" lon="16.303917">
                 <ele>0</ele>
                 <time>2011-03-20T09:51:31Z</time>
                 <geoidheight>43.5</geoidheight>
                 <fix>2d</fix>
                 <sat>3</sat>
                 <hdop>16.6</hdop>
                 <vdop>0.9</vdop>
                 <pdop>16.6</pdop>
             </trkpt>
         </trkseg>
     </trk>
 </gpx>

Converting a GPX object to an XML Document

 final GPX gpx = ...;

 final Document doc = XMLProvider.provider()
     .documentBuilderFactory()
     .newDocumentBuilder()
     .newDocument();

 // The GPX data are written to the empty `doc` object.
 GPX.Writer.DEFAULT.write(gpx, new DOMResult(doc));

Since:

1.0

Version:

2.0

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type

Class

Description

static final class

GPX.Builder

Builder class for creating immutable GPX objects.

static final class

GPX.Reader

Class for reading GPX files.

static enum

GPX.Version

Represents the available GPX versions.

static final class

GPX.Writer

Class for writing GPX files.
Method Summary

Modifier and Type

Method

Description

static GPX.Builder

builder()

Create a new GPX builder.

static GPX.Builder

builder(GPX.Version version, String creator)

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

static GPX.Builder

builder(String creator)

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

boolean

equals(Object obj)

String

getCreator()

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

Optional<Document>

getExtensions()

Return the (cloned) extensions 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(GPX.Version 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

of(GPX.Version version, String creator, Metadata metadata, List<WayPoint> wayPoints, List<Route> routes, List<Track> tracks, Document extensions)

Create a new GPX object with the given data.

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 creator, Metadata metadata, List<WayPoint> wayPoints, List<Route> routes, List<Track> tracks, Document extensions)

Create a new GPX object with the given data.

static GPX

read(Path path)

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, Path path)

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

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Details
- 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.
- getExtensions
  
  public Optional<Document> getExtensions()
  
  Return the (cloned) extensions document. The root element of the returned document has the name extensions.
  <extensions> ... </extensions>
  
  Returns:
  
  the extensions document
  
  Since:
  
  1.5
- 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(GPX.Version version, String creator)
  
  Create a new GPX builder with the given GPX version and creator string.
  
  Parameters:
  
  version - the GPX version
  
  creator - the GPX creator
  
  Returns:
  
  new GPX builder
  
  Throws:
  
  NullPointerException - if one of the arguments is null
  
  Since:
  
  1.3
- 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(GPX.Version version, String creator, Metadata metadata, List<WayPoint> wayPoints, List<Route> routes, List<Track> tracks, Document extensions)
  
  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
  
  extensions - the XML extensions
  
  Returns:
  
  a new GPX object with the given data
  
  Throws:
  
  NullPointerException - if the creator, {code wayPoints}, routes or tracks is null
  
  Since:
  
  1.5
- 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 creator, Metadata metadata, List<WayPoint> wayPoints, List<Route> routes, List<Track> tracks, Document extensions)
  
  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
  
  extensions - the XML extensions
  
  Returns:
  
  a new GPX object with the given data
  
  Throws:
  
  NullPointerException - if the creator, {code wayPoints}, routes or tracks is null
  
  Since:
  
  1.5
- of
  
  public static GPX of(GPX.Version 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, Path path) throws IOException
  
  Writes the given gpx object (in GPX XML format) to the given path. This method is a shortcut for
  GPX.Writer.DEFAULT.write(gpx, path);
  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
  
  See Also:
  
  GPX.Writer
- read
  
  public static GPX read(Path path) throws IOException
  
  Read an GPX object from the given input stream. This method is a shortcut for
  GPX.Reader.DEFAULT.read(path);
  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
  
  See Also:
  
  GPX.Reader

Class GPX

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Details

getVersion

getCreator

getMetadata

getWayPoints

wayPoints

getRoutes

routes

getTracks

tracks

getExtensions

toBuilder

toString

hashCode

equals

builder

builder

builder

of

of

of

of

write

read