a_vcard.android.syncml.pim.vcard
Class VCardParser_V21

java.lang.Object
  extended by a_vcard.android.syncml.pim.vcard.VCardParser_V21
Direct Known Subclasses:
VCardParser_V30

public class VCardParser_V21
extends java.lang.Object

This class is used to parse vcard. Please refer to vCard Specification 2.1.


Field Summary
static java.lang.String DEFAULT_CHARSET
           
protected  VBuilder mBuilder
          The builder to build parsed data
protected  java.lang.String mEncoding
          The encoding type
protected  java.io.BufferedReader mReader
           
protected  java.util.HashSet<java.lang.String> mWarningValueMap
           
protected  java.lang.String sDefaultEncoding
           
 
Constructor Summary
VCardParser_V21()
          Create a new VCard parser.
VCardParser_V21(VCardSourceDetector detector)
           
 
Method Summary
 void cancel()
          Cancel parsing.
protected  java.lang.String getBase64(java.lang.String firstString)
           
protected  java.lang.String getLine()
           
protected  java.lang.String getNonEmptyLine()
           
protected  java.lang.String getQuotedPrintable(java.lang.String firstString)
           
protected  java.lang.String getVersion()
           
protected  void handleAgent(java.lang.String propertyValue)
          vCard 2.1 specifies AGENT allows one vcard entry.
protected  void handleAnyParam(java.lang.String paramName, java.lang.String paramValue)
          Mainly for "X-" type.
protected  void handleCharset(java.lang.String charsetval)
          vCard specification only allows us-ascii and iso-8859-xxx (See RFC 1521), but some vCard contains other charset, so we allow them.
protected  void handleEncoding(java.lang.String pencodingval)
          pencodingval = "7BIT" / "8BIT" / "QUOTED-PRINTABLE" / "BASE64" / "X-" word
protected  void handleLanguage(java.lang.String langval)
          See also Section 7.1 of RFC 1521
protected  void handleMultiplePropertyValue(java.lang.String propertyName, java.lang.String propertyValue)
          Mainly for "ADR", "ORG", and "N" We do not care the number of strnosemi here.
protected  void handleParams(java.lang.String params)
          params = ";" [ws] paramlist paramlist = paramlist [ws] ";" [ws] param / param param = "TYPE" [ws] "=" [ws] ptypeval / "VALUE" [ws] "=" [ws] pvalueval / "ENCODING" [ws] "=" [ws] pencodingval / "CHARSET" [ws] "=" [ws] charsetval / "LANGUAGE" [ws] "=" [ws] langval / "X-" word [ws] "=" [ws] word / knowntype
protected  void handlePropertyValue(java.lang.String propertyName, java.lang.String propertyValue)
           
protected  void handleType(java.lang.String ptypeval)
          ptypeval = knowntype / "X-" word
protected  void handleValue(java.lang.String pvalueval)
          pvalueval = "INLINE" / "URL" / "CONTENT-ID" / "CID" / "X-" word
protected  boolean isValidEncoding(java.lang.String encoding)
           
protected  boolean isValidPropertyName(java.lang.String propertyName)
           
protected  java.lang.String maybeUnescape(char ch)
          Returns unescaped String if the character should be unescaped.
protected  java.lang.String maybeUnescapeText(java.lang.String text)
          For vCard 3.0.
 boolean parse(java.io.InputStream is, java.lang.String charset, VBuilder builder)
          Parse the given stream and constructs VCardDataBuilder object.
 void parse(java.io.InputStream is, java.lang.String charset, VBuilder builder, boolean canceled)
          It is very, very rare case, but there is a case where canceled may be already true outside this object.
 boolean parse(java.io.InputStream is, VBuilder builder)
           
protected  boolean parseItem()
          item = [groups "."] name [params] ":" value CRLF / [groups "."] "ADR" [params] ":" addressparts CRLF / [groups "."] "ORG" [params] ":" orgparts CRLF / [groups "."] "N" [params] ":" nameparts CRLF / [groups "."] "AGENT" [params] ":" vcard CRLF
protected  void parseItems()
          items = *CRLF item / item
protected  void parseVCardFile()
          Parse the file at the given position vcard_file = [wsls] vcard [wsls]
protected  boolean readBeginVCard(boolean allowGarbage)
           
protected  void readEndVCard(boolean useCache, boolean allowGarbage)
          The arguments useCache and allowGarbase are usually true and false accordingly when this function is called outside this function itself.
