ezvcard.types
Class KeyType

java.lang.Object
  ezvcard.types.VCardType
      ezvcard.types.BinaryType<KeyTypeParameter>
          ezvcard.types.KeyType

All Implemented Interfaces:

Comparable<VCardType>

public class KeyType
extends BinaryType<KeyTypeParameter>

A public key for encryption.

Adding a key

 VCard vcard = new VCard();
 
 //URL (vCard 4.0 only; KEYs cannot have URLs in vCard 2.1 and 3.0)
 KeyType key = new KeyType("http://www.mywebsite.com/pubkey.pgp", KeyTypeParameter.PGP);
 vcard.addKey(key);
 
 //binary data
 byte data[] = ...
 key = new KeyType(data, KeyTypeParameter.PGP);
 vcard.addKey(key);
 
 //plain text value
 key = new KeyType();
 key.setText("...", KeyTypeParameter.PGP);
 vcard.addKey(key);
 
 //if "KeyTypeParameter" does not have the pre-defined constant that you need, then create a new instance
 //arg 1: the value of the 2.1/3.0 TYPE parameter
 //arg 2: the value to use for the 4.0 MEDIATYPE parameter and for 4.0 data URIs
 //arg 3: the file extension of the data type (optional)
 KeyTypeParameter param = new KeyTypeParameter("mykey", "application/my-key", "mkey");
 key = new KeyType("http://www.mywebsite.com/pubkey.enc", param);
 vcard.addKey(key);
 

Getting the keys

 VCard vcard = ...
 
 int fileCount = 0;
 for (KeyType key : vcard.getKeys()){
   //the key will have either a URL or a binary data
   //only 4.0 vCards are allowed to use URLs for keys
   if (key.getData() == null){
     System.out.println("Key URL: " + key.getUrl());
   } else {
     KeyTypeParameter type = key.getContentType();
     
     if (type == null) {
       //the vCard may not have any content type data associated with the key
       System.out.println("Saving a key file...");
     } else {
       System.out.println("Saving a \"" + type.getMediaType() + "\" file...");
     }
     
     String folder;
     if (type == KeyTypeParameter.PGP){ //it is safe to use "==" instead of "equals()"
       folder = "pgp-keys";
     } else {
       folder = "other-keys";
     }
     
     byte data[] = key.getData();
     String filename = "key" + fileCount;
     if (type != null && type.getExtension() != null){
        filename += "." + type.getExtension();
     }
     OutputStream out = new FileOutputStream(new File(folder, filename));
     out.write(data);
     out.close();
     fileCount++;
   }
 }
 

vCard property name: KEY

vCard versions: 2.1, 3.0, 4.0

Author:

Michael Angstadt

Field Summary

static String

NAME

Fields inherited from class ezvcard.types.BinaryType

contentType, data, url

Fields inherited from class ezvcard.types.VCardType

group, subTypes, typeName

Constructor Summary

KeyType()

KeyType(byte[] data, KeyTypeParameter type)

KeyType(File file, KeyTypeParameter type)

KeyType(InputStream in, KeyTypeParameter type)

KeyType(String url, KeyTypeParameter type)

Method Summary

protected KeyTypeParameter	buildMediaTypeObj(String mediaType) Builds a MediaTypeParameter object based on the information in the MEDIATYPE parameter or data URI of 4.0 vCards.
protected KeyTypeParameter	buildTypeObj(String type) Builds a MediaTypeParameter object based on the value of the TYPE parameter in 2.1/3.0 vCards.
protected void	cannotUnmarshalValue(String value, VCardVersion version, List<String> warnings, CompatibilityMode compatibilityMode, KeyTypeParameter contentType) Called if the unmarshalling code cannot determine how to unmarshal the value.
protected void	doMarshalSubTypes(VCardSubTypes copy, VCardVersion version, List<String> warnings, CompatibilityMode compatibilityMode, VCard vcard) Gets the sub types that will be sent over the wire.
protected void	doMarshalText(StringBuilder sb, VCardVersion version, List<String> warnings, CompatibilityMode compatibilityMode) Converts this type object to a string for sending over the wire.
protected void	doMarshalXml(XCardElement parent, List<String> warnings, CompatibilityMode compatibilityMode) Marshals this type for inclusion in an xCard (XML document).
protected void	doUnmarshalHtml(HCardElement element, List<String> warnings) Unmarshals the type from an hCard (HTML document).
protected void	doUnmarshalXml(XCardElement element, List<String> warnings, CompatibilityMode compatibilityMode) Unmarshals the type from an xCard (XML document).
String	getText() Gets the plain text representation of the key.
void	setText(String text, KeyTypeParameter type) Sets a plain text representation of the key.

Methods inherited from class ezvcard.types.BinaryType

addPid, doUnmarshalText, getAltId, getContentType, getData, getPids, getPref, getType, getUrl, removePids, setAltId, setContentType, setData, setPref, setType, setUrl

Methods inherited from class ezvcard.types.VCardType

compareTo, getGroup, getQName, getSubTypes, getSupportedVersions, getTypeName, marshalSubTypes, marshalText, marshalXml, setGroup, unmarshalHtml, unmarshalText, unmarshalXml

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NAME

public static final String NAME

See Also:

Constant Field Values

Constructor Detail

KeyType

public KeyType()

KeyType

public KeyType(byte[] data,
               KeyTypeParameter type)

Parameters:

data - the binary data

type - the type of key (e.g. PGP)

KeyType

public KeyType(String url,
               KeyTypeParameter type)

Parameters:

url - the URL to the key (vCard 4.0 only)

type - the type of key (e.g. PGP)

KeyType

