|
Eclipse Platform Release 3.4 |
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
This interface describes functionality provided by secure preferences. Secure preferences can be used to persist sensitive information in an encrypted form.
Logically, secure preferences combine functionality of a keyring (keystore) and
Preferences
.
For an excellent detailed description of the preferences functionality see
Preferences
. To recap in a short form, preferences
provide a tree. Nodes on that tree can be used to specify context. For instance,
root node could have a child node called "cvs" to store information related to CVS
integration.
Each node can have a map of keys with associated values. For instance, to store password for the CVS repository located on eclipse.org we could use the following code:
ISecurePreferences root = SecurePreferencesFactory.getDefault(); ISecurePreferences node = root.node("cvs/eclipse.org"); node.put("password", myPassword, true);
This interface has the following differences from the Preferences
:
On the keyring side, when adding a key to the node, you can ask framework to encrypt it. Framework will lazily acquire password from password provider and use it to encrypt all new entries added to the secure preferences tree in this session.
It is worthwhile to reiterate that same limitations as Preferences
apply to the node names. One non-trivial limitation is that node names can not contain forward
slashes. For convenience, utility methods EncodingUtils.encodeSlashes(String)
and
EncodingUtils.decodeSlashes(String)
are provided to work around this limitation.
Also note that secure preferences only intended to store relatively small size data, such as passwords. If you need to securely store large objects, consider encrypting such objects in a symmetric way using randomly generated password and use secure preferences to store the password.
If secure preferences were modified, the framework will automatically save them on shutdown.
This interface is not intended to be implemented or extended by clients.
Method Summary | |
String |
absolutePath()
Returns absolute path to this node. |
String[] |
childrenNames()
Returns names of children nodes |
void |
clear()
Removes all values from this node. |
void |
flush()
Saves the tree of secure preferences to the persistent storage. |
String |
get(String key,
String def)
Retrieves a value associated with the key in this node. |
boolean |
getBoolean(String key,
boolean def)
Retrieves a value associated with the key in this node. |
byte[] |
getByteArray(String key,
byte[] def)
Retrieves a value associated with the key in this node. |
double |
getDouble(String key,
double def)
Retrieves a value associated with the key in this node. |
float |
getFloat(String key,
float def)
Retrieves a value associated with the key in this node. |
int |
getInt(String key,
int def)
Retrieves a value associated with the key in this node. |
long |
getLong(String key,
long def)
Retrieves a value associated with the key in this node. |
boolean |
isEncrypted(String key)
Specifies if value associated with the key is encrypted. |
String[] |
keys()
Returns keys that have associated values. |
String |
name()
Returns name of this node. |
ISecurePreferences |
node(String pathName)
Returns node corresponding to the path specified. |
boolean |
nodeExists(String pathName)
Checks if the node corresponding to the specified path exists in this tree of secure preferences. |
ISecurePreferences |
parent()
Returns parent of this node |
void |
put(String key,
String value,
boolean encrypt)
Stores a value associated with the key in this node. |
void |
putBoolean(String key,
boolean value,
boolean encrypt)
Stores a value associated with the key in this node. |
void |
putByteArray(String key,
byte[] value,
boolean encrypt)
Stores a value associated with the key in this node. |
void |
putDouble(String key,
double value,
boolean encrypt)
Stores a value associated with the key in this node. |
void |
putFloat(String key,
float value,
boolean encrypt)
Stores a value associated with the key in this node. |
void |
putInt(String key,
int value,
boolean encrypt)
Stores a value associated with the key in this node. |
void |
putLong(String key,
long value,
boolean encrypt)
Stores a value associated with the key in this node. |
void |
remove(String key)
Removes value associated with the key. |
void |
removeNode()
Removes this node from the tree of secure preferences. |
Method Detail |
public void put(String key, String value, boolean encrypt) throws StorageException
key
- key with which the value is going to be associatedvalue
- value to storeencrypt
- true
if value is to be encrypted, false
value
does not need to be encrypted
StorageException
- if exception occurred during encryption
IllegalStateException
- if this node (or an ancestor) has been removed with
the removeNode()
method.
NullPointerException
- if key
is null
.public String get(String key, String def) throws StorageException
key
- key with this the value is associateddef
- default value to return if the key is not associated with any value
StorageException
- if exception occurred during decryption
IllegalStateException
- if this node (or an ancestor) has been removed with
the removeNode()
method.public void remove(String key)
key
- key with which a value is associated
IllegalStateException
- if this node (or an ancestor) has been removed with
the removeNode()
method.public void clear()
IllegalStateException
- if this node (or an ancestor) has been removed with
the removeNode()
method.public String[] keys()
IllegalStateException
- if this node (or an ancestor) has been removed with
the removeNode()
method.public String[] childrenNames()
IllegalStateException
- if this node (or an ancestor) has been removed with
the removeNode()
method.public ISecurePreferences parent()
IllegalStateException
- if this node (or an ancestor) has been removed with
the removeNode()
method.public ISecurePreferences node(String pathName)
If the node path is invalid, an IllegalArgumentException
will be thrown
by this method. The valid node path:
pathName
- absolute or relative path to the node
IllegalArgumentException
- if the path name is invalid.
IllegalStateException
- if this node (or an ancestor) has been removed with
the removeNode()
method.Preferences
,
Preferences.node(String)
public boolean nodeExists(String pathName)
If the node path is invalid, an IllegalArgumentException
will be thrown
by this method. See node(String)
for the description of what is considered
to be a valid path.
pathName
- absolute or relative path to the node
true
if node corresponding to the path exists, false
otherwise
IllegalArgumentException
- if the path name is invalid.
IllegalStateException
- if this node (or an ancestor) has been removed with
the removeNode()
method.Preferences
,
Preferences.node(String)
public void removeNode()
IllegalStateException
- if this node (or an ancestor) has been removed with
the removeNode()
method.public String name()
IllegalStateException
- if this node (or an ancestor) has been removed with
the removeNode()
method.public String absolutePath()
IllegalStateException
- if this node (or an ancestor) has been removed with
the removeNode()
method.public void flush() throws IOException
IOException
- if error occurred while saving secure preferencespublic void putInt(String key, int value, boolean encrypt) throws StorageException
key
- key with which the value is going to be associatedvalue
- value to storeencrypt
- true
if value is to be encrypted, false
value
does not need to be encrypted
StorageException
- if exception occurred during encryption
IllegalStateException
- if this node (or an ancestor) has been removed with
the removeNode()
method.
NullPointerException
- if key
is null
.public int getInt(String key, int def) throws StorageException
key
- key with this the value is associateddef
- default value to return if the key is not associated with any value
StorageException
- if exception occurred during decryption
IllegalStateException
- if this node (or an ancestor) has been removed with
the removeNode()
method.public void putLong(String key, long value, boolean encrypt) throws StorageException
key
- key with which the value is going to be associatedvalue
- value to storeencrypt
- true
if value is to be encrypted, false
value
does not need to be encrypted
StorageException
- if exception occurred during encryption
IllegalStateException
- if this node (or an ancestor) has been removed with
the removeNode()
method.
NullPointerException
- if key
is null
.public long getLong(String key, long def) throws StorageException
key
- key with this the value is associateddef
- default value to return if the key is not associated with any value
StorageException
- if exception occurred during decryption
IllegalStateException
- if this node (or an ancestor) has been removed with
the removeNode()
method.public void putBoolean(String key, boolean value, boolean encrypt) throws StorageException
key
- key with which the value is going to be associatedvalue
- value to storeencrypt
- true
if value is to be encrypted, false
value
does not need to be encrypted
StorageException
- if exception occurred during encryption
IllegalStateException
- if this node (or an ancestor) has been removed with
the removeNode()
method.
NullPointerException
- if key
is null
.public boolean getBoolean(String key, boolean def) throws StorageException
key
- key with this the value is associateddef
- default value to return if the key is not associated with any value
StorageException
- if exception occurred during decryption
IllegalStateException
- if this node (or an ancestor) has been removed with
the removeNode()
method.public void putFloat(String key, float value, boolean encrypt) throws StorageException
key
- key with which the value is going to be associatedvalue
- value to storeencrypt
- true
if value is to be encrypted, false
value
does not need to be encrypted
StorageException
- if exception occurred during encryption
IllegalStateException
- if this node (or an ancestor) has been removed with
the removeNode()
method.
NullPointerException
- if key
is null
.public float getFloat(String key, float def) throws StorageException
key
- key with this the value is associateddef
- default value to return if the key is not associated with any value
StorageException
- if exception occurred during decryption
IllegalStateException
- if this node (or an ancestor) has been removed with
the removeNode()
method.public void putDouble(String key, double value, boolean encrypt) throws StorageException
key
- key with which the value is going to be associatedvalue
- value to storeencrypt
- true
if value is to be encrypted, false
value
does not need to be encrypted
StorageException
- if exception occurred during encryption
IllegalStateException
- if this node (or an ancestor) has been removed with
the removeNode()
method.
NullPointerException
- if key
is null
.public double getDouble(String key, double def) throws StorageException
key
- key with this the value is associateddef
- default value to return if the key is not associated with any value
StorageException
- if exception occurred during decryption
IllegalStateException
- if this node (or an ancestor) has been removed with
the removeNode()
method.public void putByteArray(String key, byte[] value, boolean encrypt) throws StorageException
key
- key with which the value is going to be associatedvalue
- value to storeencrypt
- true
if value is to be encrypted, false
value
does not need to be encrypted
StorageException
- if exception occurred during encryption
IllegalStateException
- if this node (or an ancestor) has been removed with
the removeNode()
method.
NullPointerException
- if key
is null
.public byte[] getByteArray(String key, byte[] def) throws StorageException
key
- key with this the value is associateddef
- default value to return if the key is not associated with any value
StorageException
- if exception occurred during decryption
IllegalStateException
- if this node (or an ancestor) has been removed with
the removeNode()
method.public boolean isEncrypted(String key) throws StorageException
key
- key with which a value is associated
true
if value is encrypted, false
otherwise
StorageException
- if stored data is invalid
IllegalStateException
- if this node (or an ancestor) has been removed with
the removeNode()
method.
|
Eclipse Platform Release 3.4 |
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Guidelines for using Eclipse APIs.
Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.