Merge pull request #4 from jenetics/r1.0.0

Release 1.0.0

Author: jenetics

README.md

@@ -1,6 +1,8 @@
 # JPX - Java GPX library
 
-This is a Java library for creating, reading and writing GPS data in [GPX](http://www.topografix.com/GPX) format. It implements version [1.1](http://www.topografix.com/GPX/1/1/) of the GPX format. Javadoc of the library can be [here](https://jenetics.github.io/jpx/javadoc/jpx/index.html).
+**JPX** is a Java library for creating, reading and writing [GPS](https://en.wikipedia.org/wiki/Global_Positioning_System) data in [GPX](https://en.wikipedia.org/wiki/GPS_Exchange_Format) format. It is a *full* implementation of version [1.1](http://www.topografix.com/GPX/1/1/) of the GPX format. The data classes are completely immutable and allows a functional programming style. They  are working also nicely with the Java 8 [Stream](http://docs.oracle.com/javase/8/docs/api/java/util/stream/Stream.html) API.
+
+ The comprehensive Javadoc of the library can be [here](https://jenetics.github.io/jpx/javadoc/jpx/index.html).
 
 ## Requirements
 
@@ -29,7 +31,7 @@ For building the JPX library you have to check out the master branch from Github
 
     $ ./gradle jar
 
-## Download (soon available)
+## Download
 
 * **Github**: <https://github.com/jenetics/jpx/archive/v1.0.0.zip>
 *  **Maven**: `io.jenetics:jpx:1.0.0` on <a href="http://search.maven.org/#search%7Cga%7C1%7Ca%3A%22jpx%22">Maven Central</a>   
@@ -51,15 +53,14 @@ final GPX gpx = GPX.builder()
 **Writing GPX object to a file**
 
 ```java
-// Writing "pretty" GPX file.
-GPX.write(gpx, "    ", "gpx.xml");
+GPX.write(gpx, "gpx.xml");
 ```
 
 *GPX output*
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
-<gpx xmlns="http://www.topografix.com/GPX/1/1" version="1.1" creator="JPX - Java GPX library">
+<gpx version="1.1" creator="JPX - Java GPX library" xmlns="http://www.topografix.com/GPX/1/1">
     <trk>
         <trkseg>
             <trkpt lat="48.2081743" lon="16.3738189">
@@ -106,7 +107,7 @@ $ [lat=48.2081743, lon=48.2081743, ele=162]
 ```java
 final Point start = WayPoint.of(47.2692124, 11.4041024);
 final Point end = WayPoint.of(47.3502, 11.70584);
-final Length distance = Geoid.WGSC_84.distance(start, end);
+final Length distance = Geoid.WGSC84.distance(start, end);
 System.out.println(distance);
 ```
 
@@ -125,7 +126,7 @@ final Length length = gpx.tracks()
     .flatMap(Track::segments)
     .findFirst()
     .map(TrackSegment::points).orElse(Stream.empty())
-    .collect(Geoid.WGSC_84.toPathLength());
+    .collect(Geoid.WGSC84.toPathLength());
 ```
 
 

build.gradle

@@ -39,7 +39,7 @@ ext {
 
 allprojects {
 	group = 'io.jenetics'
-	version = '1.0.0-SNAPSHOT'
+	version = '1.0.0'
 
 	repositories {
 		flatDir(dir: "${rootDir}/buildSrc/lib")

jpx/build.gradle

@@ -37,7 +37,7 @@ repositories {
 }
 
 dependencies {
-	testCompile 'org.testng:testng:6.9.10'
+	testCompile 'org.testng:testng:6.10'
 }
 
 javadoc {
@@ -62,7 +62,7 @@ javadoc {
 	doLast {
 		project.copy {
 			from('src/main/java') {
-				include 'org/**/doc-files/*.*'
+				include 'io/**/doc-files/*.*'
 			}
 			includeEmptyDirs = false
 			into destinationDir.path

jpx/src/main/java/io/jenetics/jpx/DGPSStation.java

@@ -33,7 +33,12 @@
  * @version 1.0
  * @since 1.0
  */
-public final class DGPSStation extends Number implements Serializable {
+public final class DGPSStation
+	extends Number
+	implements
+		Comparable<DGPSStation>,
+		Serializable
+{
 
 	private static final long serialVersionUID = 1L;
 
@@ -80,6 +85,11 @@ public float floatValue() {
 		return (float)_value;
 	}
 
+	@Override
+	public int compareTo(final DGPSStation other) {
+		return Integer.compare(_value, other._value);
+	}
+
 	@Override
 	public int hashCode() {
 		return Integer.hashCode(_value);

jpx/src/main/java/io/jenetics/jpx/Degrees.java

@@ -33,7 +33,12 @@
  * @version 1.0
  * @since 1.0
  */
-public final class Degrees extends Number implements Serializable {
+public final class Degrees
+	extends Number
+	implements
+		Comparable<Degrees>,
+		Serializable
+{
 
 	private static final long serialVersionUID = 1L;
 
@@ -100,6 +105,11 @@ public float floatValue() {
 		return (float)doubleValue();
 	}
 
+	@Override
+	public int compareTo(final Degrees other) {
+		return Double.compare(_value, other._value);
+	}
+
 	@Override
 	public int hashCode() {
 		return Double.hashCode(_value);

jpx/src/main/java/io/jenetics/jpx/Email.java

@@ -37,7 +37,7 @@
  * @version 1.0
  * @since 1.0
  */
-public final class Email implements Serializable {
+public final class Email implements Comparable<Email>, Serializable {
 
 	private static final long serialVersionUID = 1L;
 
@@ -75,6 +75,25 @@ public String getDomain() {
 		return _domain;
 	}
 
+	/**
+	 * Return the full EMail address: id + "@" + domain.
+	 *
+	 * @return the full EMail address: id + "@" + domain
+	 */
+	public String getAddress() {
+		return _id + "@" + _domain;
+	}
+
+	@Override
+	public int compareTo(final Email other) {
+		int cmp = _domain.compareTo(other._domain);
+		if (cmp == 0) {
+			cmp = _id.compareTo(other._id);
+		}
+
+		return cmp;
+	}
+
 	@Override
 	public int hashCode() {
 		int hash = 37;
@@ -92,7 +111,7 @@ public boolean equals(final Object obj) {
 
 	@Override
 	public String toString() {
-		return _id + "@" + _domain;
+		return getAddress();
 	}
 
 

jpx/src/main/java/io/jenetics/jpx/Length.java

@@ -20,6 +20,7 @@
 package io.jenetics.jpx;
 
 import static java.lang.String.format;
+import static java.util.Objects.requireNonNull;
 
 import java.io.Serializable;
 
@@ -32,10 +33,71 @@
  * @version 1.0
  * @since 1.0
  */
-public final class Length extends Number implements Serializable {
+public final class Length
+	extends Number
+	implements
+		Comparable<Length>,
+		Serializable
+{
 
 	private static final long serialVersionUID = 1L;
 
+	/**
+	 * Represents a given length unit.
+	 */
+	public static enum Unit {
+
+		/**
+		 * Represents a meter.
+		 */
+		METER(1.0),
+
+		/**
+		 * Represents a kilometer.
+		 */
+		KILOMETER(1_000.0),
+
+		/**
+		 * Represents an inch.
+		 */
+		INCH(127.0/5_000.0),
+
+		/**
+		 * Represents a yard.
+		 */
+		YARD(1_143.0/1_250.0),
+
+		/**
+		 * Represents a mile.
+		 */
+		MILE(201_168.0/125.0);
+
+		private final double _factor;
+
+		private Unit(final double factor) {
+			_factor = factor;
+		}
+
+		/**
+		 * Convert the given length value of the given {@code sourceUnit} into a
+		 * length value of {@code this} length unit. The given example converts 3
+		 * inches into yards.
+		 *
+		 * <pre>{@code
+		 * final double yards = YARD.convert(3, INCH);
+		 * }</pre>
+		 *
+		 * @param length the length value
+		 * @param sourceUnit the source length unit
+		 * @return the speed value of {@code this} length unit
+		 */
+		public double convert(final double length, final Unit sourceUnit) {
+			requireNonNull(sourceUnit);
+			final double meters = length*sourceUnit._factor;
+			return meters/_factor;
+		}
+	}
+
 	private final double _value;
 
 	/**
@@ -58,21 +120,15 @@ public double doubleValue() {
 	}
 
 	/**
-	 * Return the length in meter.
+	 * Return the length in the desired unit.
 	 *
-	 * @return the length in meter
+	 * @param unit the desired length unit
+	 * @return the length in the desired unit
+	 * @throws NullPointerException if the given length {@code unit} is
+	 *         {@code null}
 	 */
-	public double toMeters() {
-		return _value;
-	}
-
-	/**
-	 * Return the length in kilometers.
-	 *
-	 * @return the length in kilometers
-	 */
-	public double toKilometer() {
-		return _value/1000.0;
+	public double to(final Unit unit) {
+		return unit.convert(_value, Unit.METER);
 	}
 
 	@Override
@@ -90,6 +146,11 @@ public float floatValue() {
 		return (float)doubleValue();
 	}
 
+	@Override
+	public int compareTo(final Length other) {
+		return Double.compare(_value, other._value);
+	}
+
 	@Override
 	public int hashCode() {
 		return Double.hashCode(_value);
@@ -112,23 +173,17 @@ public String toString() {
 	 * ************************************************************************/
 
 	/**
-	 * Create a new {@code Length} object with the given value in meters.
-	 *
-	 * @param meters the length in meters
-	 * @return a new {@code Length} object with the given value in meters.
-	 */
-	public static Length ofMeters(final double meters) {
-		return new Length(meters);
-	}
-
-	/**
-	 * Create a new {@code Length} object with the given value in km.
+	 * Create a new {@code Length} object with the given length.
 	 *
-	 * @param km the length in kilometers
-	 * @return a new {@code Length} object with the given value in kilometers.
+	 * @param length the length
+	 * @param unit the length unit
+	 * @return a new {@code Length} object with the given length.
+	 * @throws NullPointerException if the given length {@code unit} is
+	 *         {@code null}
 	 */
-	public static Length ofKilometers(final double km) {
-		return new Length(km*1000);
+	public static Length of(final double length, final Unit unit) {
+		requireNonNull(unit);
+		return new Length(Unit.METER.convert(length, unit));
 	}
 
 	/**
@@ -141,9 +196,9 @@ static Length parse(final Object object) {
 		return object instanceof Length
 			? (Length)object
 			: object instanceof Number
-				? ofMeters(((Number) object).doubleValue())
+				? of(((Number)object).doubleValue(), Unit.METER)
 				: object != null
-					? ofMeters(Double.parseDouble(object.toString()))
+					? of(Double.parseDouble(object.toString()), Unit.METER)
 					: null;
 	}
 

jpx/src/main/java/io/jenetics/jpx/Metadata.java

@@ -178,6 +178,21 @@ public Optional<Bounds> getBounds() {
 		return Optional.ofNullable(_bounds);
 	}
 
+	/**
+	 * Return {@code true} if all metadata properties are {@code null} or empty.
+	 *
+	 * @return {@code true} if all metadata properties are {@code null} or empty
+	 */
+	public boolean isEmpty() {
+		return _name == null &&
+			_description == null &&
+			_author == null &&
+			_copyright == null &&
+			_links.isEmpty() &&
+			_time == null &&
+			_keywords == null &&
+			_bounds == null;
+	}
 
 	@Override
 	public int hashCode() {

jpx/src/main/java/io/jenetics/jpx/Person.java

@@ -82,6 +82,17 @@ public Optional<Link> getLink() {
 		return Optional.ofNullable(_link);
 	}
 
+	/**
+	 * Return {@code true} if all person properties are {@code null}.
+	 *
+	 * @return {@code true} if all person properties are {@code null}
+	 */
+	public boolean isEmpty() {
+		return _name == null &&
+			_email == null &&
+			_link == null;
+	}
+
 	@Override
 	public int hashCode() {
 		int hash = 37;

jpx/src/main/java/io/jenetics/jpx/Point.java

@@ -66,7 +66,10 @@ public default Optional<ZonedDateTime> getTime() {
 	}
 
 	/**
-	 * Calculate the distance between points on an ellipsoidal earth model.
+	 * Calculate the distance between points on the default ellipsoidal earth
+	 * model
+	 * <a href="https://en.wikipedia.org/wiki/World_Geodetic_System#A_new_World_Geodetic_System:_WGS_84">
+	 * WGS-84</a>.
 	 *
 	 * @see <a href="http://www.ngs.noaa.gov/PUBS_LIB/inverse.pdf">DIRECT AND
 	 *               INVERSE SOLUTIONS OF GEODESICS 0 THE ELLIPSOID