SHOW Signed
 

net.rim.device.api.system
Class PersistentContent

java.lang.Object
  |
  +--net.rim.device.api.system.PersistentContent

public final class PersistentContent
extends Object

Allows a developer to encrypt and/or compress Strings and byte arrays. Data up to (2 ^ 31) - 1 bytes in length can be handled by this API.

This API was designed to allow applications to protect data in a database if the user has enabled Content Protection/Compression in their device's security settings. It consists of two main methods (encode and decode), as well as a number of helper methods.

encode encrypts and/or compresses a String or byte array into an encoded Object according to the device's security settings. Conversely, decode decrypts and/or decompresses an encoded Object back to its original form.

To encode an object:

    String data = "This is a secret.";
    // first compress and encrypt data
    Object encoding = PersistentContent.encode( data, true, true );
    ... // then persist encoding
 

To decode an object:

    try {
        ...
        data = PersistentContent.decodeString( encoding );
        ...
    } catch( IllegalStateException e ) {
        // unable to decode data; the device must be locked.
    }
 

Note that encoding can be performed anytime, whether the device is locked or unlocked. However, an object that was encoded using encryption can only be decoded if the device is unlocked. This can pose a problem if the device locks while an application is performing a potentially long operation during which it requires the ability to decode encrypted data, such as sorting encrypted records. In this case, the application can obtain a ticket. So long as a strong reference to a ticket exists, decoding encrypted data is allowed. Thus, applications should release tickets as soon as possible to allow the device to reach a locked and secure state.

Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:
JDE 4.0.0
See Also:
PersistentContentListener, PersistentContentException, PersistentStore, PersistentObject, RecordStore

