Refactor vCard code.

- make the usage of VCardSourceDetector.
- simplyfy flag usage.
- remove unnecessary argument "canceled"

Change-Id: I6dd9723df7230be7478f6817c0ac2e6cbedc6ca7

10 files changed, 161 insertions, 148 deletions

diff --git a/core/java/android/pim/vcard/VCardBuilder.java b/core/java/android/pim/vcard/VCardBuilder.java
index 9b8cfbb..a44f2e7 100644
--- a/core/java/android/pim/vcard/VCardBuilder.java
+++ b/core/java/android/pim/vcard/VCardBuilder.java
@@ -144,7 +144,9 @@ public class VCardBuilder {
         mAppendTypeParamName = VCardConfig.appendTypeParamName(vcardType);
         mNeedsToConvertPhoneticString = VCardConfig.needsToConvertPhoneticString(vcardType);
 
+        // TODO: remove this flag since the bit for it is actually 0.
         final boolean shouldUseUtf8 = VCardConfig.shouldUseUtf8ForExport(vcardType);
+
         final boolean shouldUseShiftJis = VCardConfig.shouldUseShiftJisForExport(vcardType);
 
         // vCard 2.1 requires charset.
diff --git a/core/java/android/pim/vcard/VCardConfig.java b/core/java/android/pim/vcard/VCardConfig.java
index 01edf93..50e63c1 100644
--- a/core/java/android/pim/vcard/VCardConfig.java
+++ b/core/java/android/pim/vcard/VCardConfig.java
@@ -38,12 +38,6 @@ public class VCardConfig {
 
     /* package */ static final int LOG_LEVEL = LOG_LEVEL_NONE;
 
-    /* package */ static final int PARSE_TYPE_UNKNOWN = 0;
-    /* package */ static final int PARSE_TYPE_APPLE = 1;
-    /* package */ static final int PARSE_TYPE_MOBILE_PHONE_JP = 2;  // For Japanese mobile phones.
-    /* package */ static final int PARSE_TYPE_FOMA = 3;  // For Japanese FOMA mobile phones.
-    /* package */ static final int PARSE_TYPE_WINDOWS_MOBILE_JP = 4;
-
     /**
      * <P>
      * The charset used during import.
@@ -80,6 +74,8 @@ public class VCardConfig {
 
     /*
      * These flags are ignored when charset is explicitly given by a caller.
+     *
+     * TODO: remove this field. DO NOT USE ANY MORE.
      */
     private static final int FLAG_USE_UTF8_FOR_EXPORT = 0;
     private static final int FLAG_USE_SHIFT_JIS_FOR_EXPORT = 0x100;
@@ -116,7 +112,7 @@ public class VCardConfig {
     private static final int FLAG_USE_DEFACT_PROPERTY = 0x40000000;
 
     /**
-     * The flag indicating some specific dialect seen in vcard of DoCoMo (one of Japanese
+     * The flag indicating some specific dialect seen in vCard of DoCoMo (one of Japanese
      * mobile careers) should be used. This flag does not include any other information like
      * that "the vCard is for Japanese". So it is "possible" that "the vCard should have DoCoMo's
      * dialect but the name order should be European", but it is not recommended.
@@ -228,24 +224,64 @@ public class VCardConfig {
      */
     public static final int FLAG_REFRAIN_PHONE_NUMBER_FORMATTING = 0x02000000;
 
+    /**
+     * <p>
+     * For importer only. Ignored in exporter.
+     * </p>
+     * <p>
+     * The flag indicating the parser should handle a nested vCard, in which vCard clause starts
+     * in another vCard clause. Here's a typical example.
+     * </p>
+     * <pre class="prettyprint">BEGIN:VCARD
+     * BEGIN:VCARD
+     * VERSION:2.1
+     * ...
+     * END:VCARD
+     * END:VCARD</pre>
+     * <p>
+     * The vCard 2.1 specification allows the nest, but also let parsers ignore nested entries,
+     * while some mobile devices emit nested ones as primary data to be imported.
+     * </p>
+     * <p>
+     * This flag forces a vCard parser to torelate such a nest and understand its content.
+     * </p>
+     */
+    public static final int FLAG_TORELATE_NEST = 0x01000000;
+
     //// The followings are VCard types available from importer/exporter. ////
 
     /**
-     * <P>
-     * Generic vCard format with the vCard 2.1. Uses UTF-8 for the charset.
-     * When composing a vCard entry, the US convension will be used toward formatting
-     * some values.
-     * </P>
-     * <P>
+     * <p>
+     * The type indicating nothing. Used by {@link VCardSourceDetector} when it
+     * was not able to guess the exact vCard type.
+     * </p>
+     */
+    public static final int VCARD_TYPE_UNKNOWN = 0;
+
+
+    /**
+     * <p>
+     * Generic vCard format with the vCard 2.1. When composing a vCard entry,
+     * the US convension will be used toward formatting some values.
+     * </p>
+     * <p>
      * e.g. The order of the display name would be "Prefix Given Middle Family Suffix",
      * while it should be "Prefix Family Middle Given Suffix" in Japan for example.
-     * </P>
+     * </p>
+     * <p>
+     * Uses UTF-8 for the charset as a charset for exporting. Note that old vCard importer
+     * outside Android cannot accept it since vCard 2.1 specifically does not allow
+     * that charset, while we need to use it to support various languages around the world.
+     * </p>
+     * <p>
+     * If you want to use alternative charset, you should notify the charset to the other
+     * compontent to be used.
+     * </p>
      */
-    public static final int VCARD_TYPE_V21_GENERIC_UTF8 =
-        (FLAG_V21 | NAME_ORDER_DEFAULT | FLAG_USE_UTF8_FOR_EXPORT |
-                FLAG_USE_DEFACT_PROPERTY | FLAG_USE_ANDROID_PROPERTY);
+    public static final int VCARD_TYPE_V21_GENERIC =
+        (FLAG_V21 | NAME_ORDER_DEFAULT | FLAG_USE_DEFACT_PROPERTY | FLAG_USE_ANDROID_PROPERTY);
 
-    /* package */ static String VCARD_TYPE_V21_GENERIC_UTF8_STR = "v21_generic";
+    /* package */ static String VCARD_TYPE_V21_GENERIC_STR = "v21_generic";
     
     /**
      * <P>
@@ -255,11 +291,10 @@ public class VCardConfig {
      * Not fully ready yet. Use with caution when you use this.
      * </P>
      */
-    public static final int VCARD_TYPE_V30_GENERIC_UTF8 =
-        (FLAG_V30 | NAME_ORDER_DEFAULT | FLAG_USE_UTF8_FOR_EXPORT |
-                FLAG_USE_DEFACT_PROPERTY | FLAG_USE_ANDROID_PROPERTY);
+    public static final int VCARD_TYPE_V30_GENERIC =
+        (FLAG_V30 | NAME_ORDER_DEFAULT | FLAG_USE_DEFACT_PROPERTY | FLAG_USE_ANDROID_PROPERTY);
 
-    /* package */ static final String VCARD_TYPE_V30_GENERIC_UTF8_STR = "v30_generic";
+    /* package */ static final String VCARD_TYPE_V30_GENERIC_STR = "v30_generic";
     
     /**
      * <P>
@@ -267,11 +302,10 @@ public class VCardConfig {
      * Currently, only name order is considered ("Prefix Middle Given Family Suffix")
      * </P>
      */
-    public static final int VCARD_TYPE_V21_EUROPE_UTF8 =
-        (FLAG_V21 | NAME_ORDER_EUROPE | FLAG_USE_UTF8_FOR_EXPORT |
-                FLAG_USE_DEFACT_PROPERTY | FLAG_USE_ANDROID_PROPERTY);
-    
-    /* package */ static final String VCARD_TYPE_V21_EUROPE_UTF8_STR = "v21_europe";
+    public static final int VCARD_TYPE_V21_EUROPE =
+        (FLAG_V21 | NAME_ORDER_EUROPE | FLAG_USE_DEFACT_PROPERTY | FLAG_USE_ANDROID_PROPERTY);
+
+    /* package */ static final String VCARD_TYPE_V21_EUROPE_STR = "v21_europe";
     
     /**
      * <P>
@@ -281,9 +315,8 @@ public class VCardConfig {
      * Not ready yet. Use with caution when you use this.
      * </P>
      */
-    public static final int VCARD_TYPE_V30_EUROPE_UTF8 =
-        (FLAG_V30 | NAME_ORDER_EUROPE | FLAG_USE_UTF8_FOR_EXPORT |
-                FLAG_USE_DEFACT_PROPERTY | FLAG_USE_ANDROID_PROPERTY);
+    public static final int VCARD_TYPE_V30_EUROPE =
+        (FLAG_V30 | NAME_ORDER_EUROPE | FLAG_USE_DEFACT_PROPERTY | FLAG_USE_ANDROID_PROPERTY);
     
     /* package */ static final String VCARD_TYPE_V30_EUROPE_STR = "v30_europe";
 
@@ -295,11 +328,10 @@ public class VCardConfig {
      * Not ready yet. Use with caution when you use this.
      * </P>
      */
-    public static final int VCARD_TYPE_V21_JAPANESE_UTF8 =
-        (FLAG_V21 | NAME_ORDER_JAPANESE | FLAG_USE_UTF8_FOR_EXPORT |
-                FLAG_USE_DEFACT_PROPERTY | FLAG_USE_ANDROID_PROPERTY);
+    public static final int VCARD_TYPE_V21_JAPANESE =
+        (FLAG_V21 | NAME_ORDER_JAPANESE | FLAG_USE_DEFACT_PROPERTY | FLAG_USE_ANDROID_PROPERTY);
 
-    /* package */ static final String VCARD_TYPE_V21_JAPANESE_UTF8_STR = "v21_japanese_utf8";
+    /* package */ static final String VCARD_TYPE_V21_JAPANESE_STR = "v21_japanese_utf8";
 
     /**
      * <P>
@@ -339,11 +371,10 @@ public class VCardConfig {
      * Not ready yet. Use with caution when you use this.
      * </P>
      */
-    public static final int VCARD_TYPE_V30_JAPANESE_UTF8 =
-        (FLAG_V30 | NAME_ORDER_JAPANESE | FLAG_USE_UTF8_FOR_EXPORT |
-                FLAG_USE_DEFACT_PROPERTY | FLAG_USE_ANDROID_PROPERTY);
+    public static final int VCARD_TYPE_V30_JAPANESE =
+        (FLAG_V30 | NAME_ORDER_JAPANESE | FLAG_USE_DEFACT_PROPERTY | FLAG_USE_ANDROID_PROPERTY);
 
-    /* package */ static final String VCARD_TYPE_V30_JAPANESE_UTF8_STR = "v30_japanese_utf8";
+    /* package */ static final String VCARD_TYPE_V30_JAPANESE_STR = "v30_japanese_utf8";
 
     /**
      * <P>
@@ -357,14 +388,13 @@ public class VCardConfig {
      */
     public static final int VCARD_TYPE_V21_JAPANESE_MOBILE =
         (FLAG_V21 | NAME_ORDER_JAPANESE | FLAG_USE_SHIFT_JIS_FOR_EXPORT |
-                FLAG_CONVERT_PHONETIC_NAME_STRINGS |
-                FLAG_REFRAIN_QP_TO_NAME_PROPERTIES);
+                FLAG_CONVERT_PHONETIC_NAME_STRINGS | FLAG_REFRAIN_QP_TO_NAME_PROPERTIES);
 
     /* package */ static final String VCARD_TYPE_V21_JAPANESE_MOBILE_STR = "v21_japanese_mobile";
 
     /**
      * <P>
-     * VCard format used in DoCoMo, which is one of Japanese mobile phone careers.
+     * The vCard format used in DoCoMo, which is one of Japanese mobile phone careers.
      * </p>
      * <P>
      * Base version is vCard 2.1, but the data has several DoCoMo-specific convensions.
@@ -377,30 +407,30 @@ public class VCardConfig {
 
     /* package */ static final String VCARD_TYPE_DOCOMO_STR = "docomo";
 
-    public static int VCARD_TYPE_DEFAULT = VCARD_TYPE_V21_GENERIC_UTF8;
+    public static int VCARD_TYPE_DEFAULT = VCARD_TYPE_V21_GENERIC;
 
     private static final Map<String, Integer> sVCardTypeMap;
     private static final Set<Integer> sJapaneseMobileTypeSet;
     
     static {
         sVCardTypeMap = new HashMap<String, Integer>();
-        sVCardTypeMap.put(VCARD_TYPE_V21_GENERIC_UTF8_STR, VCARD_TYPE_V21_GENERIC_UTF8);
-        sVCardTypeMap.put(VCARD_TYPE_V30_GENERIC_UTF8_STR, VCARD_TYPE_V30_GENERIC_UTF8);
-        sVCardTypeMap.put(VCARD_TYPE_V21_EUROPE_UTF8_STR, VCARD_TYPE_V21_EUROPE_UTF8);
-        sVCardTypeMap.put(VCARD_TYPE_V30_EUROPE_STR, VCARD_TYPE_V30_EUROPE_UTF8);
+        sVCardTypeMap.put(VCARD_TYPE_V21_GENERIC_STR, VCARD_TYPE_V21_GENERIC);
+        sVCardTypeMap.put(VCARD_TYPE_V30_GENERIC_STR, VCARD_TYPE_V30_GENERIC);
+        sVCardTypeMap.put(VCARD_TYPE_V21_EUROPE_STR, VCARD_TYPE_V21_EUROPE);
+        sVCardTypeMap.put(VCARD_TYPE_V30_EUROPE_STR, VCARD_TYPE_V30_EUROPE);
         sVCardTypeMap.put(VCARD_TYPE_V21_JAPANESE_SJIS_STR, VCARD_TYPE_V21_JAPANESE_SJIS);
-        sVCardTypeMap.put(VCARD_TYPE_V21_JAPANESE_UTF8_STR, VCARD_TYPE_V21_JAPANESE_UTF8);
+        sVCardTypeMap.put(VCARD_TYPE_V21_JAPANESE_STR, VCARD_TYPE_V21_JAPANESE);
         sVCardTypeMap.put(VCARD_TYPE_V30_JAPANESE_SJIS_STR, VCARD_TYPE_V30_JAPANESE_SJIS);
-        sVCardTypeMap.put(VCARD_TYPE_V30_JAPANESE_UTF8_STR, VCARD_TYPE_V30_JAPANESE_UTF8);
+        sVCardTypeMap.put(VCARD_TYPE_V30_JAPANESE_STR, VCARD_TYPE_V30_JAPANESE);
         sVCardTypeMap.put(VCARD_TYPE_V21_JAPANESE_MOBILE_STR, VCARD_TYPE_V21_JAPANESE_MOBILE);
         sVCardTypeMap.put(VCARD_TYPE_DOCOMO_STR, VCARD_TYPE_DOCOMO);
 
         sJapaneseMobileTypeSet = new HashSet<Integer>();
         sJapaneseMobileTypeSet.add(VCARD_TYPE_V21_JAPANESE_SJIS);
-        sJapaneseMobileTypeSet.add(VCARD_TYPE_V21_JAPANESE_UTF8);
+        sJapaneseMobileTypeSet.add(VCARD_TYPE_V21_JAPANESE);
         sJapaneseMobileTypeSet.add(VCARD_TYPE_V21_JAPANESE_SJIS);
         sJapaneseMobileTypeSet.add(VCARD_TYPE_V30_JAPANESE_SJIS);
-        sJapaneseMobileTypeSet.add(VCARD_TYPE_V30_JAPANESE_UTF8);
+        sJapaneseMobileTypeSet.add(VCARD_TYPE_V30_JAPANESE);
         sJapaneseMobileTypeSet.add(VCARD_TYPE_V21_JAPANESE_MOBILE);
         sJapaneseMobileTypeSet.add(VCARD_TYPE_DOCOMO);
     }
diff --git a/core/java/android/pim/vcard/VCardEntry.java b/core/java/android/pim/vcard/VCardEntry.java
index 7c7e9b8..5b8422f 100644
--- a/core/java/android/pim/vcard/VCardEntry.java
+++ b/core/java/android/pim/vcard/VCardEntry.java
@@ -469,7 +469,7 @@ public class VCardEntry {
     private final Account mAccount;
 
     public VCardEntry() {
-        this(VCardConfig.VCARD_TYPE_V21_GENERIC_UTF8);
+        this(VCardConfig.VCARD_TYPE_V21_GENERIC);
     }
 
     public VCardEntry(int vcardType) {
diff --git a/core/java/android/pim/vcard/VCardEntryConstructor.java b/core/java/android/pim/vcard/VCardEntryConstructor.java
index 4efb105..23bec75 100644
--- a/core/java/android/pim/vcard/VCardEntryConstructor.java
+++ b/core/java/android/pim/vcard/VCardEntryConstructor.java
@@ -62,7 +62,7 @@ public class VCardEntryConstructor implements VCardInterpreter {
     final private List<VCardEntryHandler> mEntryHandlers = new ArrayList<VCardEntryHandler>();
 
     public VCardEntryConstructor() {
-        this(null, null, false, VCardConfig.VCARD_TYPE_V21_GENERIC_UTF8, null);
+        this(null, null, false, VCardConfig.VCARD_TYPE_V21_GENERIC, null);
     }
 
     public VCardEntryConstructor(final int vcardType) {
diff --git a/core/java/android/pim/vcard/VCardParser.java b/core/java/android/pim/vcard/VCardParser.java
index 71ab5c4..e9ea251 100644
--- a/core/java/android/pim/vcard/VCardParser.java
+++ b/core/java/android/pim/vcard/VCardParser.java
@@ -57,15 +57,6 @@ public interface VCardParser {
      */
     public boolean parse(InputStream is, String charset, VCardInterpreter interpreter)
             throws IOException, VCardException;
-    
-    /**
-     * The method variants which tells this object the operation is already canceled.
-     * @hide
-     */
-    // TODO: remove this if possible.
-    public boolean parse(InputStream is, String charset,
-            VCardInterpreter builder, boolean canceled)
-        throws IOException, VCardException;
 
     /**
      * <p>
diff --git a/core/java/android/pim/vcard/VCardParserImpl_V21.java b/core/java/android/pim/vcard/VCardParserImpl_V21.java
index 22fdb75..0bd6c41 100644
--- a/core/java/android/pim/vcard/VCardParserImpl_V21.java
+++ b/core/java/android/pim/vcard/VCardParserImpl_V21.java
@@ -110,6 +110,7 @@ import java.util.Set;
     // In some cases, vCard is nested. Currently, we only consider the most
     // interior vCard data.
     // See v21_foma_1.vcf in test directory for more information.
+    // TODO: Don't ignore by using count, but read all of information outside vCard.
     private int mNestCount;
 
     // Used only for parsing END:VCARD.
@@ -129,36 +130,12 @@ import java.util.Set;
     private long mTimeHandleQuotedPrintable;
     private long mTimeHandleBase64;
 
-    /**
-     * <p>
-     * Same as {{@link #VCardParserImpl_V21(VCardSourceDetector)} with
-     * {@link VCardConfig#PARSE_TYPE_UNKNOWN}.
-     * </p>
-     */
     public VCardParserImpl_V21() {
-        this(VCardConfig.PARSE_TYPE_UNKNOWN);
+        this(VCardConfig.VCARD_TYPE_DEFAULT);
     }
 
-    /**
-     * <p>
-     * The constructor which uses the estimated type available from a given detector.
-     * </p>
-     */
-    public VCardParserImpl_V21(VCardSourceDetector detector) {
-        this(detector != null ? detector.getEstimatedType() : VCardConfig.PARSE_TYPE_UNKNOWN);
-    }
-
-    /**
-     * <p>
-     * The constructor which uses a given parse type like
-     * {@link VCardConfig#PARSE_TYPE_UNKNOWN}.
-     * </p>
-     * <p>
-     * This should be used only when you already know the exact type to be used.
-     * </p>
-     */
-    public VCardParserImpl_V21(int parseType) {
-        if (parseType == VCardConfig.PARSE_TYPE_FOMA) {
+    public VCardParserImpl_V21(int vcardType) {
+        if ((vcardType & VCardConfig.FLAG_TORELATE_NEST) != 0) {
             mNestCount = 1;
         }
     }
@@ -170,15 +147,15 @@ import java.util.Set;
      */
     // <pre class="prettyprint">vcard_file = [wsls] vcard [wsls]</pre>
     protected void parseVCardFile() throws IOException, VCardException {
-        boolean firstRead = true;
+        boolean readingFirstFile = true;
         while (true) {
             if (mCanceled) {
                 break;
             }
-            if (!parseOneVCard(firstRead)) {
+            if (!parseOneVCard(readingFirstFile)) {
                 break;
             }
-            firstRead = false;
+            readingFirstFile = false;
         }
 
         if (mNestCount > 0) {
@@ -943,16 +920,17 @@ import java.util.Set;
     }
 
 
-    public boolean parse(InputStream is, String inputCharset, VCardInterpreter interpreter)
+    public boolean parse(InputStream is, String charset, VCardInterpreter interpreter)
             throws IOException, VCardException {
         if (is == null) {
             throw new NullPointerException("InputStream must not be null.");
         }
-        if (inputCharset == null) {
-            inputCharset = VCardConfig.DEFAULT_TEMPORARY_CHARSET;
+
+        if (charset == null) {
+            charset = VCardConfig.DEFAULT_TEMPORARY_CHARSET;
         }
 
-        final InputStreamReader tmpReader = new InputStreamReader(is, inputCharset);
+        final InputStreamReader tmpReader = new InputStreamReader(is, charset);
         if (VCardConfig.showPerformanceLog()) {
             mReader = new CustomBufferedReader(tmpReader);
         } else {
@@ -961,7 +939,7 @@ import java.util.Set;
 
         mInterpreter = interpreter;
 
-        long start = System.currentTimeMillis();
+        final long start = System.currentTimeMillis();
         if (mInterpreter != null) {
             mInterpreter.start();
         }
@@ -978,13 +956,6 @@ import java.util.Set;
         return true;
     }
 
-    public boolean parse(InputStream is, String charset,
-            VCardInterpreter builder, boolean canceled)
-            throws IOException, VCardException {
-        mCanceled = canceled;
-        return parse(is, charset, builder);
-    }
-
     public final void cancel() {
         mCanceled = true;
     }
diff --git a/core/java/android/pim/vcard/VCardParserImpl_V30.java b/core/java/android/pim/vcard/VCardParserImpl_V30.java
index fb6ee4f..250866b 100644
--- a/core/java/android/pim/vcard/VCardParserImpl_V30.java
+++ b/core/java/android/pim/vcard/VCardParserImpl_V30.java
@@ -43,10 +43,6 @@ import android.util.Log;
         super();
     }
 
-    public VCardParserImpl_V30(VCardSourceDetector detector) {
-        this(detector != null ? detector.getEstimatedType() : VCardConfig.PARSE_TYPE_UNKNOWN);
-    }
-
     public VCardParserImpl_V30(int parseMode) {
         super(parseMode);
     }
diff --git a/core/java/android/pim/vcard/VCardParser_V21.java b/core/java/android/pim/vcard/VCardParser_V21.java
index f7e496a..a545394 100644
--- a/core/java/android/pim/vcard/VCardParser_V21.java
+++ b/core/java/android/pim/vcard/VCardParser_V21.java
@@ -94,10 +94,6 @@ public final class VCardParser_V21 implements VCardParser {
         mVCardParserImpl = new VCardParserImpl_V21();
     }
 
-    public VCardParser_V21(VCardSourceDetector detector) {
-        mVCardParserImpl = new VCardParserImpl_V21(detector);
-    }
-
     public VCardParser_V21(int parseType) {
         mVCardParserImpl = new VCardParserImpl_V21(parseType);
     }
@@ -114,12 +110,6 @@ public final class VCardParser_V21 implements VCardParser {
         return mVCardParserImpl.parse(is, charset, interpreter);
     }
 
-    public boolean parse(InputStream is, String charset,
-            VCardInterpreter interpreter, boolean canceled)
-            throws IOException, VCardException {
-        return mVCardParserImpl.parse(is, charset, interpreter, canceled);
-    }
-
     public void cancel() {
         mVCardParserImpl.cancel();
     }
diff --git a/core/java/android/pim/vcard/VCardParser_V30.java b/core/java/android/pim/vcard/VCardParser_V30.java
index 13b4196..d6d9bb4d 100644
--- a/core/java/android/pim/vcard/VCardParser_V30.java
+++ b/core/java/android/pim/vcard/VCardParser_V30.java
@@ -72,10 +72,6 @@ public class VCardParser_V30 implements VCardParser {
         mVCardParserImpl = new VCardParserImpl_V30();
     }
 
-    public VCardParser_V30(VCardSourceDetector detector) {
-        mVCardParserImpl = new VCardParserImpl_V30(detector);
-    }
-
     public VCardParser_V30(int parseType) {
         mVCardParserImpl = new VCardParserImpl_V30(parseType);
     }
@@ -92,12 +88,6 @@ public class VCardParser_V30 implements VCardParser {
         return mVCardParserImpl.parse(is, charset, interpreter);
     }
 
-    public boolean parse(InputStream is, String charset,
-            VCardInterpreter interpreter, boolean canceled)
-            throws IOException, VCardException {
-        return mVCardParserImpl.parse(is, charset, interpreter, canceled);
-    }
-
     public void cancel() {
         mVCardParserImpl.cancel();
     }
diff --git a/core/java/android/pim/vcard/VCardSourceDetector.java b/core/java/android/pim/vcard/VCardSourceDetector.java
index 7297c50..291deca 100644
--- a/core/java/android/pim/vcard/VCardSourceDetector.java
+++ b/core/java/android/pim/vcard/VCardSourceDetector.java
@@ -15,15 +15,28 @@
  */
 package android.pim.vcard;
 
+import android.text.TextUtils;
+
 import java.util.Arrays;
 import java.util.HashSet;
 import java.util.List;
 import java.util.Set;
 
 /**
- * Class which tries to detects the source of the vCard from its properties.
- * Currently this implementation is very premature.
- * @hide
+ * <p>
+ * The class which tries to detects the source of a vCard file from its contents.
+ * </p>
+ * <p>
+ * The specification of vCard (including both 2.1 and 3.0) is not so strict as to
+ * guess its format just by reading beginning few lines (usually we can, but in
+ * some most pessimistic case, we cannot until at almost the end of the file).
+ * Also we cannot store all vCard entries in memory, while there's no specification
+ * how big the vCard entry would become after the parse.
+ * </p>
+ * <p>
+ * This class is usually used for the "first scan", in which we can understand which vCard
+ * version is used (and how many entries exist in a file).
+ * </p>
  */
 public class VCardSourceDetector implements VCardInterpreter {
     private static Set<String> APPLE_SIGNS = new HashSet<String>(Arrays.asList(
@@ -42,8 +55,22 @@ public class VCardSourceDetector implements VCardInterpreter {
             "X-SD-VERN", "X-SD-FORMAT_VER", "X-SD-CATEGORIES", "X-SD-CLASS", "X-SD-DCREATED",
             "X-SD-DESCRIPTION"));
     private static String TYPE_FOMA_CHARSET_SIGN = "X-SD-CHAR_CODE";
-    
-    private int mType = VCardConfig.PARSE_TYPE_UNKNOWN;
+
+
+    // TODO: Should replace this with types in VCardConfig
+    private static final int PARSE_TYPE_UNKNOWN = 0;
+    // For Apple's software, which does not mean this type is effective for all its products.
+    // We confirmed they usually use UTF-8, but not sure about vCard type.
+    private static final int PARSE_TYPE_APPLE = 1;
+    // For Japanese mobile phones, which are usually using Shift_JIS as a charset.
+    private static final int PARSE_TYPE_MOBILE_PHONE_JP = 2;
+    // For some of mobile phones released from DoCoMo, which use nested vCard. 
+    private static final int PARSE_TYPE_DOCOMO_TORELATE_NEST = 3;
+    // For Japanese Windows Mobel phones. It's version is supposed to be 6.5.
+    private static final int PARSE_TYPE_WINDOWS_MOBILE_V65_JP = 4;
+
+    private int mParseType = 0;  // Not sure.
+
     // Some mobile phones (like FOMA) tells us the charset of the data.
     private boolean mNeedParseSpecifiedCharset;
     private String mSpecifiedCharset;
@@ -72,21 +99,22 @@ public class VCardSourceDetector implements VCardInterpreter {
     
     public void propertyName(String name) {
         if (name.equalsIgnoreCase(TYPE_FOMA_CHARSET_SIGN)) {
-            mType = VCardConfig.PARSE_TYPE_FOMA;
+            mParseType = PARSE_TYPE_DOCOMO_TORELATE_NEST;
+            // Probably Shift_JIS is used, but we should double confirm.
             mNeedParseSpecifiedCharset = true;
             return;
         }
-        if (mType != VCardConfig.PARSE_TYPE_UNKNOWN) {
+        if (mParseType != PARSE_TYPE_UNKNOWN) {
             return;
         }
         if (WINDOWS_MOBILE_PHONE_SIGNS.contains(name)) {
-            mType = VCardConfig.PARSE_TYPE_WINDOWS_MOBILE_JP;
+            mParseType = PARSE_TYPE_WINDOWS_MOBILE_V65_JP;
         } else if (FOMA_SIGNS.contains(name)) {
-            mType = VCardConfig.PARSE_TYPE_FOMA;
+            mParseType = PARSE_TYPE_DOCOMO_TORELATE_NEST;
         } else if (JAPANESE_MOBILE_PHONE_SIGNS.contains(name)) {
-            mType = VCardConfig.PARSE_TYPE_MOBILE_PHONE_JP;
+            mParseType = PARSE_TYPE_MOBILE_PHONE_JP;
         } else if (APPLE_SIGNS.contains(name)) {
-            mType = VCardConfig.PARSE_TYPE_APPLE;
+            mParseType = PARSE_TYPE_APPLE;
         }
     }
 
@@ -102,25 +130,40 @@ public class VCardSourceDetector implements VCardInterpreter {
         }
     }
 
-    /* package */ int getEstimatedType() {
-        return mType;
+    /**
+     * @return The available type can be used with vCard parser. You probably need to
+     * use {{@link #getEstimatedCharset()} to understand the charset to be used.
+     */
+    public int getEstimatedType() {
+        switch (mParseType) {
+            case PARSE_TYPE_DOCOMO_TORELATE_NEST:
+                return VCardConfig.VCARD_TYPE_DOCOMO | VCardConfig.FLAG_TORELATE_NEST;
+            case PARSE_TYPE_MOBILE_PHONE_JP:
+                return VCardConfig.VCARD_TYPE_V21_JAPANESE_MOBILE;
+            case PARSE_TYPE_APPLE:
+            case PARSE_TYPE_WINDOWS_MOBILE_V65_JP:
+            default:
+                return VCardConfig.VCARD_TYPE_UNKNOWN;
+        }
     }
-    
+
     /**
-     * Return charset String guessed from the source's properties.
+     * <p>
+     * Returns charset String guessed from the source's properties.
      * This method must be called after parsing target file(s).
+     * </p>
      * @return Charset String. Null is returned if guessing the source fails.
      */
     public String getEstimatedCharset() {
-        if (mSpecifiedCharset != null) {
+        if (TextUtils.isEmpty(mSpecifiedCharset)) {
             return mSpecifiedCharset;
         }
-        switch (mType) {
-            case VCardConfig.PARSE_TYPE_WINDOWS_MOBILE_JP:
-            case VCardConfig.PARSE_TYPE_FOMA:
-            case VCardConfig.PARSE_TYPE_MOBILE_PHONE_JP:
+        switch (mParseType) {
+            case PARSE_TYPE_WINDOWS_MOBILE_V65_JP:
+            case PARSE_TYPE_DOCOMO_TORELATE_NEST:
+            case PARSE_TYPE_MOBILE_PHONE_JP:
                 return "SHIFT_JIS";
-            case VCardConfig.PARSE_TYPE_APPLE:
+            case PARSE_TYPE_APPLE:
                 return "UTF-8";
             default:
                 return null;