-
Notifications
You must be signed in to change notification settings - Fork 93
Changelog
Regarding backwards-compatibility: Regrettably, I have not been formally adhering to semantic versioning convention when assigning version numbers to each release. Each release may or may not introduce API changes that break builds.
August 27, 2023
- Fixed an issue that caused a crash when a date/time property contained an invalid component (e.g. "13" for the month). A warning is now logged instead (Issue 134).
- KIND property now uses case-insensitive string comparison for its "is*" methods (Issue 140).
- Removed hyphen character from "Automatic-Module-Name" JAR manifest entry because hyphens cannot be used in module names.
- Updated dependencies.
February 4, 2023
- ez-vcard now requires Java 1.8.
- Replaced old Java date/time code with
java.time
. - Replaced old Java file system code with the newer API (
java.nio.Path
, etc). - Impp property now uses case-insensitive string comparison for URI scheme (Issue 123).
- Added "Automatic-Module-Name" to JAR file manifest.
- Updated dependencies to their latest versions.
September 11, 2021
- Fixed more issues where locale-specific digit characters were used in timestamps and other numeric values (Issue 113).
- Removed a
.properties
file that has been causing problems for many Android/Proguard users (Issue 116). - Updated jsoup dependency in response to vulnerability CVE-2021-37714 (Issue 118).
- Updated jackson and freemarker dependencies to their latest versions.
November 8, 2020
- Fixed an issue where locale-specific digit characters were used in timestamps and other numeric values (Issue 113).
October 24, 2020
- Fixed an issue where property values encoded in quoted-printable encoding would be included in 3.0 and 4.0 vCards. These vCard versions do not support quoted-printable encoding (Issue 112).
- Updated Jackson dependency to latest version.
July 24, 2020
- Properties with date/time values now preserve the date/time components that were in the original timestamp string from the source vCard data (Issue 107). The components are stored in a
java.util.Calendar
object and can be accessed using the following methods:- Anniversary.getCalendar()
- Birthday.getCalendar()
- Deathdate.getCalendar()
- Revision.getCalendar()
- ez-vcard now requires at least Java 6. Java 5 is no longer supported by newer JDKs (Issue 90).
- Updated Jackson dependency to latest version.
- Minor improvements from IntelliJ code analysis.
March 16, 2020
- URIs can now be used as KEY property values (Issue 100).
- Relaxed date parsing: Dates with single digit month and/or date components can now be parsed, provided they are in extended format (e.g. 2020-1-3). Before this change, such a date would fail to parse, causing the property to be parsed as a
RawProperty
object (Issue 102). - Updated dependency libraries to latest versions.
December 23, 2018
- Fixed issue where the values of plaintext KEY properties were not written (Issue 91).
- Updated dependency libraries to latest versions.
April 7, 2018
- Fixed issue where the
all()
method in the chaining parser API was not considering custom scripts (Issue 81). - Updated vinnie dependency to support OSGi.
August 12, 2017
- Folded property values encoded in quoted-printable are no longer indented (see this and this issue).
- Added
foldLines()
method toEzvcard
chaining API.
February 19, 2017
- Fixed an issue regarding how commas are escaped in version 2.1 vCards (Issue 67).
- Parse warnings are now represented by the
ParseWarning
class, instead of a String. This gives you access to more information about the warning, such as the warning code and line number.
December 31, 2016
- Fixed an issue regarding how characters are escaped in version 2.1 vCards (Issue 67).
- Fixed a bug that prevented the
Ezvcard
class from writing vCards to a file. - Fixed a bug that prevented a vCard from being written if certain properties contained an invalid PREF parameter (Issue 76).
- Improved performance of date parsing.
- Added support for the following timestamp formats (Issue 73):
- Timestamps that lack a UTC offset (e.g. "20161231T131000"). These will be parsed under the local computer's default timezone.
- Timestamps that lack the minute component of the UTC offset (e.g. "20161231T131000-05").
- Timestamps that contain a fraction-of-a-second component (e.g. "20161231T131000.1548").
October 8, 2016
- Refactored plain-text serialization code to use the vinnie library. This library provides generic read/write support for vCard and iCalendar file formats. This causes the following changes in ez-vcard:
- All parameters are now given names when writing a 2.1 vCard. For example, instead of writing
ADR;HOME
, it now writesADR;TYPE=home
- Escape sequences are no longer recognized in group names, property names, or parameter names (this was never intentional in the first place). For example, previously, the newline escape sequence in the property name "HELLO\nWORLD" would have been replaced with a real newline sequence when parsed.
- The
\n
newline escape sequence is no longer recognized in parameter values (with the exception of LABEL parameters of ADR properties). ez-vcard will no longer automatically encode newlines in parameter values when writing a vCard or decode them when parsing a vCard. Consider enabling circumflex accent encoding if you want to insert an encoded newline into a parameter value. - The
\"
escape sequence for inserting double quote characters in parameter values no longer works, as it was not spec-compliant. Consider enabling circumflex accent encoding if you want to insert an encoded double quote into a parameter value. - The individual items in structured property values (such as ADR) and list property values (such as CATEGORIES) are no longer trimmed when parsed. For example,
CATEGORIES:one, two, three
now yields the list["one", " two", " three"]
(notice the space character at the beginning of the last two strings).
- All parameters are now given names when writing a 2.1 vCard. For example, instead of writing
- When parsing a vCard and matching up LABEL properties with their associated ADR properties, the order of the TYPE parameters no longer matters.
- Added the ability to specify your own hCard template (see HCardPage).
August 28, 2016
- Added XXE protection when parsing xCards (Issue 55).
- Added
VCardWriter.setTargetApplication()
method for use when a specific vCard consumer requires special processing. This method replaced theVCardWriter.setOutlookCompatibility()
method. - Changed all 2.1
ENCODING
parameter values to be in upper-case instead of lower-case. This make them a little bit more spec-compliant because the 2.1 specification does not say anything about these parameter values being case-insensitive. This also resolves a compatibility issue with the Windows 10 Contacts app (Issue 56) - Changed the way trailing semicolons on structured values are handled. They are now trimmed by default in vCard versions 2.1 and 3.0. For example, instead of writing
N:Family;;;;
, it will now writeN:Family
. This setting can be changed by callingVCardWriter.setIncludeTrailingSemicolons()
(Issue 57). - The
REV
property was not using proper syntax when being written to a version 3.0 vCard. -
VCardReader
is now aware of differences in how the vCard versions handle whitespace at the beginning of folded lines. Version 2.1 allows multiple whitespace characters to be used, while versions 3.0 and 4.0 only allow a single whitespace character to be used. - Fixed a bug related to how property parse errors are handled. Previously, if a property could not be parsed, the RawProperty object that is created in its place was not being assigned the property's parameters or data type.
May 17, 2016
- Improved this library's multimap implementation (
ListMultimap
) so thatList
objects returned by itsget()
method are backed by the multimap. In other words, any changes that are made to theseList
objects will update the multimap, and vice versa. This effects the following:-
List
objects returned by theVCard
class, which hold property objects. -
List
objects returned by theVCardParameters
class, which hold parameter values.
-
- In response to the above change, various "add/remove" methods were removed from the property classes that simply added and removed elements from a
List
(for exampleTelephone.addType()
). This was done to remove cruft from the API. Instead, use the getter method to get theList
object, and perform your modifications on that. - Modified serialization logic to ensure that the PRODID property is the first property to be written (after VERSION). This is not required by the specs, but may help with interoperability.
- INDEX and PREF parameters are no longer validated in their "setter" methods. Moved validation logic to the
validate()
method. - PID parameter values are now represented with
Pid
objects, instead ofInteger
arrays. - GEO parameter values are now represented with
GeoUri
objects, instead of twodoubles
. - Improved the
DataUri
class so it supports more than just binary data. - Renamed
StructuredName.getAdditional()
togetAdditionalNames()
. - Renamed the various
indent()
methods for jCards toprettyPrint()
. - Improved jCard (JSON) pretty printing by making use of jackson's pretty printing framework.
- Added optional support for the jackson-databind framework (see
JCardModule
and@JCardFormat
). - Fixed an issue with xCard where extended properties with "unknown" data types were parsed incorrectly under certain circumstances.
- Fixed a round-tripping issue with xCard and jCards where extended properties with backslash-escaped characters were double-escaped when parsed.
- The names of extended properties in xCards are now converted to upper-case when parsed.
- Updated the embedded commons-codec code to the latest version (1.10).
- Removed unnecessary commons-codec source files.
February 6, 2016
- Added
equals()
andhashCode()
methods to all property and parameter classes. This allows you to check twoVCard
objects for value equality. - Added the ability to make deep copies of
VCard
objects. Simply invoke its copy constructor. - Added useful
toString()
methods to all property classes. - Relaxed the logic that checks property names for validity before writing them to an output stream. Before, it would throw an exception if a property name contained any characters not allowed by the specifications. Now, it only throws an exception if the property name contains a character that breaks the syntax (such as newline sequences and colon characters). Spec-compliant character checks have been moved to the validation framework (see
VCard.validate()
). - Parameter values are no longer quietly modified to remove or replace invalid characters. All characters are now allowed, except for the ones that break the syntax (in which case, an exception is thrown). Spec-compliant character checks have been moved to the validation framework (see
VCard.validate()
). - The
ADR
property is now multi-value aware. According to theADR
property syntax, it is possible for each component of the address to contain multiple values, even though this almost never happens in practice. ez-vcard would previously only recognize the first value and ignore the rest. This became an issue when the property contained a comma character in the street address component, and the comma was not properly escaped (see next item). - Added
Address.getStreetAddressFull()
andAddress.getExtendedAddressFull()
methods. These can be used in the event that the parsed ADR property did not properly escape any comma characters in the extended and street addresses. - Prevented UTF-16 surrogate pairs from being split up across folded lines (see Pull Request 36).
- Improved performance by removing some regular expressions.
- Renamed
XCardDocument.add(VCard)
toaddVCard(VCard)
. - Fixed an issue where special characters in the
IMPP
property value URIs were not being encoded correctly when being written to an output stream (see Pull Request 34). - Added
VCardRawReader.setVersionAlias()
method, which allows you to define how a vCard is parsed if it contains a non-standard version number. - Moved exception messages into a resource bundle.
November 14, 2015
- Added the ability to specify the XML version when writing xCards (see Issue 29). Note that most JDKs only support version 1.0 natively, so you'll need to include a library like xalan if you want XML 1.1 support.
- Added the ability to specify your own, custom JAXP output properties when writing xCards.
- Fixed an issue where ez-vcard would consume multiple whitespace characters when reading a folded line. This was in conflict with the specifications, which state that folded lines must begin with only one whitespace character (see Issue 30).
- Added logic to IMPP properties to use the
TYPE=pref
orPREF=1
parameters, depending on what version the vCard is being written in (see Issue 32). - Rolled-back a change from 0.9.7, which added a blank line after all base64-encoded property values. This is necessary for compatibility with Microsoft Outlook mail clients, but breaks other vCard consumers. Added the ability to turn this feature on by calling the
VCardReader.setOutlookCompatibility()
method (it is now off by default) (see Issue 33). - Made the parsing of folded, quoted-printable property values more robust by refactoring the way ez-vcard parses input.
September 13, 2015
- Fixed a bug where certain ORG properies weren't being written correctly in jCards (see Issue 27)
- Fixed a compatibility issue where Outlook 2010 requires there to be an empty line after base64-encoded public keys (see Issue 21).
- Fixed a bug where custom scribes were not being used in embedded vCards.
- Refactored the PartialDate class.
- Refactored the UtcOffset class to store its value in milliseconds instead of hours/minutes.
- When parsing LOGO, PHOTO, SOUND, and KEY properties, the parser now looks at the file extension in the URL to determine the media type if no other information is available.
- Updated the following dependencies:
- jsoup: 1.7.3 -> 1.8.3
- Freemarker: 2.3.20 -> 2.3.23
- jackson: 2.3.3 -> 2.6.1
- Javadoc improvements.
October 13, 2014
- Added a "readAll()" method to all reader classes.
- Added optional dependency definitions to OSGi bundle settings.
- Removed the constructors from
VCardWriter
that allow you to customize the line folding settings. See the VCardWriter Javadocs for new instructions on how to modify these settings. - Fixed a bug where variables in the hCard template were being removed during the build process (credit: David Spieler; see Issue 19).
- Fixed a bug where LABEL properties in nested 2.1 vCards weren't being assigned to their ADR properties correctly.
- Fixed a validation bug where the CATEGORIES and SORT-STRING properties were considered to be part of the 2.1 spec (they are not).
July 26, 2014
- Fixed a bug where not all newline sequences were being written as
<br />
in hCards (credit: aliteralmind). - Fixed a bug where XCardWriter was incorrectly encoding "\r" characters in Windows newline sequences (credit: aliteralmind).
- Date property values are now encoded correctly in version 3.0 vCards (credit: 沈�). Before, they were encoded in "basic" format (e.g. "20140726"). Now, they are encoded in "extended" format (e.g. "2014-07-26").
May 31, 2014
- Added a streaming API for xCards (
XCardReader
,XCardWriter
). - Fixed a bug where
<unknown>
property values in xCard documents weren't being parsed correctly. - Fixed a bug that caused a NPE to be thrown when removing the LEVEL parameter from a EXPERTISE or INTEREST property.
- Fixed a bug that prevented ORG properties with empty values from being written to an hCard (Issue 16).
- Fixed an hCard bug where a vCard with an embedded vCard would treat the embedded vCard's properties as its own.
- Renamed
HCardReader
toHCardParser
. - Upgraded jsoup dependency from version 1.7.1 to 1.7.3.
- Upgraded jackson dependency from version 2.1.3 to 2.3.3.
- Improved the performance of plain-text vCard parsing by removing a regular expression.
- Removed a reference to a jsoup class in "VCardPropertyScribe". This allows users to create custom scribe classes without having to add the optional jsoup dependency to their project.
April 1, 2014
- Fixed a bug where incorrectly encoded quoted-printable values were preventing the vCard from being parsed (Issue 15).
- Javadoc improvements.
February 4, 2014
- If a property's value is encoded in quoted-printable encoding, then the property should contain a CHARSET parameter that defines the character set that the property value was encoded in. However, not all vCards may include such a parameter. To account for this, you can now define the default character set to use when parsing quoted-printable properties that do not have a CHARSET parameter (Issue 12). Use the "VCardReader.setDefaultQuotedPrintableCharset()" method to define this setting.
- Quoted-printable property values are now encoded using UTF-8 when written if no CHARSET parameter is present. This improves interoperability, since virtually all systems support this character set. Before, the character set of the "Writer" object would be used, which could be a non-standard character set or a character set specific to the local operating system.
- Fixed a bug where ORG properties with multiple values weren't being written correctly in plain-text vCards (Issue 13).
- Fixed a bug where the "ez-vcard.properties" file wasn't being filtered during the build process. This caused the PRODID property of vCards created by ez-vcard to show the wrong version number of ez-vcard (Issue 14).
December 24, 2013
- Added OSGi support (credit: Florian Brunner).
- Moved the validation and parser warnings into a resource bundle for i18n. Note that some messages were tweaked in the process.
- Validation warnings now have IDs associated with them so they can be handled programmatically.
- Added a validation check which checks whether the CHARSET parameter is a recognized character set.
- Fixed a bug that prevented quoted-printable property values from being encoded correctly when written (credit: Tom Vogel).
October 25, 2013
This update includes significant changes to the API. Existing code that uses eariler versions may break.
- Added a new marshalling framework. This moves the marshalling code out of the property classes and into classes of their own (called "scribes"), creating a cleaner separation between the data model and the marshalling code. Property classes are no longer required to have a default constructor.
- Removed the "Type" suffix from the property class names (for example, renamed
AddressType
toAddress
). Property classes that are meant to be parent classes have had their "Type" suffix replaced with "Property" (for example, renamedTextType
toTextProperty
). - Removed the "Parameter" suffix from the parameter class names (for example, renamed
AddressTypeParameter
toAddressType
). - Removed the property name from the
VCardType
class (i.e. removed thegetTypeName()
method). Each property's name now resides in its "scribe" class (located in the "ezvcard.io.scribe
" package). - Grouped the I/O classes into sub-packages based on their format type (for example,
VCardReader
was moved from "ezvcard.io
" to "ezvcard.io.text
"). - Renamed all methods in the
VCardType
class so that they use "parameter" terminology instead of "sub type" terminology (for example, renamedgetSubTypes
togetParameters
). - Renamed all methods in the
VCard
class so that they use "property" terminology instead of "type" terminology (for example, renamedaddType
toaddProperty
) - Renamed and/or moved the following packages/classes:
-
ezvcard.types
-->ezvcard.property
-
ezvcard.parameters
-->ezvcard.parameter
-
ezvcard.VCardSubTypes
-->ezvcard.parameter.VCardParameters
-
ezvcard.types.VCardType
-->ezvcard.property.VCardProperty
-
ezvcard.util.HCardElement
-->ezvcard.io.html.HCardElement
-
ezvcard.util.XCardElement
-->ezvcard.io.xml.XCardElement
-
ezvcard.util.JsonValue
-->ezvcard.io.json.JsonValue
-
ezvcard.util.JCardValue
-->ezvcard.io.json.JCardValue
- The
Ezvcard
class now flushes the stream after every plain-text or JSON-encoded vCard is written. - Fixed a bug with the
Ezvcard
class that prevented UTF-8 encoding from being used when writing xCards and jCards.
October 1, 2013
- Fixed a bug where "quoted-printable" encoded property values were not being folded correctly (see Issue 9).
September 19, 2013
Major changes:
-
Validation framework: Added a validation framework that checks
VCard
objects for errors. It can be invoked by callingVCard.validate()
. The writer classes no longer generate a list of warnings when aVCard
is written. -
XCardDocument/XCardReader merge: Merged the
XCardReader
class into theXCardDocument
class.XCardDocument
is now used to both read and write xCards. -
Unparsable properties no longer ignored: Added a
CannotParseException
, which is thrown if a property value cannot be parsed. This will cause the property to be unmarshalled as aRawType
instead of being completely ignored, allowing for its raw value to be retrieved. For xCards, such properties will be unmarshalled asXmlType
properties. -
Improved UTF-8 support: UTF-8 encoding is now used essentially whenever a
File
orInputStream/OutputStream
object is passed into one of ez-vcard's reader/writer classes. JavaReader/Writer
objects are configured to use their own character encoding, so they are not effected by this change. - If a
File
orOutputStream
object is passed into a plain-text vCard writer, and the target version is 4.0, UTF-8 encoding will be used. All other versions will use the JVM's default character encoding. - If a
File
orOutputStream
object is passed into a xCard or jCard writer, UTF-8 encoding will be used. - If a
File
orInputStream
object is passed into a plain-text vCard reader, the JVM's default character encoding is still used for backwards compatibility to older vCard versions. - If a
File
orInputStream
object is passed into a xCard reader, the "encoding" attribute in the header portion of the XML document will be properly taken into account. Before, it was ignored and the document was always parsed according to the JVM's default character encoding. - If a
File
orInputStream
object is passed into a jCard reader, UTF-8 decoding will be used.
Other changes:
- Added the
VCardDataType
class, which represents a vCard data type (such as "text" and "uri"). It replaces theValueParameter
andJCardDataType
classes. - Added the ability to append onto existing files when writing plain-text files with the
Ezvcard
class. - The
Ezvcard.parse(File)
methods no longer throw aFileNotFoundException
. - Added the
XCardDocument.registerParameterDataType()
method for setting the data types of extended parameters. - The
XmlType
property now stores its value as aDocument
object instead of aString
. - The following
VCardSubType
methods now throw anIllegalStateException
when their parameter value cannot be parsed (for example, if the PREF parameter is non-numeric). Before, they would return "null", which was misleading because "null" also means that the parameter does not exist. Raw parameter values can still be retrieved using theget()
method. getPref()
getGeo()
getPids()
getIndex()
- Added a
versionStrict
flag to the writer classes. When enabled, properties that do not support the target vCard version will not be written to the data stream (for example, a GENDER property, which is only supported by 4.0, will not be written to a 2.1 vCard). This is how the writers have functioned in the past. When the flag is disabled, properties that do not support the target vCard version will be written anyway. This setting is enabled by default. - A
CannotParseException
is now consistently thrown during the parsing of xCard properties when the XML element which holds the property's value cannot be found. Before, aSkipMeException
was sometimes thrown, but not always. - Changed the behavior for how properties with empty values are written. Before, they were not written to the vCard at all, but now they are. The new
VCard.validate()
method can be called to check for properties that have empty or inappropriate values. - Changes to the
TimezoneType
property: - Now accepts a
java.util.TimeZone
object as its value. - If it only contains a text value and it is being written to a 2.1 vCard, it will attempt to calculate the UTC offset by treating the text value as an Olson timezone ID.
- When parsing an xCard, if its xCard value contains both a
<text>
and a<uri>
element (which is not allowed), only the<text>
element will be parsed. Before, both were parsed. - User-defined type classes can now override the standard type classes. This means that it's now possible to create alternative type classes for standard properties like ADR.
- Made the following classes immutable:
DataUri
GeoUri
TelUri
- Added the following methods to
VCardType
: getSubType(String)
getSubTypes(String)
setSubType(String, String)
addSubType(String, String)
removeSubType(String)
removeType(VCardType)
- Renamed the following methods:
-
XCardDocument.addVCard
-->add
-
HCardPage.addVCard
-->add
-
JCardValue.getSingleValued
-->asSingle
-
JCardValue.getMultivalued
-->asMulti
-
JCardValue.getStructured
-->asStructured
- Added syntax highlighting to the code samples in the Javadocs. :)
August 4, 2013
- Updated jCard functionality to adhere to the most recent draft specification.
- Removed the "vcardstream" array.
- jCards can optionally be wrapped in a JSON array (useful when writing multiple jCards).
- Fixed a bug that prevented
KEY
URLs from being parsed correctly. - Fixed the XML marshalling of N and ADR properties so that XML elements for every value component is included, even if the component is null or empty.
- Fixed a bug that gave
LANG
properties the wrong data type in jCards. -
ORG
property values are no longer surrounded by brackets in jCard if the property only has one value. - Date-related property values are now written to "date" or "date-time" XML elements, instead of "date-and-or-time" elements.
- Date-related properties with date, date-time, or partial-date values (such as
BDAY
) no longer includeVALUE
orCALSCALE
parameters when written, except when the value is text (in which case aVALUE=text
parameter is added). - Fixed the marshalling of UTC offset values for the
TZ
property for 4.0 vCards and xCards ("basic" format should be used, not "extended"). - Refactored the way in which the
VCard
class stores its properties:- When parsing, all property instances are now added to the
VCard
object. Previously, for properties with a cardinality of zero or one, the only instance that was retrievable was the one that was parsed last. - Property order is more predictable during marshalling. Properties are essentially written in the order that they were added to the
VCard
object. - Removed the
addExtendedType(VCardType)
method. To add an extended type class instance, useaddType(VCardType)
instead. - Removed the
getExtendedType(Class)
method. To get an extended type class instance, usegetType(Class)
instead.
- When parsing, all property instances are now added to the
- Refactored the jCard reading/writing code:
- The
JCardValue
class now holds the raw JSON data in the form ofJsonValue
objects. This adds greater flexibility for reading/writing wonky property values. - Removed the
JCardDataType.UNKNOWN
enum. A "null" value is now used to represent the "unknown" data type. - Pretty printing has been tweaked slightly.
- The
- Refactored the parsing code of plain-text vCards. Parsing is slightly more strict:
BEGIN:VCARD
andEND:VCARD
properties are now required, or else the vCard will not be parsed.
June 17, 2013
- Fixed an Android compatibility issue: Android's version of commons-codec (1.2) was overriding the version that ez-vcard uses (1.6) (see this discussion). Selection portions of the commons-codec 1.6 source code have been added to the ez-vcard code base. Their package names were changed in order to eliminate the conflict.
- vCard (plain-text) and jCard (JSON) readers now include line numbers in their warnings (for example: "Line 10 (TEL property): Could not parse property value as a URI. Assuming it's text.")
- Each warning message is now prefixed with the name of the property that the warning belongs to (see example in previous bullet point).
- Minor text changes to some of the warning messages.
May 21, 2013
- Added a new
PartialDate
class for representing truncated and reduced accuracy dates. - The
TelephoneType
class (TEL property) now distinguishes between text and URI values. A URI value is represented with the newTelUri
class. - A
TemplateException
exception is no longer thrown when writing a vCard to an HTML page (see Issue 7, credit: dnault). - GENDER is no longer marshalled as a structured jCard property if it does not contain the optional text component.
- Fixed a bug dealing with the way in which XML namespaces are handled in xCards.
April 17, 2013
- Added support for jCard (JSON-encoded vCards, see: jCard draft specification).
- Added methods to the
VCard
class for adding groups of alternative representations. These methods will automatically generate an appropriateALTID
parameter value. - Fixed a typo in the name of the
DateOrTimeType.setCalscale()
method. - Fixed an issue with hCards where
AGENT
URLs were not being parsed correctly. -
TZ
parameters in theADR
property are no longer parsed as URIs. - Improved overall unit test coverage.
March 29, 2013
- Fixed an issue that prevented the
GEO
property from marshalling correctly under certain locales (credit: Moritz Bechler).
February 24, 2013
- Renamed the marshal methods in the
VCardType
class to better reflect their format (e.g. renamed "unmarshalValue" to "unmarshalText"). - Fixed a bug in how "quoted-printable" property values are parsed: values that have empty lines at the end of them are now parsed correctly (see this discussion)
- Added
KIND:device
(RFC 6869). - Changed how the
SORT-AS
parameter works in theOrganizationType
andStructuredNameType
classes. - Major fixes/additions to parameter values in plain-text vCards:
- Added support for circumflex accent encoding (RFC 6868).
- Certain invalid characters are now removed completely from each parameter value on marshal. A warning is logged if the parameter gets modified in any way. These characters are:
- ASCII control characters
- The following characters in 2.1 vCards:
,
.
:
=
[
]()
- Other invalid characters are now replaced with another character. A warning is logged if the parameter gets modified in any way. These characters are:
- Double quotes in 3.0/4.0 vCards are replaced with single quotes (before, they were escaped with backslashes, which is not part of the standard).
- Newlines in 2.1/3.0 vCards are replaced with spaces (before, they were escaped with backslashes, which is not part of the standard). Newlines continue to be escaped with backslashes in 4.0 vCards in order to support the
LABEL
parameter. - Fixed how double-quoted, multi-valued parameters in 3.0/4.0 are implemented. For multi-valued parameters, double quotes were put around all the values instead of each individual value, which is incorrect according to the ABNF.
- Added the ability to parse multi-valued
TYPE
parameters that are enclosed entirely in double quotes (e.g.ADR;TYPE="home,work"
). This is done to account for an error in the 4.0 specs.
January 17, 2013
- Fixed a critical error in the way an xCard is written. If the vCard had a PRODID property and "XCardDocument" was configured to add a PRODID property, then it would not write the vCard.
January 13, 2013
- It's the Usability Update!
- Added a method chaining interface for reading/writing vCards (
Ezvcard
class). - Added convenience constructors to
KeyType
,LogoType
,PhotoType
, andSoundType
classes for getting the binary data from aFile
orInputStream
object (in addition to the originalbyte
array). - Added convenience constructors to the reader classes so that the vCards can be read from a
String
,File
, orInputStream
(in addition the originalReader
). - Added convenience methods to the writer classes so that the vCards can be written to a
String
,File
, orOutputStream
(in addition the originalWriter
). - Added convenience methods to the
VCard
class to make it easier to add certain basic properties. For example, to set theFN
property, aString
can be passed into thesetFormattedName()
method instead of aFormattedNameType
object. - Added the
Iterable
interface to theVCard
class, which allows you to iterate over each of the properties in the vCard. - Added the
VCard.getAllTypes()
method to get all properties in the vCard. - Added support for pretty-printing xCard XML documents.
- Made xCard parsing more flexible by allowing the xCard XML element to exist anywhere inside the XML document.
- Fixed namespace-related bugs in the xCard parsing code.
- Fixed how newlines are encoded in 2.1 vCards: property values that contain newlines are now "quoted-printable" encoded (see Issue 3).
- Deprecated the
get/setCompatibilityMode()
methods on the readers/writers.
December 12, 2012
- Added support for the hCard microformat (HTML-encoded vCards).
-
PRODID
is now used instead ofX-GENERATOR
for marking the vCard as having been generated by ez-vcard. This is whatPRODID
is supposed to be used for. SincePRODID
is not supported in 2.1,X-PRODID
is used in 2.1 vCards. - Fixes to
IMPP
property class: ** Added 3.0 to its list of supported versions.IMPP
was introduced in a separate specification after the 3.0 specs were released. ** Added ICQ and Skype support. ** Fixed the scheme string for MSN instant messenger handles. ** Added getters for getting the IM protocol (e.g. "aim") and handle (e.g. "[email protected]"). - Removed 2.1 from
NICKNAME
's list of supported versions. This property is not defined in the 2.1 specs. - Fixed a typo in the name of the
CALADRURI
property. - When unescaping an escaped newline in a plain text vCard, the local system's newline sequence is now used instead of "\r\n".
-
GEO
coordinate values are now rounded to 6 decimals instead of 4 when marshalling (see Issue 2). - Added
RevisionType.now()
helper constructor. It generates aREV
property whose value is the current time. - Renamed
XCardMarshaller
toXCardDocument
.
November 8, 2012
- Marshalling classes (
VCardReader
,VCardWriter
,XCardReader
,XCardMarshaller
) no longer throw a checkedVCardException
. - ORG-DIRECTORY type class was missing the
getSupportedVersions()
method. - Added the ability to specify the XML element name of extended types (xCard).
- Improved the performance of the marshaller classes. The same
List
object is now used for collecting the marshalling warnings of each vCard type (previously, a newList
object was created for every vCard type). - Refactored the way in which AGENT is marshalled to make the marshalling of embedded vCards more generic. An
EmbeddedVCardException
is now thrown from theAgentType
class, which the marshaller catches and then uses to marshal/unmarshal the embedded vCard. - Renamed
AgentType.get/setVcard()
toAgentType.get/setVCard()
(capitalized the "C") -
VCard.addExtendedType(String, String)
now builds aRawType
instead of aTextType
. - Removed the
VCardReaderBuilder
class. - Removed the more obscure image and sound types from
ImageTypeParameter
andSoundTypeParameter
and added a couple new ones. - Removed the
Protocol
enum from theImppType
class and added helper methods for reading/creating handles for common IM clients (e.g. AIM and Yahoo! Messenger).
October 2, 2012
- Tweaked POM file for inclusion in Maven Central.
- Removed the
getType()
andsetType()
methods from theImppType
class. These methods were not necessary becauseImppType
inherits fromMultiValuedTypeParameterType
.
September 24, 2012
- Added support for RFC 6473 (KIND:application)
- Added support for RFC 6474 (BIRTHPLACE, DEATHPLACE, DEATHDATE)
- Added support for RFC 6715 (Open Mobile Alliance Converged Address Book extensions)
- Added convenience methods to
VCard
class for reading/writing xCards. - Fixed bug in the RELATED property that prevented URI values from being read.
- Multiple instances of the BDAY and ANNIVERSARY properties can now be added to the
VCard
object. This is necessary because these properties support the ALTID parameter.
September 8, 2012
- Added support for xCard (an XML representation for vCards).
- Added the
SkipMeException
, which can be thrown from a type class's marshal or unmarshal methods. If thrown from a marshal method, it will prevent the property from being marshalled. If thrown from an unmarshal method, it will prevent the type object from being added to theVCard
object. - Added logic to the
EMAIL
andTEL
properties to determine whether to use the "TYPE#pref
" or "PREF1
" parameter (depending on the vCard version) when marshalling. - Fixed the
TYPE
parameter of theRELATED
property so that it is (1) optional and (2) multi-valued. - Fixed the
GEO
property so it properly marshals/unmarshals its value for 4.0 vCards. - Fixed the
VCard
object so it no longer is missing getters/setters for theGENDER
property. - Removed the "guava" dependency.
- Removed the "commons-io" dependency.
August 11, 2012
- Added support for vCard 4.0
- Removed the space that ez-vcard added after the colon in the marshalled vCard. This prevented some mail clients from reading the vCard (see Issue 1).
- Values for the BEGIN, END, and PROFILE types are now in upper-case (i.e. "BEGIN:VCARD"). The 2.1/3.0 specs appear to require it to be in upper-case, so better safe than sorry (see Issue 1).
- Fleshed out the Javadocs.
July 28, 2012
- Removed SLF4J dependency.
- Modified
VCard
class to only allow one UID type in accordance with the specs. - Binary vCard types such as PHOTO and LOGO now use the proper ENCODING value when marshalled ("base64" for 2.1 and "b" for 3.0).
- Renamed
DisplayableNameType
class toSourceDisplayTextType
. - Renamed
OrgType
class toOrganizationType
.
July 23, 2012
First release
ez-vcard is maintained by Michael Angstadt
Table of Contents
Getting started
Examples
FAQ
Javadocs
Downloads
1 An Overview of the vCard data format
2 Reading and Writing vCard data with ez-vcard
2.1 Plain-text (traditional)
2.2 XML-encoded (xCard)
2.3 JSON-encoded (jCard)
2.4 HTML-encoded (hCard)
3 Differences between the vCard versions
4 Dealing with Non-standard Data
4.1 Working with non-standard properties and parameters
4.2 Property scribe
5 Project Information
5.1 News
5.2 Dependencies
5.3 Supported Specifications
5.4 Changelog
6 Reference
6.1 vCard Property Reference
6.2 Javadocs