Method Summary
 Category: Signed static void addListener(PersistentContentListener listener)
          Registers a persistent content listener.
 Category: Signed static void addWeakListener(PersistentContentListener listener)
          Registers a weak reference to a persistent content listener.
 Category: Signed static boolean checkEncoding(Object encoding)
          Determines if provided encoding is protected under the device's current Content Protection/Compression security settings.
 Category: Signed static boolean checkEncoding(Object encoding, boolean compress, boolean encrypt)
          Determines if provided encoding is protected according to the method parameters and the device's current Content Protection/Compression security settings.
 Category: Signed static Object convertByteArrayToEncoding(byte[] array)
          Converts a byte array back to an encoding.
 Category: Signed static byte[] convertEncodingToByteArray(Object encoding)
          Converts a PersistentContent encoding of an object into a byte array.
 Category: Signed static Object copyEncoding(Object encoding)
          Retrieves a copy of an encoded object.
 Category: Signed static Object decode(Object content)
          Decodes (i.e., decrypts and/or decompresses) data.
 Category: Signed static Object decode(Object content, boolean firstBlockOnly)
          Decodes (i.e., decrypts and/or decompresses) portion of data object.
 Category: Signed static byte[] decodeByteArray(Object content)
          Decodes (i.e., decrypts and/or decompresses) byte array.
 Category: Signed static byte[] decodeByteArray(Object content, boolean firstBlockOnly)
          Decodes (i.e., decrypts and/or decompresses) portion of byte array.
 Category: Signed static String decodeString(Object content)
          Decodes (i.e., decrypts and/or decompresses) a string.
 Category: Signed static String decodeString(Object content, boolean firstBlockOnly)
          Decodes (i.e., decrypts and/or decompresses) portion of string.
 Category: Signed static Object encode(byte[] data)
          Encrypts and/or compresses a byte array according to the Content Protection/Compression security settings on the device.
 Category: Signed static Object encode(byte[] data, boolean compress, boolean encrypt)
          Encrypts and/or compresses a byte array according to the method parameters and the current Content Protection/Compression security settings on the device.
 Category: Signed static Object encode(byte[] data, int offset, int length, boolean compress, boolean encrypt)
          Encrypts and/or compresses a portion of a byte array according to the method parameters and the current Content Protection/Compression security settings on the device.
 Category: Signed static Object encode(String string)
          Encrypts and/or compresses a string according to the Content Protection/Compression security settings on the device.
 Category: Signed static Object encode(String string, boolean compress, boolean encrypt)
          Encrypts and/or compresses a string according to the method parameters and the current Content Protection/Compression security settings on the device.
 Category: Signed static Object encode(String string, int index, int length, boolean compress, boolean encrypt)
          Encrypts and/or compresses a sub-string according to the method parameters and the current Content Protection/Compression security settings on the device.
 Category: Signed static Object encodeAndAppend(byte[] data, boolean compress, boolean encrypt, Object content)
          Encrypts and/or compresses a byte array according to the method parameters and the current Content Protection/Compression security settings on the device, and appends it to provided content.
 Category: Signed static Object encodeAndAppend(byte[] data, int offset, int length, boolean compress, boolean encrypt, Object content)
          Encrypts and/or compresses the portion of a byte array according to the method parameters and the current Content Protection/Compression security settings on the device, and appends it to provided content.
 Category: Signed static Object encodeAndAppend(byte[] data, Object content)
          Encrypts and/or compresses a byte array according to the Content Protection/Compression security settings on the device, and appends it to provided content.
 Category: Signed static Object encodeAndAppend(String string, boolean compress, boolean encrypt, Object content)
          Encrypts and/or compresses string according to the method parameters and the current Content Protection/Compression security settings on the device, and appends to provided content.
 Category: Signed static Object encodeAndAppend(String string, int index, int length, boolean compress, boolean encrypt, Object content)
          Encrypts and/or compresses a sub-string according to the method parameters and the current Content Protection/Compression security settings on the device, and appends to provided content.
 Category: Signed static Object encodeAndAppend(String string, Object content)
          Encrypts and/or compresses a string according to the Content Protection/Compression security settings on the device, and appends to provided content.
 Category: Signed static Object encodeObject(Object obj)
          Encrypts and/or compresses an arbitrary object according to the current Content Protection/Compression security settings on the device.
 Category: Signed static Object encodeObject(Object obj, boolean compress, boolean encrypt)
          Encrypts and/or compresses an arbitrary object according to the method parameters and the current Content Protection/Compression security settings on the device.
 Category: Signed static int getLength(Object encoding)
          Determines what the length of the encoding will be once it has been decoded.
 Category: Signed static int getLockGeneration()
          Retrieves a counter that changes every time the user locks or unlocks their device.
 Category: Signed static int getModeGeneration()
          Retrieves a counter that changes every time the user has changed their Content Protection settings.
 Category: Signed static int getState()
          Retrieves the state of the device.
 Category: Signed static Object getTicket()
          Retrieves decryption ticket.
 Category: Signed static boolean isByteArray(Object encoding)
          Determines whether or not the provided encoding represents a byte array.
 Category: Signed static boolean isCompressed(Object encoding)
          Determines whether or not the provided encoding is a compressed string or byte array.
 Category: Signed static boolean isCompressionEnabled()
          Determines if Content Compression is enabled by the user.
 Category: Signed static boolean isContentProtectionSupported()
          Determines whether or not Content Protection is supported by this device.
 Category: Signed static boolean isEncrypted(Object encoding)
          Determines whether or not the provided encoding is an encrypted string or byte array.
 Category: Signed static boolean isEncryptionEnabled()
          Determines if Content Encryption (i.e., Content Protection) is currently enabled by the user.
 Category: Signed static boolean isSecure()
          Determines whether or not the device is secure, i.e., locked with no tickets held, so decoding encrypted data is not allowed.
 Category: Signed static boolean isString(Object encoding)
          Determines whether or not the provided encoding represents a string.
 Category: Signed static boolean isTicketInUse()
          Determines whether or not a ticket is still in use.
 Category: Signed static void markAsPlaintext(Object object)
          Marks the provided object as plaintext (i.e., not encrypted).
 Category: Signed static Object reEncode(Object encoding)
          Re-encodes an object according to the device's current Content Protection/Compression security settings.
 Category: Signed static Object reEncode(Object encoding, boolean compress, boolean encrypt)
          Re-encodes an object according to the method parameters and the device's current Content Protection/Compression security settings.
 Category: Signed static void removeListener(PersistentContentListener listener)
          Removes a persistent content listener.
 Category: Signed static void requestReEncode()
          Requests that all registered PersistentContentListeners re-encode their data.
 Category: Signed static Object waitForTicket()
          Blocks and waits to retrieve a decryption ticket.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