protected  java.lang.String[] separateLineAndHandleGroup(java.lang.String line)
           
 void showDebugInfo()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_CHARSET

public static final java.lang.String DEFAULT_CHARSET
See Also:
Constant Field Values

mBuilder

protected VBuilder mBuilder
The builder to build parsed data


mEncoding

protected java.lang.String mEncoding
The encoding type


sDefaultEncoding

protected final java.lang.String sDefaultEncoding
See Also:
Constant Field Values

mReader

protected java.io.BufferedReader mReader

mWarningValueMap

protected java.util.HashSet<java.lang.String> mWarningValueMap
Constructor Detail

VCardParser_V21

public VCardParser_V21()
Create a new VCard parser.


VCardParser_V21

public VCardParser_V21(VCardSourceDetector detector)
Method Detail

parseVCardFile

protected void parseVCardFile()
                       throws java.io.IOException,
                              VCardException
Parse the file at the given position vcard_file = [wsls] vcard [wsls]

Throws:
java.io.IOException
VCardException

getVersion

protected java.lang.String getVersion()

isValidPropertyName

protected boolean isValidPropertyName(java.lang.String propertyName)
Returns:
true when the propertyName is a valid property name.

isValidEncoding

protected boolean isValidEncoding(java.lang.String encoding)
Returns:
true when the encoding is a valid encoding.

getLine

protected java.lang.String getLine()
                            throws java.io.IOException
Returns:
String. It may be null, or its length may be 0
Throws:
java.io.IOException

getNonEmptyLine

protected java.lang.String getNonEmptyLine()
                                    throws java.io.IOException,
                                           VCardException
Returns:
String with it's length > 0
Throws:
java.io.IOException
VCardException - when the stream reached end of line

readBeginVCard

protected boolean readBeginVCard(boolean allowGarbage)
                          throws java.io.IOException,
                                 VCardException
Returns:
True when successful. False when reaching the end of line
Throws:
java.io.IOException
VCardException

readEndVCard

protected void readEndVCard(boolean useCache,
                            boolean allowGarbage)
                     throws java.io.IOException,
                            VCardException
The arguments useCache and allowGarbase are usually true and false accordingly when this function is called outside this function itself.

Parameters:
useCache - When true, line is obtained from mPreviousline. Otherwise, getLine() is used.
allowGarbage - When true, ignore non "END:VCARD" line.
Throws:
java.io.IOException
VCardException

parseItems

protected void parseItems()
                   throws java.io.IOException,
                          VCardException
items = *CRLF item / item

Throws:
java.io.IOException
VCardException

parseItem

protected boolean parseItem()
                     throws java.io.IOException,
                            VCardException
item = [groups "."] name [params] ":" value CRLF / [groups "."] "ADR" [params] ":" addressparts CRLF / [groups "."] "ORG" [params] ":" orgparts CRLF / [groups "."] "N" [params] ":" nameparts CRLF / [groups "."] "AGENT" [params] ":" vcard CRLF

Throws:
java.io.IOException
VCardException

separateLineAndHandleGroup

protected java.lang.String[] separateLineAndHandleGroup(java.lang.String line)
                                                 throws VCardException
Throws:
VCardException

handleParams

protected void handleParams(java.lang.String params)
                     throws VCardException
params = ";" [ws] paramlist paramlist = paramlist [ws] ";" [ws] param / param param = "TYPE" [ws] "=" [ws] ptypeval / "VALUE" [ws] "=" [ws] pvalueval / "ENCODING" [ws] "=" [ws] pencodingval / "CHARSET" [ws] "=" [ws] charsetval / "LANGUAGE" [ws] "=" [ws] langval / "X-" word [ws] "=" [ws] word / knowntype

Throws:
VCardException

handleType

protected void handleType(java.lang.String ptypeval)
ptypeval = knowntype / "X-" word


handleValue

protected void handleValue(java.lang.String pvalueval)
                    throws VCardException
pvalueval = "INLINE" / "URL" / "CONTENT-ID" / "CID" / "X-" word

Throws:
VCardException

handleEncoding

protected void handleEncoding(java.lang.String pencodingval)
                       throws VCardException
pencodingval = "7BIT" / "8BIT" / "QUOTED-PRINTABLE" / "BASE64" / "X-" word

Throws:
VCardException

handleCharset

protected void handleCharset(java.lang.String charsetval)
vCard specification only allows us-ascii and iso-8859-xxx (See RFC 1521), but some vCard contains other charset, so we allow them.


