Class VCard

java.lang.Object

org.jivesoftware.smack.packet.Stanza

org.jivesoftware.smack.packet.IQ

org.jivesoftware.smackx.vcardtemp.packet.VCard

All Implemented Interfaces:

Element, IqView, NamedElement, StanzaView, TopLevelStreamElement, XmlElement, XmlLangElement

public final class VCard
extends IQ

A VCard class for use with the SMACK jabber library.

You should refer to the XEP-54 documentation.

Please note that this class is incomplete but it does provide the most commonly found information in vCards. Also remember that VCard transfer is not a standard, and the protocol may change or be replaced.

Usage:

// To save VCard:

VCard vCard = new VCard();
vCard.setFirstName("kir");
vCard.setLastName("max");
vCard.setEmailHome("foo@fee.bar");
vCard.setJabberId("jabber@id.org");
vCard.setOrganization("Jetbrains, s.r.o");
vCard.setNickName("KIR");

vCard.setField("TITLE", "Mr");
vCard.setAddressFieldHome("STREET", "Some street");
vCard.setAddressFieldWork("CTRY", "US");
vCard.setPhoneWork("FAX", "3443233");

vCard.save(connection);

// To load VCard:

VCard vCard = new VCard();
vCard.load(conn); // load own VCard
vCard.load(conn, "joe@foo.bar"); // load someone's VCard

Nested Class Summary

Nested classes/interfaces inherited from class IQ

IQ.IQChildElementXmlStringBuilder, IQ.ResponseType, IQ.Type

Field Summary

Fields

Modifier and Type	Field	Description
static final String	ELEMENT
static final String	NAMESPACE

Fields inherited from class IQ

IQ_ELEMENT, QUERY_ELEMENT

Fields inherited from class Stanza

DEFAULT_LANGUAGE, ITEM, language, TEXT

Constructor Summary

Constructors

Constructor	Description
VCard()

Method Summary

Modifier and Type	Method	Description
boolean	equals(Object o)
String	getAddressFieldHome(String addrField)	Get home address field.
String	getAddressFieldWork(String addrField)	Get work address field.
byte[]	getAvatar()	Return the byte representation of the avatar(if one exists), otherwise returns null if no avatar could be found.
String	getAvatarHash()	Returns the SHA-1 Hash of the Avatar image.
String	getAvatarMimeType()	Returns the MIME Type of the avatar or null if none is set.
static byte[]	getBytes(URL url)	Common code for getting the bytes of a url.
String	getEmailHome()
String	getEmailWork()
String	getField(String field)	Get the content of a generic VCard field.
String	getFirstName()
protected IQ.IQChildElementXmlStringBuilder	getIQChildElementBuilder(IQ.IQChildElementXmlStringBuilder xml)	This method must be overwritten by IQ subclasses to create their child content.
String	getJabberId()
String	getLastName()
String	getMiddleName()
String	getNickName()
String	getOrganization()
String	getOrganizationUnit()
String	getPhoneHome(String phoneType)	Get home phone number.
String	getPhoneWork(String phoneType)	Get work phone number.
String	getPrefix()
String	getSuffix()
int	hashCode()
void	load(XMPPConnection connection)	Deprecated. use VCardManager.loadVCard() instead.
void	load(XMPPConnection connection, EntityBareJid user)	Deprecated. use VCardManager.loadVCard(EntityBareJid) instead.
void	removeAvatar()	Removes the avatar from the vCard.
void	save(XMPPConnection connection)	Deprecated. use VCardManager.saveVCard(VCard) instead.
void	setAddressFieldHome(String addrField, String value)	Set home address field.
void	setAddressFieldWork(String addrField, String value)	Set work address field.
void	setAvatar(byte[] bytes)	Specify the bytes of the JPEG for the avatar to use.
void	setAvatar(byte[] bytes, String mimeType)	Specify the bytes for the avatar to use as well as the mime type.
void	setAvatar(String encodedImage, String mimeType)	Specify the Avatar used for this vCard.
void	setAvatar(URL avatarURL)	Set the avatar for the VCard by specifying the url to the image.
void	setEmailHome(String email)
void	setEmailWork(String emailWork)
void	setEncodedImage(String encodedAvatar)	Deprecated. Use setAvatar(String, String) instead.
void	setField(String field, String value)	Set generic VCard field.
void	setField(String field, String value, boolean isUnescapable)	Set generic, unescapable VCard field.
void	setFirstName(String firstName)
void	setJabberId(CharSequence jabberId)
void	setLastName(String lastName)
void	setMiddleName(String middleName)
void	setNickName(String nickName)
void	setOrganization(String organization)
void	setOrganizationUnit(String organizationUnit)
void	setPhoneHome(String phoneType, String phoneNum)	Set home phone number.
void	setPhoneWork(String phoneType, String phoneNum)	Set work phone number.
void	setPrefix(String prefix)
void	setSuffix(String suffix)