addListener

public static void addListener(PersistentContentListener listener)
Registers a persistent content listener.

This method registers a strong reference to the provided listener so that it will not be garbage collected.

Parameters:
listener - Listener to add.
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

addWeakListener

public static void addWeakListener(PersistentContentListener listener)
Registers a weak reference to a persistent content listener.

This method registers a weak reference to the provided listener; thus, you must keep a reference to the listener to prevent it from being garbage collected.

Parameters:
listener - The listener to add.
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

checkEncoding

public static boolean checkEncoding(Object encoding)
Determines if provided encoding is protected under the device's current Content Protection/Compression security settings.

Use this method to determine if the provided encoding is protected under the device's current Content Protection/Compression security settings. If not, the encoding should be re-encoded.

Parameters:
encoding - Encoding to check.
Returns:
True if the encoding is protected and its encoding is consistent with the device's current settings; otherwise false, and the encoding should be re-encoded with reEncode(java.lang.Object).
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

checkEncoding

public static boolean checkEncoding(Object encoding,
                                    boolean compress,
                                    boolean encrypt)
Determines if provided encoding is protected according to the method parameters and the device's current Content Protection/Compression security settings. For example, if the encrypt parameter is true and Content Protection is enabled on the device, this method verifies that the encoding is encrypted.

Use this method to determine if the provided encoding is protected according to the method parameters and the device's current Content Protection/Compression security settings. If not, the encoding should be re-encoded.

Parameters:
encoding - Encoding to check.
compress - Compression setting to use.
encrypt - Encryption setting to use.
Returns:
True if the encoding is protected according to the method parameters and the device's current Content Protection/Compression security settings; otherwise false, and the encoding should be re-encoded with reEncode(java.lang.Object).
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

convertByteArrayToEncoding

public static Object convertByteArrayToEncoding(byte[] array)
Converts a byte array back to an encoding.
Parameters:
array - Byte array that contains an encoding, as returned by convertEncodingToByteArray(java.lang.Object).
Returns:
An encoding that can be passed to decode(java.lang.Object).
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

convertEncodingToByteArray

public static byte[] convertEncodingToByteArray(Object encoding)
Converts a PersistentContent encoding of an object into a byte array.

This method can be used to serialize an encoded object to a byte array, e.g., for storage in an RMS database, or to ensure that backed up data can only be restored to the same device.

Parameters:
encoding - Encoding to convert.
Returns:
Byte array that contains the encoding.
Since:
JDE 4.0.0
See Also:
convertByteArrayToEncoding(byte[])
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

copyEncoding

public static Object copyEncoding(Object encoding)
Retrieves a copy of an encoded object.

Parameters:
encoding - The encoded object to be copied.
Returns:
Copy of the encoded object.
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

decode

public static Object decode(Object content)
Decodes (i.e., decrypts and/or decompresses) data.

Parameters:
content - Data object to decode.
Returns:
Decoded data.
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

decode

public static Object decode(Object content,
                            boolean firstBlockOnly)
Decodes (i.e., decrypts and/or decompresses) portion of data object.

Parameters:
content - Data object to decode.
firstBlockOnly - If true, decode only first block of data; otherwise, decode entire data object.
Returns:
Decoded data object, or first block of object.
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

decodeByteArray

public static byte[] decodeByteArray(Object content)
Decodes (i.e., decrypts and/or decompresses) byte array.

Parameters:
content - Data object to decode.
Returns:
Decoded byte array.
Throws:
ClassCastException - thrown if the decoded object is not a byte array.
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

decodeByteArray

public static byte[] decodeByteArray(Object content,
                                     boolean firstBlockOnly)
Decodes (i.e., decrypts and/or decompresses) portion of byte array.

Parameters:
content - Data object to decode.
firstBlockOnly - If true, decode only first block of data; otherwise, decode entire data object.
Returns:
Decoded byte array, or first block of array.
Throws:
ClassCastException - thrown if the decoded object is not a byte array.
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