handleLanguage

protected void handleLanguage(java.lang.String langval)
                       throws VCardException
See also Section 7.1 of RFC 1521

Throws:
VCardException

handleAnyParam

protected void handleAnyParam(java.lang.String paramName,
                              java.lang.String paramValue)
Mainly for "X-" type. This accepts any kind of type without check.


handlePropertyValue

protected void handlePropertyValue(java.lang.String propertyName,
                                   java.lang.String propertyValue)
                            throws java.io.IOException,
                                   VCardException
Throws:
java.io.IOException
VCardException

getQuotedPrintable

protected java.lang.String getQuotedPrintable(java.lang.String firstString)
                                       throws java.io.IOException,
                                              VCardException
Throws:
java.io.IOException
VCardException

getBase64

protected java.lang.String getBase64(java.lang.String firstString)
                              throws java.io.IOException,
                                     VCardException
Throws:
java.io.IOException
VCardException

handleMultiplePropertyValue

protected void handleMultiplePropertyValue(java.lang.String propertyName,
                                           java.lang.String propertyValue)
                                    throws java.io.IOException,
                                           VCardException
Mainly for "ADR", "ORG", and "N" We do not care the number of strnosemi here. addressparts = 0*6(strnosemi ";") strnosemi ; PO Box, Extended Addr, Street, Locality, Region, Postal Code, Country Name orgparts = *(strnosemi ";") strnosemi ; First is Organization Name, remainder are Organization Units. nameparts = 0*4(strnosemi ";") strnosemi ; Family, Given, Middle, Prefix, Suffix. ; Example:Public;John;Q.;Reverend Dr.;III, Esq. strnosemi = *(*nonsemi ("\;" / "\" CRLF)) *nonsemi ; To include a semicolon in this string, it must be escaped ; with a "\" character. We are not sure whether we should add "\" CRLF to each value. For now, we exclude them.

Throws:
java.io.IOException
VCardException

handleAgent

protected void handleAgent(java.lang.String propertyValue)
                    throws VCardException
vCard 2.1 specifies AGENT allows one vcard entry. It is not encoded at all. item = ... / [groups "."] "AGENT" [params] ":" vcard CRLF vcard = "BEGIN" [ws] ":" [ws] "VCARD" [ws] 1*CRLF items *CRLF "END" [ws] ":" [ws] "VCARD"

Throws:
VCardException

maybeUnescapeText

protected java.lang.String maybeUnescapeText(java.lang.String text)
For vCard 3.0.


maybeUnescape

protected java.lang.String maybeUnescape(char ch)
Returns unescaped String if the character should be unescaped. Return null otherwise. e.g. In vCard 2.1, "\;" should be unescaped into ";" while "\x" should not be.


parse

public boolean parse(java.io.InputStream is,
                     java.lang.String charset,
                     VBuilder builder)
              throws java.io.IOException,
                     VCardException
Parse the given stream and constructs VCardDataBuilder object. Note that vCard 2.1 specification allows "CHARSET" parameter, and some career sets local encoding to it. For example, Japanese phone career uses Shift_JIS, which is not formally allowed in vCard specification. As a result, there is a case where the encoding given here does not do well with the "CHARSET". In order to avoid such cases, It may be fine to use "ISO-8859-1" as an encoding, and to encode each localized String afterward. RFC 2426 "recommends" (not forces) to use UTF-8, so it may be OK to use UTF-8 as an encoding when parsing vCard 3.0. But note that some Japanese phone uses Shift_JIS as a charset (e.g. W61SH), and another uses "CHARSET=SHIFT_JIS", which is explicitly prohibited in vCard 3.0 specification (e.g. W53K).

Parameters:
is - The source to parse.
charset - The charset.
builder - The v builder which used to construct data.
Returns:
Return true for success, otherwise false.
Throws:
java.io.IOException
VCardException

parse

public boolean parse(java.io.InputStream is,
                     VBuilder builder)
              throws java.io.IOException,
                     VCardException
Throws:
java.io.IOException
VCardException

cancel

public void cancel()
Cancel parsing. Actual cancel is done after the end of the current one vcard entry parsing.


parse

public void parse(java.io.InputStream is,
                  java.lang.String charset,
                  VBuilder builder,
                  boolean canceled)
           throws java.io.IOException,
                  VCardException
It is very, very rare case, but there is a case where canceled may be already true outside this object.

Throws:
java.io.IOException
VCardException

showDebugInfo

public void showDebugInfo()