public KeyType(InputStream in,
               KeyTypeParameter type)
        throws IOException

Parameters:

in - an input stream to the binary data (will be closed)

type - the content type (e.g. PGP)

Throws:

IOException - if there's a problem reading from the input stream

KeyType

public KeyType(File file,
               KeyTypeParameter type)
        throws IOException

Parameters:

file - the key file

type - the content type (e.g. PGP)

Throws:

IOException - if there's a problem reading from the file

Method Detail

setText

public void setText(String text,
                    KeyTypeParameter type)

Sets a plain text representation of the key.

Parameters:

text - the key in plain text

type - the key type

getText

public String getText()

Gets the plain text representation of the key.

Returns:

the key in plain text

buildTypeObj

protected KeyTypeParameter buildTypeObj(String type)

Description copied from class: BinaryType

Builds a MediaTypeParameter object based on the value of the TYPE parameter in 2.1/3.0 vCards.

Specified by:

buildTypeObj in class BinaryType<KeyTypeParameter>

Parameters:

type - the TYPE value

Returns:

the parameter object

buildMediaTypeObj

protected KeyTypeParameter buildMediaTypeObj(String mediaType)

Description copied from class: BinaryType

Builds a MediaTypeParameter object based on the information in the MEDIATYPE parameter or data URI of 4.0 vCards.

Specified by:

buildMediaTypeObj in class BinaryType<KeyTypeParameter>

Parameters:

mediaType - the media type string (e.g. "image/jpeg")

Returns:

the parameter object

doMarshalSubTypes

protected void doMarshalSubTypes(VCardSubTypes copy,
                                 VCardVersion version,
                                 List<String> warnings,
                                 CompatibilityMode compatibilityMode,
                                 VCard vcard)

Description copied from class: VCardType

Gets the sub types that will be sent over the wire.

If this method is NOT overridden, then the type's sub types will be sent over the wire as-is. In other words, whatever is in the VCardType.subTypes field will be sent. Child classes can override this method in order to modify the sub types before they are marshalled.

Overrides:

doMarshalSubTypes in class BinaryType<KeyTypeParameter>

Parameters:

copy - the sub types that will be marshalled into the vCard. This object is a copy of the VCardType.subTypes field, so any modifications done to this object will not effect the state of the field.

version - the version vCard that is being generated

warnings - allows the programmer to alert the user to any note-worthy (but non-critical) issues that occurred during the marshalling process

compatibilityMode - allows the programmer to customize the marshalling process depending on the expected consumer of the vCard

vcard - the VCard object that is being marshalled

doMarshalText

protected void doMarshalText(StringBuilder sb,
                             VCardVersion version,
                             List<String> warnings,
                             CompatibilityMode compatibilityMode)

Description copied from class: VCardType

Converts this type object to a string for sending over the wire. It is NOT responsible for folding.

Overrides:

doMarshalText in class BinaryType<KeyTypeParameter>

Parameters:

sb - the buffer to add the marshalled value to

version - the version vCard that is being generated

warnings - allows the programmer to alert the user to any note-worthy (but non-critical) issues that occurred during the marshalling process

compatibilityMode - allows the programmer to customize the marshalling process depending on the expected consumer of the vCard

doMarshalXml

protected void doMarshalXml(XCardElement parent,
                            List<String> warnings,
                            CompatibilityMode compatibilityMode)

Description copied from class: VCardType

Marshals this type for inclusion in an xCard (XML document). All child classes SHOULD override this, but are not required to.

Overrides:

doMarshalXml in class BinaryType<KeyTypeParameter>

Parameters:

parent - the XML element that the type's value will be inserted into. For example, this would be the "<fn>" element for the "FN" type.

warnings - allows the programmer to alert the user to any note-worthy (but non-critical) issues that occurred during the marshalling process

compatibilityMode - allows the programmer to customize the marshalling process depending on the expected consumer of the vCard

doUnmarshalXml

protected void doUnmarshalXml(XCardElement element,
                              List<String> warnings,
                              CompatibilityMode compatibilityMode)

Description copied from class: VCardType

Unmarshals the type from an xCard (XML document).

Overrides:

doUnmarshalXml in class BinaryType<KeyTypeParameter>

Parameters:

element - the XML element that contains the type data. For example, this would be the "<fn>" element for the "FN" type. This object will NOT include the "<parameters>" child element (it is removed after being unmarshalled into a VCardSubTypes object).

warnings - allows the programmer to alert the user to any note-worthy (but non-critical) issues that occurred during the unmarshalling process

compatibilityMode - allows the programmer to customize the unmarshalling process depending on where the vCard came from

doUnmarshalHtml

protected void doUnmarshalHtml(HCardElement element,
                               List<String> warnings)

Description copied from class: VCardType

Unmarshals the type from an hCard (HTML document).

Overrides:

doUnmarshalHtml in class BinaryType<KeyTypeParameter>

Parameters:

element - the HTML element that contains the type data.

warnings - allows the programmer to alert the user to any note-worthy (but non-critical) issues that occurred during the unmarshalling process

cannotUnmarshalValue

protected void cannotUnmarshalValue(String value,
                                    VCardVersion version,
                                    List<String> warnings,
                                    CompatibilityMode compatibilityMode,
                                    KeyTypeParameter contentType)

Description copied from class: BinaryType

Called if the unmarshalling code cannot determine how to unmarshal the value.

Overrides:

cannotUnmarshalValue in class BinaryType<KeyTypeParameter>

Parameters:

value - the value

version - the version of the vCard

warnings - the warnings

compatibilityMode - the compatibility mode

contentType - the content type of the resource of null if unknown