decodeString

public static String decodeString(Object content)
Decodes (i.e., decrypts and/or decompresses) a string.

Parameters:
content - Data object to decode.
Returns:
Decoded string.
Throws:
ClassCastException - thrown if the decoded object is not a String.
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

decodeString

public static String decodeString(Object content,
                                  boolean firstBlockOnly)
Decodes (i.e., decrypts and/or decompresses) portion of string.

Parameters:
content - Data object to decode.
firstBlockOnly - If true, decode only first block of data; otherwise, decode entire data object.
Returns:
Decoded string, or first block of string.
Throws:
ClassCastException - thrown if the decoded object is not a String.
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

encode

public static Object encode(byte[] data)
Encrypts and/or compresses a byte array according to the Content Protection/Compression security settings on the device.
Parameters:
data - Data to encrypt and/or compress.
Returns:
Encrypted and/or compressed data.
Throws:
IllegalArgumentException - if the data to be encoded is larger that what is supported by Content Protection
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

encode

public static Object encode(byte[] data,
                            boolean compress,
                            boolean encrypt)
Encrypts and/or compresses a byte array according to the method parameters and the current Content Protection/Compression security settings on the device. For example, in order to encrypt data, the encrypt parameter must be true and Content Protection must be enabled on the device.

For an object to be compressed, its size must be greater than or equal to 32 bytes. An empty byte array cannot be encrypted.

Parameters:
data - Data to encrypt and/or compress.
compress - If true, this method compresses data; otherwise, no compression performed.
encrypt - If true, this method encrypts data; otheriwse, no encryption performed.
Returns:
Encrypted and/or compressed data.
Throws:
IllegalArgumentException - if the data to be encoded is larger that what is supported by Content Protection
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

encode

public static Object encode(byte[] data,
                            int offset,
                            int length,
                            boolean compress,
                            boolean encrypt)
Encrypts and/or compresses a portion of a byte array according to the method parameters and the current Content Protection/Compression security settings on the device. For example, in order to encrypt data, the encrypt parameter must be true and Content Protection must be enabled on the device.

For an object to be compressed, its size must be greater than or equal to 32 bytes. An empty byte array cannot be encrypted.

Parameters:
data - Data to encrypt and/or compress.
offset - First byte in data to encrypt and/or compress.
length - Number of bytes from data to encrypt and/or compress (-1 means the rest of the array).
compress - If true, this method compresses data; otherwise, no compression performed.
encrypt - If true, this method encrypts data; otherwise, no encryption performed.
Returns:
Encrypted and/or compressed byte array.
Throws:
IllegalArgumentException - if the data to be encoded is larger that what is supported by Content Protection
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

encode

public static Object encode(String string)
Encrypts and/or compresses a string according to the Content Protection/Compression security settings on the device.
Parameters:
string - String to encrypt and/or compress.
Returns:
Encrypted and/or compressed string.
Throws:
IllegalArgumentException - if the data to be encoded is larger that what is supported by Content Protection
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

encode

public static Object encode(String string,
                            boolean compress,
                            boolean encrypt)
Encrypts and/or compresses a string according to the method parameters and the current Content Protection/Compression security settings on the device. For example, in order to encrypt data, the encrypt parameter must be true and Content Protection must be enabled on the device.

For an object to be compressed, its size must be greater than or equal to 32 bytes. An empty string cannot be encrypted.

Parameters:
string - String to encrypt and/or compress.
compress - If true, this method compresses string; otherwise, no compression performed.
encrypt - If true, this method encrypts string; otherwise, no encrpytion performed.
Returns:
Encrypted and/or compressed string.
Throws:
IllegalArgumentException - if the data to be encoded is larger that what is supported by Content Protection
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

encode

public static Object encode(String string,
                            int index,
                            int length,
                            boolean compress,
                            boolean encrypt)
Encrypts and/or compresses a sub-string according to the method parameters and the current Content Protection/Compression security settings on the device. For example, in order to encrypt data, the encrypt parameter must be true and Content Protection must be enabled on the device.

For an object to be compressed, its size must be greater than or equal to 32 bytes. An empty string cannot be encrypted.

