Merge pull request #11 from mapcode-foundation/dev-1.50

Move dev-1.50 to master

Author: rijnb

NOTICE

@@ -3,6 +3,6 @@ MAPCODE JAVA LIBRARY
 -------------------------------------------------------------------------------
 
 Original C library created by Pieter Geelen. Work on Java version
-of the Mapcode library by Rijn Buve and Matthew Lowden.
+of the Mapcode library by Rijn Buve (original port by Matthew Lowden).
 
 Copyright (C) 2014-2015 Stichting Mapcode Foundation (http://www.mapcode.com)

README.md

@@ -13,6 +13,9 @@ and to decode mapcodes back to latitude/longitude pairs.
 
 **An example of how to use this library can be found at: https://github.com/mapcode-foundation/mapcode-java-example**
 
+If you wish to use mapcodes in your own application landscape, consider using running an instance of the
+Mapcode REST API, which can be found on: **https://github.com/mapcode-foundation/mapcode-rest-service**
+
 # License
 
 Licensed under the Apache License, Version 2.0 (the "License");

pom.xml

@@ -8,7 +8,7 @@
     <artifactId>mapcode</artifactId>
 
     <packaging>jar</packaging>
-    <version>1.42.3-SNAPSHOT</version>
+    <version>1.50.0-SNAPSHOT</version>
 
     <name>Mapcode Java Library</name>
     <description>
@@ -45,7 +45,7 @@
             <name>Matthew Lowden</name>
             <organization>Mapcode</organization>
             <roles>
-                <role>Developer</role>
+                <role>Original Port</role>
             </roles>
         </developer>
     </developers>

src/main/java/com/mapcode/Alphabet.java

@@ -0,0 +1,107 @@
+/*
+ * Copyright (C) 2014-2015 Stichting Mapcode Foundation (http://www.mapcode.com)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.mapcode;
+
+import javax.annotation.Nonnull;
+
+import static com.mapcode.CheckArgs.checkNonnull;
+
+/**
+ * This enum defines all alphabets supported for mapcodes. Mapcodes can be safely converted between
+ * alphabets and fed to the mapcode decoder in the regular ASCII Roman alphabet or any other.
+ */
+public enum Alphabet {
+    ROMAN(0),
+    GREEK(1),
+    CYRILLIC(2),
+    HEBREW(3),
+    HINDI(4),
+    MALAY(5),
+    GEORGIAN(6),
+    KATAKANA(7),
+    THAI(8),
+    LAO(9),
+    ARMENIAN(10),
+    BENGALI(11),
+    GURMUKHI(12),
+    TIBETAN(13);
+
+    /**
+     * The numeric code is synonym for the alphanumeric code. It can be used in the decoder
+     * to define a territory as well.
+     */
+    private final int code;
+
+    private Alphabet(final int code) {
+        this.code = code;
+    }
+
+    public int getCode() {
+        return code;
+    }
+
+    /**
+     * Get an alphabet from a numeric code.
+     *
+     * @param code Numeric code.
+     * @return Alphabet.
+     * @throws UnknownAlphabetException Thrown if code out of range.
+     */
+    @Nonnull
+    public static Alphabet fromCode(final int code) throws UnknownAlphabetException {
+        if ((code >= 0) && (code < Alphabet.values().length)) {
+            return Alphabet.values()[code];
+        }
+        throw new UnknownAlphabetException(code);
+    }
+
+    /**
+     * Return alphabet from a string, which can be a numeric or alpha code.
+     *
+     * @param numericOrAlpha Alphabet. May be a numeric or alphanumeric code.
+     * @return Alphabet.
+     * @throws UnknownAlphabetException Thrown if incorrect numeric or alphanumeric code.
+     */
+    @Nonnull
+    public static Alphabet fromString(@Nonnull final String numericOrAlpha) throws UnknownAlphabetException {
+        checkNonnull("name", numericOrAlpha);
+        final String trimmed = numericOrAlpha.trim().toUpperCase();
+        try {
+            return fromCode(Integer.valueOf(numericOrAlpha));
+        } catch (final IllegalArgumentException ignored) {
+            // Ignore. Re-try as alpha code.
+        }
+        try {
+            return valueOf(trimmed);
+        } catch (final IllegalArgumentException ignored) {
+            throw new UnknownAlphabetException(trimmed);
+        }
+    }
+
+    /**
+     * Static checking of the static data structures.
+     */
+    static {
+        int i = 0;
+        for (final Alphabet alphabet : Alphabet.values()) {
+            if (Alphabet.values()[i].code != i) {
+                throw new ExceptionInInitializerError("Incorrect alphabet code: " + alphabet + ".code should be " + i);
+            }
+            ++i;
+        }
+    }
+}

src/main/java/com/mapcode/CheckArgs.java

@@ -19,8 +19,10 @@
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 
+import static com.mapcode.Mapcode.isValidMapcodeFormat;
+
 /**
- * Package private helper methods.
+ * Package private helper methods to check arguments for validity.
  */
 class CheckArgs {
 
@@ -42,4 +44,13 @@ static void checkNonnull(@Nonnull final String param, @Nullable final Object obj
             throw new IllegalArgumentException("Parameter " + param + " should not be null");
         }
     }
+
+    static void checkMapcodeCode(@Nonnull final String param, @Nullable final String code)
+            throws IllegalArgumentException {
+        checkNonnull(param, code);
+        if (!isValidMapcodeFormat(code)) {
+            throw new IllegalArgumentException(code + " is not a correctly formatted mapcode code; " +
+                    "the regular expression for the mapcode code syntax is: " + Mapcode.REGEX_MAPCODE);
+        }
+    }
 }

src/main/java/com/mapcode/DataAccess.java

@@ -34,7 +34,6 @@ class DataAccess {
 
     // Read data only once in static initializer.
     static {
-        boolean initialized = false;
         final InputStream inputStream = DataAccess.class.getResourceAsStream(FILE_NAME);
         try {
             final ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
@@ -45,9 +44,9 @@ class DataAccess {
             FILE_DATA = outputStream.toByteArray();
             inputStream.close();
             outputStream.close();
-            initialized = true;
         } catch (final IOException e) {
-            throw new ExceptionInInitializerError(e);
+            throw new ExceptionInInitializerError("Cannot initialize static data structure from: " + FILE_NAME +
+                    ", exception=" + e);
         } finally {
             try {
                 if (inputStream != null) {
@@ -57,9 +56,6 @@ class DataAccess {
                 // Ignore.
             }
         }
-        if (!initialized) {
-            throw new IllegalArgumentException("Cannot initialize static data structure from: " + FILE_NAME);
-        }
     }
 
     private DataAccess() {
@@ -143,8 +139,7 @@ static int smartDiv(final int i) {
             15477, 15493, 15530, 15547, 15571, 15594, 15611, 15631, 15657, 15683,
             15702, 15719, 15772, 15813, 15835, 15862, 15882, 15903, 15921, 15951,
             15977, 15997, 16018, 16036, 16054, 16073, 16089, 16105, 16133, 16159,
-            16166, 16168, 16169, 16171, 16172, 16174, 16176, 16178, 16180, 16182,
-            16183, 16184, 16216};
+            16166, 16168, 16169, 16201};
 
     // / low-level routines for data access
     static int dataFirstRecord(final int ccode) {