JAVA: Added carrier mapper including unittests, rules for building the binary data

files and carrier mapping files.

java/build.xml

@@ -3,6 +3,8 @@
 <project name="libphonenumber" default="compile">
   <property name="libphonenumber.src.dir" value="libphonenumber/src"/>
   <property name="libphonenumber.test.dir" value="libphonenumber/test"/>
+  <property name="carrier.src.dir" value="carrier/src"/>
+  <property name="carrier.test.dir" value="carrier/test"/>
   <property name="geocoder.src.dir" value="geocoder/src"/>
   <property name="geocoder.test.dir" value="geocoder/test"/>
   <property name="prefixmapper.src.dir" value="internal/prefixmapper/src"/>
@@ -85,6 +87,26 @@
     </exec>
   </target>
 
+  <target name="build-carrier-data">
+    <exec executable="java">
+      <arg value="-jar" />
+      <arg value="${build.tools.jar}"/>
+      <arg value="GeneratePhonePrefixData"/>
+      <arg value="${resources.dir}/carrier/"/>
+      <arg value="carrier/src/com/google/i18n/phonenumbers/carrier/data"/>
+    </exec>
+  </target>
+
+  <target name="build-carrier-test-data">
+    <exec executable="java">
+      <arg value="-jar" />
+      <arg value="${build.tools.jar}"/>
+      <arg value="GeneratePhonePrefixData"/>
+      <arg value="${resources.dir}/test/carrier/"/>
+      <arg value="carrier/test/com/google/i18n/phonenumbers/carrier/testing_data"/>
+    </exec>
+  </target>
+
   <target name="build-geo-data">
     <exec executable="java">
       <arg value="-jar" />
@@ -131,11 +153,11 @@
   </target>
 
   <target name="compile" description="Compile Java source."
-          depends="build-phone-metadata,build-short-metadata,build-alternate-metadata,build-geo-data">
+          depends="build-phone-metadata,build-short-metadata,build-alternate-metadata,build-carrier-data,build-geo-data">
     <mkdir dir="${classes.dir}"/>
-    <javac srcdir="${libphonenumber.src.dir};${geocoder.src.dir};${prefixmapper.src.dir}"
+    <javac srcdir="${libphonenumber.src.dir};${carrier.src.dir};${geocoder.src.dir};${prefixmapper.src.dir}"
            destdir="${classes.dir}" classpathref="classpath" includeAntRuntime="false"/>
-    <javac srcdir="${libphonenumber.test.dir};${geocoder.test.dir};${prefixmapper.test.dir}"
+    <javac srcdir="${libphonenumber.test.dir};${carrier.test.dir};${geocoder.test.dir};${prefixmapper.test.dir}"
            destdir="${classes.dir}" classpathref="classpath" debug="on"
            includeAntRuntime="false"/>
   </target>
@@ -147,6 +169,7 @@
         <include name="**/*.class"/>
         <exclude name="**/*Test*"/>
         <exclude name="**/BuildMetadata*"/>
+        <exclude name="**/PhoneNumberToCarrierMapper*"/>
         <exclude name="**/geocoding/*"/>
         <exclude name="**/prefixmapper/*"/>
       </fileset>
@@ -156,6 +179,16 @@
         <include name="**/ShortNumberMetadataProto*"/>
       </fileset>
     </jar>
+    <jar destfile="${jar.dir}/carrier-mapper.jar">
+      <fileset dir="${classes.dir}">
+        <include name="**/PhoneNumberToCarrierMapper.class"/>
+        <include name="**/prefixmapper/*.class"/>
+        <exclude name="**/*Test*"/>
+      </fileset>
+      <fileset dir="${carrier.src.dir}">
+        <include name="**/carrier/data/*"/>
+      </fileset>
+    </jar>
     <jar destfile="${jar.dir}/offline-geocoder.jar">
       <fileset dir="${classes.dir}">
         <include name="**/geocoding/*.class"/>
@@ -169,7 +202,7 @@
   </target>
 
   <target name="test-jar"
-          depends="compile,build-test-metadata,build-geo-test-data">
+          depends="compile,build-test-metadata,build-carrier-test-data,build-geo-test-data">
     <mkdir dir="${jar.dir}"/>
     <jar destfile="${jar.dir}/${ant.project.name}-test.jar">
       <fileset dir="${classes.dir}">
@@ -184,6 +217,9 @@
       <fileset dir="${libphonenumber.test.dir}">
         <include name="**/PhoneNumberMetadataProtoForTesting*"/>
       </fileset>
+      <fileset dir="${carrier.test.dir}">
+        <include name="**/carrier/testing_data/*"/>
+      </fileset>
       <fileset dir="${geocoder.test.dir}">
         <include name="**/geocoding/testing_data/*"/>
       </fileset>
@@ -199,6 +235,9 @@
       <batchtest fork="no" todir="${report.dir}">
         <fileset dir="${libphonenumber.test.dir}" includes="**/*Test.java"/>
       </batchtest>
+      <batchtest fork="no" todir="${report.dir}">
+        <fileset dir="${carrier.test.dir}" includes="**/*Test.java"/>
+      </batchtest>
       <batchtest fork="no" todir="${report.dir}">
         <fileset dir="${geocoder.test.dir}" includes="**/*Test.java"/>
       </batchtest>
@@ -227,6 +266,7 @@
       <formatter type="plain" usefile="false"/>
       <batchtest fork="no">
         <fileset dir="${libphonenumber.test.dir}" includes="**/*${test}.java"/>
+        <fileset dir="${carrier.test.dir}" includes="**/*${test}.java"/>
         <fileset dir="${geocoder.test.dir}" includes="**/*${test}.java"/>
       </batchtest>
     </junit>

java/carrier/pom.xml

