From 74149c2504ba1dfc379b841ad076978d866825ba Mon Sep 17 00:00:00 2001 From: Martin Desruisseaux Date: Wed, 2 May 2018 13:46:23 +0200 Subject: Replacement of "Proj.4 library" by "Proj library" and other documentation update or formatting. There is no code change in this commit, except the addition of @Native annotation on a constant. --- jniwrap/org/proj4/PJ.java | 140 ++++++++++++++++++------------------ jniwrap/org/proj4/PJException.java | 13 ++-- jniwrap/org/proj4/package-info.java | 17 +++-- 3 files changed, 83 insertions(+), 87 deletions(-) diff --git a/jniwrap/org/proj4/PJ.java b/jniwrap/org/proj4/PJ.java index 6b387287..27b0f25d 100644 --- a/jniwrap/org/proj4/PJ.java +++ b/jniwrap/org/proj4/PJ.java @@ -1,10 +1,10 @@ /****************************************************************************** * Project: PROJ.4 - * Purpose: Java/JNI wrappers for PROJ.4 API. + * Purpose: Java/JNI wrappers for PROJ API. * Author: Martin Desruisseaux * ****************************************************************************** - * Copyright (c) 2011, Open Geospatial Consortium, Inc. + * Copyright (c) 2011-2018, Open Geospatial Consortium, Inc. * * Permission is hereby granted, free of charge, to any person obtaining a * copy of this software and associated documentation files (the "Software"), @@ -23,58 +23,60 @@ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER * DEALINGS IN THE SOFTWARE. - ***************************************************************************** - * This file is a copy of a file developed in the GeoAPI "Proj.4 binding" - * module (http://www.geoapi.org/geoapi-proj4/index.html). If this file is - * modified, please consider synchronizing the changes with GeoAPI. + ****************************************************************************** */ package org.proj4; +import java.util.Objects; +import java.lang.annotation.Native; + /** - * Wraps the Proj4 {@code PJ} native data structure. - * Almost every methods defined in this class are native methods delegating the work to the - * Proj.4 library. This class is the only place where such native methods are defined. - *

- * In the Proj.4 library, the {@code PJ} structure aggregates in a single place information usually - * split in many different ISO 19111 interfaces: {@link org.opengis.referencing.datum.Ellipsoid}, + * Wraps the Proj {@code PJ} native data structure. + * Almost every methods defined in this class are native methods delegating the work to the Proj library. + * This class is the only place where such native methods are defined. + * + *

In the Proj library, the {@code PJ} structure aggregates in a single place information usually + * splitted in many different ISO 19111 interfaces: {@link org.opengis.referencing.datum.Ellipsoid}, * {@link org.opengis.referencing.datum.Datum}, {@link org.opengis.referencing.datum.PrimeMeridian}, * {@link org.opengis.referencing.cs.CoordinateSystem}, {@link org.opengis.referencing.crs.CoordinateReferenceSystem} * and their sub-interfaces. The relationship with the GeoAPI methods is indicated in the - * "See" tags when appropriate. + * "See" tags when appropriate.

* * @author Martin Desruisseaux (Geomatys) + * @version 5.1 + * @since 4.8 */ public class PJ { /** - * The maximal number of dimension accepted by the {@link #transform(PJ, int, double[], int, int)} - * method. This upper limit is actually somewhat arbitrary. This limit exists mostly as a safety - * against potential misuse. + * The maximal number of dimension accepted by the {@link #transform(PJ, int, double[], int, int)} method. + * This upper limit is actually somewhat arbitrary. This limit exists mostly as a safety against potential misuse. */ + @Native public static final int DIMENSION_MAX = 100; - // IMPLEMENTATION NOTE: if the value is modified, edit also the native C file. /** - * Loads the Proj4 library. + * Loads the Proj library. */ static { System.loadLibrary("proj"); } /** - * The pointer to {@code PJ} structure allocated in the C/C++ heap. This value has no - * meaning in Java code. Do not modify, since this value is used by Proj4. - * Do not rename neither, unless you update accordingly the C code in JNI wrappers. + * The pointer to {@code PJ} structure allocated in the C/C++ heap. This value has no meaning in Java code. + * Do not modify, since this value is used by Proj. Do not rename neither, unless you update + * accordingly the C code in JNI wrappers. */ private final long ptr; /** - * Creates a new {@code PJ} structure from the given Proj4 definition string. + * Creates a new {@code PJ} structure from the given Proj definition string. * - * @param definition The Proj.4 definition string. - * @throws IllegalArgumentException If the PJ structure can not be created from the given string. + * @param definition the Proj definition string. + * @throws IllegalArgumentException if the PJ structure can not be created from the given string. */ public PJ(final String definition) throws IllegalArgumentException { + Objects.requireNonNull(definition); ptr = allocatePJ(definition); if (ptr == 0) { throw new IllegalArgumentException(definition); @@ -87,15 +89,12 @@ public class PJ { * {@linkplain org.opengis.referencing.crs.ProjectedCRS#getBaseCRS() base geographic CRS} * from a {@linkplain org.opengis.referencing.crs.ProjectedCRS projected CRS}. * - * @param crs The CRS (usually projected) from which to derive a new CRS. - * @param type The type of the new CRS. Currently, only {@link Type#GEOGRAPHIC} is supported. - * @throws IllegalArgumentException If the PJ structure can not be created. + * @param crs the CRS (usually projected) from which to derive a new CRS. + * @param type the type of the new CRS. Currently, only {@link Type#GEOGRAPHIC} is supported. + * @throws IllegalArgumentException if the PJ structure can not be created. */ public PJ(final PJ crs, final Type type) throws IllegalArgumentException { - if (crs == null) { - // TODO: Use Objects with JDK 7. - throw new NullPointerException("The CRS must be non-null."); - } + Objects.requireNonNull(crs, "The CRS must be non-null."); if (type != Type.GEOGRAPHIC) { throw new IllegalArgumentException("Can not derive the " + type + " type."); } @@ -111,8 +110,8 @@ public class PJ { * to the {@link #ptr} field. The allocated structure is released by the {@link #finalize()} * method. * - * @param definition The Proj4 definition string. - * @return A pointer to the PJ native data structure, or 0 if the operation failed. + * @param definition the Proj definition string. + * @return a pointer to the PJ native data structure, or 0 if the operation failed. */ private static native long allocatePJ(String definition); @@ -122,39 +121,41 @@ public class PJ { * the return value must be assigned to the {@link #ptr} field. * The allocated structure is released by the {@link #finalize()} method. * - * @param projected The CRS from which to derive the base geographic CRS. - * @return A pointer to the PJ native data structure, or 0 if the operation failed. + * @param projected the CRS from which to derive the base geographic CRS. + * @return a pointer to the PJ native data structure, or 0 if the operation failed. */ private static native long allocateGeoPJ(PJ projected); /** - * Returns the version number of the Proj4 library. + * Returns the version number of the Proj library. * - * @return The Proj.4 release string. + * @return the Proj release string. */ public static native String getVersion(); /** - * Returns the Proj4 definition string. This is the string given to the constructor, + * Returns the Proj definition string. This is the string given to the constructor, * expanded with as much information as possible. * - * @return The Proj4 definition string. + * @return the Proj definition string. */ public native String getDefinition(); /** * Returns the Coordinate Reference System type. * - * @return The CRS type. + * @return the CRS type. */ public native Type getType(); /** * The coordinate reference system (CRS) type returned by {@link PJ#getType()}. - * In the Proj.4 library, a CRS can only be geographic, geocentric or projected, + * In the Proj library, a CRS can only be geographic, geocentric or projected, * without distinction between 2D and 3D CRS. * * @author Martin Desruisseaux (Geomatys) + * @version 5.1 + * @since 4.8 */ public static enum Type { /* @@ -184,7 +185,7 @@ public class PJ { /** * Returns the value stored in the {@code a_orig} PJ field. * - * @return The axis length stored in {@code a_orig}. + * @return the axis length stored in {@code a_orig}. * * @see org.opengis.referencing.datum.Ellipsoid#getSemiMajorAxis() */ @@ -193,18 +194,18 @@ public class PJ { /** * Returns the value computed from PJ fields by {@code √((a_orig)² × (1 - es_orig))}. * - * @return The axis length computed by {@code √((a_orig)² × (1 - es_orig))}. + * @return the axis length computed by {@code √((a_orig)² × (1 - es_orig))}. * * @see org.opengis.referencing.datum.Ellipsoid#getSemiMinorAxis() */ public native double getSemiMinorAxis(); /** - * Returns the square of the ellipsoid eccentricity (ε²). The eccentricity - * is related to axis length by ε=√(1-(b/a)²). The + * Returns the square of the ellipsoid eccentricity (ε²). The eccentricity + * is related to axis length by ε=√(1-(b/a)²). The * eccentricity of a sphere is zero. * - * @return The eccentricity. + * @return the eccentricity. * * @see org.opengis.referencing.datum.Ellipsoid#isSphere() * @see org.opengis.referencing.datum.Ellipsoid#getInverseFlattening() @@ -213,9 +214,9 @@ public class PJ { /** * Returns an array of character indicating the direction of each axis. Directions are - * characters like {@code 'e'} for East, {@code 'n'} for North and {@code 'u'} for Up. + * characters like {@code 'e'} for East, {@code 'n'} for North and {@code 'u'} for Up. * - * @return The axis directions. + * @return the axis directions. * * @see org.opengis.referencing.cs.CoordinateSystemAxis#getDirection() */ @@ -224,7 +225,7 @@ public class PJ { /** * Longitude of the prime meridian measured from the Greenwich meridian, positive eastward. * - * @return The prime meridian longitude, in degrees. + * @return the prime meridian longitude, in degrees. * * @see org.opengis.referencing.datum.PrimeMeridian#getGreenwichLongitude() */ @@ -235,32 +236,30 @@ public class PJ { * * @param vertical {@code false} for the conversion factor of horizontal axes, * or {@code true} for the conversion factor of the vertical axis. - * @return The conversion factor to metres for the given axis. + * @return the conversion factor to metres for the given axis. */ public native double getLinearUnitToMetre(boolean vertical); /** - * Transforms in-place the coordinates in the given array. The coordinates array shall contain - * (x,y,z,…) tuples, where the z and - * following dimensions are optional. Note that any dimension after the z value - * are ignored. - *

- * Input and output units: - *

+ * Transforms in-place the coordinates in the given array. + * The coordinates array shall contain (x,y,z,…) tuples, + * where the z and any additional dimensions are optional. + * Note that any dimension after the z value are ignored. + * + *

Input and output units:

* * - * @param target The target CRS. - * @param dimension The dimension of each coordinate value. Must be in the [2-{@value #DIMENSION_MAX}] range. - * @param coordinates The coordinates to transform, as a sequence of - * (x,y,<z>,…) tuples. - * @param offset Offset of the first coordinate in the given array. - * @param numPts Number of points to transform. - * @throws NullPointerException If the {@code target} or {@code coordinates} argument is null. + * @param target the target CRS. + * @param dimension the dimension of each coordinate value. Must be in the [2-{@value #DIMENSION_MAX}] range. + * @param coordinates the coordinates to transform, as a sequence of (x,y,<z>,…) tuples. + * @param offset offset of the first coordinate in the given array. + * @param numPts number of points to transform. + * @throws NullPointerException if the {@code target} or {@code coordinates} argument is null. * @throws IndexOutOfBoundsException if the {@code offset} or {@code numPts} arguments are invalid. - * @throws PJException If the operation failed for an other reason (provided by Proj4). + * @throws PJException if the operation failed for another reason (provided by Proj). * * @see org.opengis.referencing.operation.MathTransform#transform(double[], int, double[], int, int) */ @@ -270,24 +269,23 @@ public class PJ { /** * Returns a description of the last error that occurred, or {@code null} if none. * - * @return The last error that occurred, or {@code null}. + * @return the last error that occurred, or {@code null}. */ public native String getLastError(); /** * Returns the string representation of the PJ structure. * - * @return The string representation. + * @return the string representation. */ @Override public native String toString(); /** - * Deallocates the native PJ data structure. This method can be invoked only by the garbage - * collector, and must be invoked exactly once (no more, no less). - * NEVER INVOKE THIS METHOD EXPLICITLY, NEVER OVERRIDE. + * Deallocates the native PJ data structure. + * This method should be invoked exactly once, only by the garbage collector, */ @Override - @SuppressWarnings("deprecation") + @SuppressWarnings({"deprecation", "FinalizeDeclaration"}) protected final native void finalize(); } diff --git a/jniwrap/org/proj4/PJException.java b/jniwrap/org/proj4/PJException.java index 18a58851..4b465e6a 100644 --- a/jniwrap/org/proj4/PJException.java +++ b/jniwrap/org/proj4/PJException.java @@ -1,10 +1,10 @@ /****************************************************************************** * Project: PROJ.4 - * Purpose: Java/JNI wrappers for PROJ.4 API. + * Purpose: Java/JNI wrappers for PROJ API. * Author: Martin Desruisseaux * ****************************************************************************** - * Copyright (c) 2011, Open Geospatial Consortium, Inc. + * Copyright (c) 2011-2018, Open Geospatial Consortium, Inc. * * Permission is hereby granted, free of charge, to any person obtaining a * copy of this software and associated documentation files (the "Software"), @@ -23,10 +23,7 @@ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER * DEALINGS IN THE SOFTWARE. - ***************************************************************************** - * This file is a copy of a file developed in the GeoAPI "Proj.4 binding" - * module (http://www.geoapi.org/geoapi-proj4/index.html). If this file is - * modified, please consider synchronizing the changes with GeoAPI. + ****************************************************************************** */ package org.proj4; @@ -35,6 +32,8 @@ package org.proj4; * Exception thrown when a call to {@link PJ#transform(PJ, int, double[], int, int)} failed. * * @author Martin Desruisseaux (Geomatys) + * @version 5.1 + * @since 4.8 */ public class PJException extends Exception { /** @@ -52,7 +51,7 @@ public class PJException extends Exception { /** * Constructs a new exception with the given message. * - * @param message A message that describe the cause for the failure. + * @param message a message that describe the cause for the failure. */ public PJException(final String message) { super(message); diff --git a/jniwrap/org/proj4/package-info.java b/jniwrap/org/proj4/package-info.java index 8a6b75a3..d69fb807 100644 --- a/jniwrap/org/proj4/package-info.java +++ b/jniwrap/org/proj4/package-info.java @@ -1,10 +1,10 @@ /****************************************************************************** * Project: PROJ.4 - * Purpose: Java/JNI wrappers for PROJ.4 API. + * Purpose: Java/JNI wrappers for PROJ API. * Author: Martin Desruisseaux * ****************************************************************************** - * Copyright (c) 2011, Open Geospatial Consortium, Inc. + * Copyright (c) 2011-2018, Open Geospatial Consortium, Inc. * * Permission is hereby granted, free of charge, to any person obtaining a * copy of this software and associated documentation files (the "Software"), @@ -23,18 +23,17 @@ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER * DEALINGS IN THE SOFTWARE. - ***************************************************************************** - * This file is a copy of a file developed in the GeoAPI "Proj.4 binding" - * module (http://www.geoapi.org/geoapi-proj4/index.html). If this file is - * modified, please consider synchronizing the changes with GeoAPI. + ****************************************************************************** */ /** - * Wrappers for the Proj4 library. The {@link org.proj4.PJ} - * class contains only native methods delegating their work to the Proj.4 library. + * Wrappers for the Proj library. + * The {@link org.proj4.PJ} class contains only native methods delegating their work to the Proj library. * For higher-level methods making use of those native methods, see for example the - * GeoAPI bindings for Proj.4. + * GeoAPI bindings for Proj. * * @author Martin Desruisseaux (Geomatys) + * @version 5.1 + * @since 4.8 */ package org.proj4; -- cgit v1.2.3 From 609a8ab36f3d2ba820d548dcf82f745e6eb35c2f Mon Sep 17 00:00:00 2001 From: Martin Desruisseaux Date: Wed, 2 May 2018 13:47:34 +0200 Subject: Add link to GeoAPI for documentation purpose only (the Java classes can still be used standalone). --- jniwrap/build.xml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/jniwrap/build.xml b/jniwrap/build.xml index 7e95e676..9c23c39e 100644 --- a/jniwrap/build.xml +++ b/jniwrap/build.xml @@ -38,7 +38,8 @@ ********************************************************** --> + noqualifier="all" windowtitle="Proj bridge to Java" author="false" version="true" + link="http://www.geoapi.org/3.0/javadoc/" additionalparam="-html5"/> - - + + - + + + + + + + + diff --git a/jniwrap/org.osgeo.proj/module-info.java b/jniwrap/org.osgeo.proj/module-info.java index 8c5739fb..ea8a623a 100644 --- a/jniwrap/org.osgeo.proj/module-info.java +++ b/jniwrap/org.osgeo.proj/module-info.java @@ -1,6 +1,6 @@ /****************************************************************************** * Project: PROJ.4 - * Purpose: Java/JNI wrappers for PROJ.4 API. + * Purpose: Java/JNI wrappers for PROJ API. * Author: Martin Desruisseaux * ****************************************************************************** diff --git a/jniwrap/org.osgeo.proj/org/proj4/PJ.java b/jniwrap/org.osgeo.proj/org/proj4/PJ.java index 27b0f25d..de09f86a 100644 --- a/jniwrap/org.osgeo.proj/org/proj4/PJ.java +++ b/jniwrap/org.osgeo.proj/org/proj4/PJ.java @@ -32,11 +32,11 @@ import java.lang.annotation.Native; /** - * Wraps the Proj {@code PJ} native data structure. - * Almost every methods defined in this class are native methods delegating the work to the Proj library. + * Wraps the PROJ {@code PJ} native data structure. + * Almost every methods defined in this class are native methods delegating the work to the PROJ library. * This class is the only place where such native methods are defined. * - *

In the Proj library, the {@code PJ} structure aggregates in a single place information usually + *

In the PROJ library, the {@code PJ} structure aggregates in a single place information usually * splitted in many different ISO 19111 interfaces: {@link org.opengis.referencing.datum.Ellipsoid}, * {@link org.opengis.referencing.datum.Datum}, {@link org.opengis.referencing.datum.PrimeMeridian}, * {@link org.opengis.referencing.cs.CoordinateSystem}, {@link org.opengis.referencing.crs.CoordinateReferenceSystem} @@ -56,7 +56,7 @@ public class PJ { public static final int DIMENSION_MAX = 100; /** - * Loads the Proj library. + * Loads the PROJ library. */ static { System.loadLibrary("proj"); @@ -64,15 +64,15 @@ public class PJ { /** * The pointer to {@code PJ} structure allocated in the C/C++ heap. This value has no meaning in Java code. - * Do not modify, since this value is used by Proj. Do not rename neither, unless you update + * Do not modify, since this value is used by PROJ. Do not rename neither, unless you update * accordingly the C code in JNI wrappers. */ private final long ptr; /** - * Creates a new {@code PJ} structure from the given Proj definition string. + * Creates a new {@code PJ} structure from the given PROJ definition string. * - * @param definition the Proj definition string. + * @param definition the PROJ definition string. * @throws IllegalArgumentException if the PJ structure can not be created from the given string. */ public PJ(final String definition) throws IllegalArgumentException { @@ -110,7 +110,7 @@ public class PJ { * to the {@link #ptr} field. The allocated structure is released by the {@link #finalize()} * method. * - * @param definition the Proj definition string. + * @param definition the PROJ definition string. * @return a pointer to the PJ native data structure, or 0 if the operation failed. */ private static native long allocatePJ(String definition); @@ -127,17 +127,17 @@ public class PJ { private static native long allocateGeoPJ(PJ projected); /** - * Returns the version number of the Proj library. + * Returns the version number of the PROJ library. * - * @return the Proj release string. + * @return the PROJ release string. */ public static native String getVersion(); /** - * Returns the Proj definition string. This is the string given to the constructor, + * Returns the PROJ definition string. This is the string given to the constructor, * expanded with as much information as possible. * - * @return the Proj definition string. + * @return the PROJ definition string. */ public native String getDefinition(); @@ -150,7 +150,7 @@ public class PJ { /** * The coordinate reference system (CRS) type returned by {@link PJ#getType()}. - * In the Proj library, a CRS can only be geographic, geocentric or projected, + * In the PROJ library, a CRS can only be geographic, geocentric or projected, * without distinction between 2D and 3D CRS. * * @author Martin Desruisseaux (Geomatys) @@ -259,7 +259,7 @@ public class PJ { * @param numPts number of points to transform. * @throws NullPointerException if the {@code target} or {@code coordinates} argument is null. * @throws IndexOutOfBoundsException if the {@code offset} or {@code numPts} arguments are invalid. - * @throws PJException if the operation failed for another reason (provided by Proj). + * @throws PJException if the operation failed for another reason (provided by PROJ). * * @see org.opengis.referencing.operation.MathTransform#transform(double[], int, double[], int, int) */ diff --git a/jniwrap/org.osgeo.proj/org/proj4/package-info.java b/jniwrap/org.osgeo.proj/org/proj4/package-info.java index d69fb807..814d2483 100644 --- a/jniwrap/org.osgeo.proj/org/proj4/package-info.java +++ b/jniwrap/org.osgeo.proj/org/proj4/package-info.java @@ -27,10 +27,10 @@ */ /** - * Wrappers for the Proj library. - * The {@link org.proj4.PJ} class contains only native methods delegating their work to the Proj library. + * Wrappers for the PROJ library. + * The {@link org.proj4.PJ} class contains only native methods delegating their work to the PROJ library. * For higher-level methods making use of those native methods, see for example the - * GeoAPI bindings for Proj. + * GeoAPI bindings for PROJ. * * @author Martin Desruisseaux (Geomatys) * @version 5.1 diff --git a/src/jniproj.c b/src/jniproj.c index 573dd0e7..67aa2478 100644 --- a/src/jniproj.c +++ b/src/jniproj.c @@ -1,6 +1,6 @@ /****************************************************************************** * Project: PROJ.4 - * Purpose: Java/JNI wrappers for PROJ.4 API. + * Purpose: Java/JNI wrappers for PROJ API. * Author: Antonello Andrea * Martin Desruisseaux * @@ -32,7 +32,7 @@ * \file jniproj.c * * \brief - * Functions used by the Java Native Interface (JNI) wrappers of Proj.4 + * Functions used by the Java Native Interface (JNI) wrappers of PROJ. * * * \author Antonello Andrea @@ -339,7 +339,7 @@ JNIEXPORT jdouble JNICALL Java_org_proj4_PJ_getLinearUnitToMetre * Converts input values from degrees to radians before coordinate operation, or the output * values from radians to degrees after the coordinate operation. * - * \param pj - The Proj.4 PJ structure. + * \param pj - The PROJ.4 PJ structure. * \param data - The coordinate array to transform. * \param numPts - Number of points to transform. * \param dimension - Dimension of points in the coordinate array. -- cgit v1.2.3