Parameters:
string - String to provide source of sub-string to encrypt and/or compress.
index - First character in string to encrypt and/or compress.
length - Number of characters from string to encrypt and/or compress (-1 means the rest of the string).
compress - If true, this method compresses sub-string; otherwise, no compression performed.
encrypt - If true, this method encrypts sub-string; otherwise, no encryption performed.
Returns:
Encrypted and/or compressed sub-string.
Throws:
IllegalArgumentException - if the data to be encoded is larger that what is supported by Content Protection
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

encodeAndAppend

public static Object encodeAndAppend(byte[] data,
                                     boolean compress,
                                     boolean encrypt,
                                     Object content)
Encrypts and/or compresses a byte array according to the method parameters and the current Content Protection/Compression security settings on the device, and appends it to provided content. For example, in order to encrypt data, the encrypt parameter must be true and Content Protection must be enabled on the device. An empty byte array cannot be encrypted.
Parameters:
data - Data to encrypt and/or compress.
compress - If true, this method compresses data; otherwise, no compression performed.
encrypt - If true, this method encrypts data; otherwise, no encryption performed.
content - Content object to which to append encrypted and/or compressed data.
Returns:
Original content with encrypted and/or compressed byte array appended.
Throws:
IllegalArgumentException - if the data to be encoded is larger that what is supported by Content Protection
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

encodeAndAppend

public static Object encodeAndAppend(byte[] data,
                                     int offset,
                                     int length,
                                     boolean compress,
                                     boolean encrypt,
                                     Object content)
Encrypts and/or compresses the portion of a byte array according to the method parameters and the current Content Protection/Compression security settings on the device, and appends it to provided content. For example, in order to encrypt data, the encrypt parameter must be true and Content Protection must be enabled on the device. An empty byte array cannot be encrypted.
Parameters:
data - data to encrypt and/or compress
offset - first byte in data to encrypt and/or compress
length - number of bytes from data to encrypt and/or compress; -1 means the rest of the array
compress - if true this method compresses data; otherwise, no compression performed
encrypt - if true this method encrypts data; otherwise, no encryption performed
content - content object to which to append encrypted and/or compressed data; must be a byte or char array
Returns:
original content with encrypted and/or compressed byte array appended
Throws:
IllegalArgumentException - if an illegal or inappropriate argument has been specified
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

encodeAndAppend

public static Object encodeAndAppend(byte[] data,
                                     Object content)
Encrypts and/or compresses a byte array according to the Content Protection/Compression security settings on the device, and appends it to provided content.
Parameters:
data - Data to encrypt and/or compress.
content - Content object to which to append encrypted and/or compressed data.
Returns:
Original content with encrypted and/or compressed byte array appended.
Throws:
IllegalArgumentException - if the data to be encoded is larger that what is supported by Content Protection
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

encodeAndAppend

public static Object encodeAndAppend(String string,
                                     boolean compress,
                                     boolean encrypt,
                                     Object content)
Encrypts and/or compresses string according to the method parameters and the current Content Protection/Compression security settings on the device, and appends to provided content. For example, in order to encrypt data, the encrypt parameter must be true and Content Protection must be enabled on the device. An empty string cannot be encrypted.
Parameters:
string - String to encrypt and/or compress.
compress - If true, this method compresses string; otherwise, no compression performed.
encrypt - If true, this method encrypts string; otherwise, no encrpytion performed.
content - Content object to which to append encrypted and/or compressed string.
Returns:
Original content with encrypted and/or compressed string appended.
Throws:
IllegalArgumentException - if the data to be encoded is larger that what is supported by Content Protection
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

encodeAndAppend

public static Object encodeAndAppend(String string,
                                     int index,
                                     int length,
                                     boolean compress,
                                     boolean encrypt,
                                     Object content)