Methods inherited from class IQ

createErrorResponse, createErrorResponse, createResultIQ, getChildElementName, getChildElementNamespace, getChildElementQName, getChildElementXML, getElementName, getType, setType, toString, toXML

Methods inherited from class Stanza

addCommonAttributes, addExtension, addExtensions, appendErrorIfExists, getDefaultLanguage, getError, getExtension, getExtension, getExtensionElement, getExtensions, getExtensions, getExtensions, getExtensions, getExtensionsMap, getFrom, getLanguage, getNamespace, getStanzaId, getTo, hasExtension, hasExtension, hasStanzaIdSet, logCommonAttributes, overrideExtension, removeExtension, setError, setFrom, setNewStanzaId, setStanzaId, setTo, throwIfNoStanzaId

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface Element

toXML, toXML

Methods inherited from interface IqView

isRequestIQ, isResponseIQ

Methods inherited from interface StanzaView

getError, getExtension, getExtension, getExtensions, getExtensions, getExtensions, getFrom, getStanzaId, getTo, hasExtension, hasExtension, hasExtension

Methods inherited from interface XmlElement

getQName

Field Details

ELEMENT

public static final String ELEMENT

See Also:

• Constant Field Values

NAMESPACE

public static final String NAMESPACE

See Also:

• Constant Field Values

Constructor Details

VCard

public VCard()

Method Details

getField

public String getField(String field)

Get the content of a generic VCard field.

Parameters:

field - value of field. Possible values: NICKNAME, PHOTO, BDAY, JABBERID, MAILER, TZ, GEO, TITLE, ROLE, LOGO, NOTE, PRODID, REV, SORT-STRING, SOUND, UID, URL, DESC.

Returns:

content of field.

setField

public void setField(String field,
 String value)

Set generic VCard field.

Parameters:

field - field to set. See getField(String)

value - value of field

See Also:

• getField(String)

setField

public void setField(String field,
 String value,
 boolean isUnescapable)

Set generic, unescapable VCard field. If unescapable is set to true, XML maybe a part of the value.

Parameters:

field - field to set. See getField(String)

value - value of field

isUnescapable - True if the value should not be escaped, and false if it should.

getFirstName

public String getFirstName()

setFirstName

public void setFirstName(String firstName)

getLastName

public String getLastName()

setLastName

public void setLastName(String lastName)

getMiddleName

public String getMiddleName()

setMiddleName

public void setMiddleName(String middleName)

getPrefix

public String getPrefix()

setPrefix

public void setPrefix(String prefix)

getSuffix

public String getSuffix()

setSuffix

public void setSuffix(String suffix)

getNickName

public String getNickName()

setNickName

public void setNickName(String nickName)

getEmailHome

public String getEmailHome()

setEmailHome

public void setEmailHome(String email)

getEmailWork

public String getEmailWork()

setEmailWork

public void setEmailWork(String emailWork)

getJabberId

public String getJabberId()

setJabberId

public void setJabberId(CharSequence jabberId)

getOrganization

public String getOrganization()

setOrganization

public void setOrganization(String organization)

getOrganizationUnit

public String getOrganizationUnit()

setOrganizationUnit

public void setOrganizationUnit(String organizationUnit)

getAddressFieldHome

public String getAddressFieldHome(String addrField)

Get home address field.

Parameters:

addrField - one of POSTAL, PARCEL, (DOM | INTL), PREF, POBOX, EXTADR, STREET, LOCALITY, REGION, PCODE, CTRY

Returns:

content of home address field.

setAddressFieldHome

public void setAddressFieldHome(String addrField,
 String value)

Set home address field.

Parameters:

addrField - one of POSTAL, PARCEL, (DOM | INTL), PREF, POBOX, EXTADR, STREET, LOCALITY, REGION, PCODE, CTRY

value - new value for the field.

getAddressFieldWork

public String getAddressFieldWork(String addrField)

Get work address field.

Parameters:

addrField - one of POSTAL, PARCEL, (DOM | INTL), PREF, POBOX, EXTADR, STREET, LOCALITY, REGION, PCODE, CTRY

Returns:

content of work address field.

setAddressFieldWork

public void setAddressFieldWork(String addrField,
 String value)

Set work address field.

Parameters:

addrField - one of POSTAL, PARCEL, (DOM | INTL), PREF, POBOX, EXTADR, STREET, LOCALITY, REGION, PCODE, CTRY

value - new value for the field.

setPhoneHome

public void setPhoneHome(String phoneType,
 String phoneNum)

Set home phone number.

Parameters:

phoneType - one of VOICE, FAX, PAGER, MSG, CELL, VIDEO, BBS, MODEM, ISDN, PCS, PREF

phoneNum - phone number

getPhoneHome

public String getPhoneHome(String phoneType)

Get home phone number.

Parameters:

phoneType - one of VOICE, FAX, PAGER, MSG, CELL, VIDEO, BBS, MODEM, ISDN, PCS, PREF

Returns:

content of home phone number.

setPhoneWork

public void setPhoneWork(String phoneType,
 String phoneNum)

Set work phone number.

Parameters:

phoneType - one of VOICE, FAX, PAGER, MSG, CELL, VIDEO, BBS, MODEM, ISDN, PCS, PREF

phoneNum - phone number

getPhoneWork

public String getPhoneWork(String phoneType)

Get work phone number.

Parameters:

phoneType - one of VOICE, FAX, PAGER, MSG, CELL, VIDEO, BBS, MODEM, ISDN, PCS, PREF

Returns:

content of work phone number.

setAvatar

public void setAvatar(URL avatarURL)

Set the avatar for the VCard by specifying the url to the image.

Parameters:

avatarURL - the url to the image(png, jpeg, gif, bmp)

removeAvatar

public void removeAvatar()

Removes the avatar from the vCard. This is done by setting the PHOTO value to the empty string as defined in XEP-0153

setAvatar

public void setAvatar(byte[] bytes)

Specify the bytes of the JPEG for the avatar to use. If bytes is null, then the avatar will be removed. 'image/jpeg' will be used as MIME type.

Parameters:

bytes - the bytes of the avatar, or null to remove the avatar data

setAvatar

public void setAvatar(byte[] bytes,
 String mimeType)

Specify the bytes for the avatar to use as well as the mime type.

Parameters:

bytes - the bytes of the avatar.

mimeType - the mime type of the avatar.

setAvatar

public void setAvatar(String encodedImage,
 String mimeType)

Specify the Avatar used for this vCard.

Parameters:

encodedImage - the Base64 encoded image as String

mimeType - the MIME type of the image

setEncodedImage

@Deprecated
public void setEncodedImage(String encodedAvatar)

Deprecated.

Use setAvatar(String, String) instead.

Set the encoded avatar string. This is used by the provider.

Parameters:

encodedAvatar - the encoded avatar string.

getAvatar

public byte[] getAvatar()

Return the byte representation of the avatar(if one exists), otherwise returns null if no avatar could be found. Example 1

// Load Avatar from VCard
byte[] avatarBytes = vCard.getAvatar();

// To create an ImageIcon for Swing applications
ImageIcon icon = new ImageIcon(avatar);

// To create just an image object from the bytes
ByteArrayInputStream bais = new ByteArrayInputStream(avatar);
try {
  Image image = ImageIO.read(bais);
 }
 catch (IOException e) {
   e.printStackTrace();
}

Returns:

byte representation of avatar.

getAvatarMimeType