@@ -0,0 +1,46 @@
+<?xml version="1.0"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <groupId>com.googlecode.libphonenumber</groupId>
+  <artifactId>carrier</artifactId>
+  <version>1.0-SNAPSHOT</version>
+  <packaging>jar</packaging>
+  <url>http://code.google.com/p/libphonenumber/</url>
+
+  <parent>
+    <groupId>com.googlecode.libphonenumber</groupId>
+    <artifactId>libphonenumber-parent</artifactId>
+    <version>5.9-SNAPSHOT</version>
+  </parent>
+
+  <build>
+    <sourceDirectory>src</sourceDirectory>
+    <testSourceDirectory>test</testSourceDirectory>
+    <resources>
+      <resource>
+        <directory>src/com/google/i18n/phonenumbers/carrier/data</directory>
+        <targetPath>com/google/i18n/phonenumbers/carrier/data</targetPath>
+      </resource>
+    </resources>
+    <testResources>
+      <testResource>
+        <directory>test/com/google/i18n/phonenumbers/carrier/testing_data</directory>
+        <targetPath>com/google/i18n/phonenumbers/carrier/testing_data</targetPath>
+      </testResource>
+    </testResources>
+  </build>
+
+  <dependencies>
+    <dependency>
+      <groupId>com.googlecode.libphonenumber</groupId>
+      <artifactId>libphonenumber</artifactId>
+      <version>5.9-SNAPSHOT</version>
+    </dependency>
+    <dependency>
+      <groupId>com.googlecode.libphonenumber</groupId>
+      <artifactId>prefixmapper</artifactId>
+      <version>2.10-SNAPSHOT</version>
+    </dependency>
+  </dependencies>
+
+</project>

java/carrier/src/com/google/i18n/phonenumbers/PhoneNumberToCarrierMapper.java

@@ -0,0 +1,106 @@
+/*
+ * Copyright (C) 2013 The Libphonenumber Authors
+ *
+ * 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.google.i18n.phonenumbers;
+
+import com.google.i18n.phonenumbers.PhoneNumberUtil;
+import com.google.i18n.phonenumbers.PhoneNumberUtil.PhoneNumberType;
+import com.google.i18n.phonenumbers.Phonenumber.PhoneNumber;
+import com.google.i18n.phonenumbers.prefixmapper.PrefixFileReader;
+
+import java.util.Locale;
+
+/**
+ * A phone prefix mapper which provides carrier information related to a phone number.
+ *
+ * @author Cecilia Roes
+ */
+public class PhoneNumberToCarrierMapper {
+  private static PhoneNumberToCarrierMapper instance = null;
+  private static final String MAPPING_DATA_DIRECTORY =
+      "/com/google/i18n/phonenumbers/carrier/data/";
+  private PrefixFileReader prefixFileReader = null;
+
+  private final PhoneNumberUtil phoneUtil = PhoneNumberUtil.getInstance();
+
+  // @VisibleForTesting
+  PhoneNumberToCarrierMapper(String phonePrefixDataDirectory) {
+    prefixFileReader = new PrefixFileReader(phonePrefixDataDirectory);
+  }
+
+  /**
+   * Gets a {@link PhoneNumberToCarrierMapper} instance to carry out international carrier lookup.
+   *
+   * <p> The {@link PhoneNumberToCarrierMapper} is implemented as a singleton. Therefore, calling
+   * this method multiple times will only result in one instance being created.
+   *
+   * @return  a {@link PhoneNumberToCarrierMapper} instance
+   */
+  public static synchronized PhoneNumberToCarrierMapper getInstance() {
+    if (instance == null) {
+      instance = new PhoneNumberToCarrierMapper(MAPPING_DATA_DIRECTORY);
+    }
+    return instance;
+  }
+
+  /**
+   * Returns a text description for the given phone number, in the language provided. The
+   * description consists of the name of the carrier the number was originally allocated to, however
+   * if the country supports mobile number portability the number might not belong to the returned
+   * carrier anymore. If no mapping is found an empty string is returned.
+   *
+   * <p>This method assumes the validity of the number passed in has already been checked, and that
+   * the number is suitable for carrier lookup. We consider mobile and pager numbers possible
+   * candidates for carrier lookup.
+   *
+   * @param number  a valid phone number for which we want to get a text description
+   * @param languageCode  the language code for which the description should be written
+   * @return  a text description for the given language code for the given phone number
+   */
+  public String getDescriptionForValidNumber(PhoneNumber number, Locale languageCode) {
+    String langStr = languageCode.getLanguage();
+    String scriptStr = "";  // No script is specified
+    String regionStr = languageCode.getCountry();
+
+    return prefixFileReader.getDescriptionForNumber(number, langStr, scriptStr, regionStr);
+  }
+
+  /**
+   * As per {@link #getDescriptionForValidNumber(PhoneNumber, Locale)} but explicitly checks
+   * the validity of the number passed in.
+   *
+   * @param number  the phone number for which we want to get a text description
+   * @param languageCode  the language code for which the description should be written
+   * @return  a text description for the given language code for the given phone number, or empty
+   *     string if the number passed in is invalid
+   */
+  public String getDescriptionForNumber(PhoneNumber number, Locale languageCode) {
+    PhoneNumberType numberType = phoneUtil.getNumberType(number);
+    if (isMobile(numberType)) {
+      return getDescriptionForValidNumber(number, languageCode);
+    }
+    return "";
+  }
+
+  /**
+   * Checks if the supplied number type supports carrier lookup.
+   */
+  private boolean isMobile(PhoneNumberType numberType) {
+    return (numberType == PhoneNumberType.MOBILE ||
+            numberType == PhoneNumberType.FIXED_LINE_OR_MOBILE ||
+            numberType == PhoneNumberType.PAGER);
+  }
+}