Encrypts and/or compresses a sub-string according to the method parameters and the current Content Protection/Compression security settings on the device, and appends to provided content. For example, in order to encrypt data, the encrypt parameter must be true and Content Protection must be enabled on the device. An empty string cannot be encrypted.
Parameters:
string - String to provide source of sub-string to encrypt and/or compress.
index - First character in string to encrypt and/or compress.
length - Number of characters from string to encrypt and/or compress (-1 means the rest of the string).
compress - If true, this method compresses string; otherwise, no compression performed.
encrypt - If true, this method encrypts string; otherwise, no encryption performed.
content - Content object to which to append encrypted and/or compressed string.
Returns:
Original content with encrypted and/or compressed sub-string appended.
Throws:
IllegalArgumentException - if an illegal or inappropriate argument has been specified
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

encodeAndAppend

public static Object encodeAndAppend(String string,
                                     Object content)
Encrypts and/or compresses a string according to the Content Protection/Compression security settings on the device, and appends to provided content.
Parameters:
string - String to encrypt and/or compress.
content - Content object to which to append encrypted and/or compressed string.
Returns:
Original content with encrypted and/or compressed string appended.
Throws:
IllegalArgumentException - if the data to be encoded is larger that what is supported by Content Protection
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

encodeObject

public static Object encodeObject(Object obj)
Encrypts and/or compresses an arbitrary object according to the current Content Protection/Compression security settings on the device. Note that only Strings and byte arrays are actually encoded.

Parameters:
obj - Object to encrypt and/or compress.
Returns:
Encrypted and/or compressed object.
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

encodeObject

public static Object encodeObject(Object obj,
                                  boolean compress,
                                  boolean encrypt)
Encrypts and/or compresses an arbitrary object according to the method parameters and the current Content Protection/Compression security settings on the device. For example, in order to encrypt data, the encrypt parameter must be true and Content Protection must be enabled on the device. Note that only Strings and byte arrays are actually encoded. An empty string or byte array cannot be encrypted.

Parameters:
obj - Object to encrypt and/or compress.
compress - If true, this method compresses the object; otherwise, no compression performed.
encrypt - If true, this method encrypts the object; otherwise, no encryption performed.
Returns:
Encrypted and/or compressed string.
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

getLength

public static int getLength(Object encoding)
Determines what the length of the encoding will be once it has been decoded.

If encoding is actually a string, then this method just returns String.length(). If encoding is actually a byte array, then this method just returns the number of byte elements in the array.

Parameters:
encoding - Encoding to measure.
Returns:
Length of the decoded encoding.
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

getLockGeneration

public static int getLockGeneration()
Retrieves a counter that changes every time the user locks or unlocks their device.

The value returned by this method should be considered for comparison purposes only. That is, comparing the return value to a previously returned value lets the caller know whether the device has locked or unlocked since the previous call. If the values are different, then the device has locked and/or unlocked. This is used mainly as an optimization technique, allowing an application to abort a long encoding/decoding operation, because the device has locked/unlocked, and it will have to be undone anyway.

Returns:
A counter that can be compared to previously returned values that will indicate if the device has locked or unlocked since the last call.
Since:
JDE 4.0.0
See Also:
PersistentContentListener.persistentContentStateChanged(int)
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

getModeGeneration

public static int getModeGeneration()
Retrieves a counter that changes every time the user has changed their Content Protection settings.

The value returned by this method should be considered for comparison purposes only. That is, comparing the return value to a previously returned value lets the caller know whether the Content Protection settings have changed since the previous call. If the values are different, then the Content Protection settings have changed. This is used mainly as an optimization technique, allowing an application to abort a long encoding/decoding operation, because the Content Protection settings have changed and it will need to be done again anyway.

Returns:
A counter that can be compared to previously returned values that will indicate if the Content Protection settings have changed since the last call.
Since:
JDE 4.0.0
See Also:
PersistentContentListener.persistentContentModeChanged(int)
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

getState

public static int getState()
Retrieves the state of the device.
Returns:
Value expressing the device's state.
Since:
JDE 4.0.0
See Also:
PersistentContentListener
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

getTicket

public static Object getTicket()
Retrieves decryption ticket.

If the device is currently unlocked, this method retrieves a ticket that the caller can use to decode encrypted data, for as long as the ticket is strongly referenced. This guarantees access to encrypted data even if the device locks while the caller is performing a potentially long operation, such as sorting.

Note: please release all references to the returned ticket as soon as possible, as it poses a possible security hazard if held indefinitely.