public String getAvatarMimeType()

Returns the MIME Type of the avatar or null if none is set.

Returns:

the MIME Type of the avatar or null

getBytes

public static byte[] getBytes(URL url)
                       throws IOException

Common code for getting the bytes of a url.

Parameters:

url - the url to read.

Returns:

bytes of the file pointed to by URL.

Throws:

IOException - if an IOException occurs while reading the file.

getAvatarHash

public String getAvatarHash()

Returns the SHA-1 Hash of the Avatar image.

Returns:

the SHA-1 Hash of the Avatar image.

save

@Deprecated
public void save(XMPPConnection connection)
          throws SmackException.NoResponseException,
XMPPException.XMPPErrorException,
SmackException.NotConnectedException,
InterruptedException

Deprecated.

use VCardManager.saveVCard(VCard) instead.

Save this vCard for the user connected by 'connection'. XMPPConnection should be authenticated and not anonymous.

Parameters:

connection - the XMPPConnection to use.

Throws:

XMPPException.XMPPErrorException - thrown if there was an issue setting the VCard in the server.

SmackException.NoResponseException - if there was no response from the server.

SmackException.NotConnectedException - if the XMPP connection is not connected.

InterruptedException - if the calling thread was interrupted.

load

@Deprecated
public void load(XMPPConnection connection)
          throws SmackException.NoResponseException,
XMPPException.XMPPErrorException,
SmackException.NotConnectedException,
InterruptedException

Deprecated.

use VCardManager.loadVCard() instead.

Load VCard information for a connected user. XMPPConnection should be authenticated and not anonymous.

Parameters:

connection - connection.

Throws:

XMPPException.XMPPErrorException - if there was an XMPP error returned.

SmackException.NoResponseException - if there was no response from the remote entity.

SmackException.NotConnectedException - if the XMPP connection is not connected.

InterruptedException - if the calling thread was interrupted.

load

@Deprecated
public void load(XMPPConnection connection,
 EntityBareJid user)
          throws SmackException.NoResponseException,
XMPPException.XMPPErrorException,
SmackException.NotConnectedException,
InterruptedException

Deprecated.

use VCardManager.loadVCard(EntityBareJid) instead.

Load VCard information for a given user. XMPPConnection should be authenticated and not anonymous.

Parameters:

connection - connection.

user - user whose information we want to load.

Throws:

XMPPException.XMPPErrorException - if there was an XMPP error returned.

SmackException.NoResponseException - if there was no response from the server.

SmackException.NotConnectedException - if the XMPP connection is not connected.

InterruptedException - if the calling thread was interrupted.

getIQChildElementBuilder

protected IQ.IQChildElementXmlStringBuilder getIQChildElementBuilder(IQ.IQChildElementXmlStringBuilder xml)

Description copied from class: IQ

This method must be overwritten by IQ subclasses to create their child content. It is important you don't use the builder to add the final end tag. This will be done automatically by IQ.IQChildElementXmlStringBuilder after eventual existing ExtensionElements have been added.

For example to create an IQ with a extra attribute and an additional child element

<iq to='foo@example.org' id='123'>
  <bar xmlns='example:bar' extraAttribute='blaz'>
     <extraElement>elementText</extraElement>
  </bar>
</iq>

the body of the getIQChildElementBuilder looks like

// The builder 'xml' will already have the child element and the 'xmlns' attribute added
// So the current builder state is "<bar xmlns='example:bar'"
xml.attribute("extraAttribute", "blaz");
xml.rightAngleBracket();
xml.element("extraElement", "elementText");
// Do not close the 'bar' attribute by calling xml.closeElement('bar')

If your IQ only contains attributes and no child elements, i.e. it can be represented as empty element, then you can mark it as such.

xml.attribute("myAttribute", "myAttributeValue");
xml.setEmptyElement();

If your IQ does not contain any attributes or child elements (besides ExtensionElements), consider sub-classing SimpleIQ instead.

Specified by:

getIQChildElementBuilder in class IQ

Parameters:

xml - a pre-created builder which already has the child element and the 'xmlns' attribute set.

Returns:

the build to create the IQ child content.

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object