ayech0x2/Android_GPX

Small Android library to parse and create GPX files

Android_GPX

This is a small Android library that I created for a work project, it can be used to easily parse and create GPX files.

Have a look at the sample project using this library at:

https://github.com/FrancescoRigoni/Android_GPX_SampleProject

The library contains a SAX parser for the GPX format, as described in the GPX Schema documentation at http://www.topografix.com/gpx/1/1/ .

The Gpx parser is asynchronous, this means that an event listener interface must be provided when the parser is started. The parsed GPX document or any parsing error that may occur will be returned through the event listener interface.

Basic Usage

This is the basic code required to parse a GPX file, assuming that we have a "file.gpx" in the assets folder:

    try {
      
      InputStream input = getAssets().open("file.gpx");
      
      // The GpxParser automatically closes the InputStream so we do not have to bother about it
      new GpxParser(input, this, this).parse();
      
    } catch (IOException e) {
      // Error opening/reading file
    }

The GpxParser constructor takes three parameters:

• The InputStream for input data
• A GpxParserListener implementation (see below)
• A GpxParserProgressListener implementation, can be null (see below)

Once the GpxParser has been constructed just call the parse() method to start it.

Parser Listeners

Two different event listeners can be provided to the GpxParser constructor:

public GpxParser(InputStream gpxIs, 
                 GpxParserListener listener, 
                 GpxParserProgressListener progressListener)

The GpxParserListener is mandatory, an IllegalArgumentException will be thrown if this argument is null. GpxParserListener provides basic feedback on the parser activity, the methods are pretty self explanatory:

public static interface GpxParserListener {
		
	public void onGpxParseStarted();
	public void onGpxParseCompleted(GPXDocument document);
	public void onGpxParseError(String type, String message, int lineNumber, int columnNumber);
		
}

The GpxParserProgressListener on the other hand is only required if you need a fine degree of feedback on what the parser is currently doing in the background. This listener should be used only if necessary as it implies implementing a lot of methods.

public static interface GpxParserProgressListener {

  public void onGpxNewTrackParsed(int count, GPXTrack track);
  public void onGpxNewRouteParsed(int count, GPXRoute track);
  public void onGpxNewSegmentParsed(int count, GPXSegment segment);
  public void onGpxNewTrackPointParsed(int count, GPXTrackPoint trackPoint);
  public void onGpxNewRoutePointParsed(int count, GPXRoutePoint routePoint);
  public void onGpxNewWayPointParsed(int count, GPXWayPoint wayPoint);
		
}

As you can see the GpxParserProgressListener can be used to get a callback on every GPX entity that is being parsed.

Internal GPX representation

As you may have noticed this library provides a set of objects to represent different GPX entities

• GPXDocument Top level container, represents the GPX file
• GPXTrack GPX trk entity
• GPXRoute GPX rte entity
• GPXSegment GPX trkseg entity
• GPXTrackPoint GPX trkpt entity
• GPXRoutePoint GPX rtept entity
• GPXWayPoint GPX wpt entity

Please read the code for more details on how these classes work.