Returns:
Ticket object, or null if the device is locked.
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

isByteArray

public static boolean isByteArray(Object encoding)
Determines whether or not the provided encoding represents a byte array.

Parameters:
encoding - Encoding to test.
Returns:
True if encoding represents a byte array; otherwise, false.
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

isCompressed

public static boolean isCompressed(Object encoding)
Determines whether or not the provided encoding is a compressed string or byte array. For an object to be compressed, its size must be greater than or equal to 32 bytes.

Parameters:
encoding - Encoding to test.
Returns:
True if encoding is a compressed string or byte array; otherwise, false.
Since:
JDE 4.1.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

isCompressionEnabled

public static boolean isCompressionEnabled()
Determines if Content Compression is enabled by the user.
Returns:
True if Content Compression is currently enabled; otherwise, false.
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

isContentProtectionSupported

public static boolean isContentProtectionSupported()
Determines whether or not Content Protection is supported by this device.
Returns:
True if Content Protection is supported; otherwise, false.
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

isEncrypted

public static boolean isEncrypted(Object encoding)
Determines whether or not the provided encoding is an encrypted string or byte array. Byte arrays of length 0 and empty strings (string ="") cannot be encrypted.

Parameters:
encoding - Encoding to test.
Returns:
True if encoding is an encrypted string or byte array. Returns false if encoding is a byte array of length 0 or an empty string.
Since:
JDE 4.1.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

isEncryptionEnabled

public static boolean isEncryptionEnabled()
Determines if Content Encryption (i.e., Content Protection) is currently enabled by the user.
Returns:
True if Content Encryption (i.e., Content Protection) is currently enabled; otherwise, false.
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

isSecure

public static boolean isSecure()
Determines whether or not the device is secure, i.e., locked with no tickets held, so decoding encrypted data is not allowed.
Returns:
True if the device supports Content Protection and is secure; otherwise, false.
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

isString

public static boolean isString(Object encoding)
Determines whether or not the provided encoding represents a string.

Parameters:
encoding - Encoding to test.
Returns:
True if encoding represents a string; otherwise, false.
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

isTicketInUse

public static boolean isTicketInUse()
Determines whether or not a ticket is still in use. If a ticket remains strongly referenced, the device will not be secure because decoding encrypted data is allowed.
Returns:
True if a ticket is still referenced; otherwise, false.
Since:
JDE 4.0.2
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

markAsPlaintext

public static void markAsPlaintext(Object object)
Marks the provided object as plaintext (i.e., not encrypted).
Parameters:
object - The object to be marked as plaintext.
Since:
JDE 4.0.2
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

reEncode

public static Object reEncode(Object encoding)
Re-encodes an object according to the device's current Content Protection/Compression security settings.
Parameters:
encoding - Encoding to re-encode.
Returns:
Re-encoded object.
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

reEncode

public static Object reEncode(Object encoding,
                              boolean compress,
                              boolean encrypt)
Re-encodes an object according to the method parameters and the device's current Content Protection/Compression security settings. For example, if the encrypt parameter is true and Content Protection is enabled on the device, this method ensures that the encoding is encrypted.
Parameters:
encoding - Encoding to re-encode.
compress - Compression setting to use.
encrypt - Encryption setting to use.
Returns:
Re-encoded object.
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

removeListener

public static void removeListener(PersistentContentListener listener)
Removes a persistent content listener.
Parameters:
listener - Listener to remove.
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

requestReEncode

public static void requestReEncode()
Requests that all registered PersistentContentListeners re-encode their data. This method should be called if the application wants to enable or disable the use of encryption on a field. For example, the user may have changed an option that requires some data to be available in plaintext format while the device is locked. Calling requestReEncode after changing such an option should force the required field to be re-encoded with encryption disabled, thus allowing access to it while the device is locked.
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

waitForTicket

public static Object waitForTicket()
Blocks and waits to retrieve a decryption ticket.

This method behaves like getTicket(), except that if the device is locked, it waits for the device to unlock and then returns the ticket.

Returns:
Ticket object.
Since:
JDE 4.0.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.



Copyright 1999-2008 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.