com.ibm.di.util
Class BasePropertiesFile

java.lang.Object
  extended by com.ibm.di.util.BasePropertiesFile
Direct Known Subclasses:
JavaPropertiesFile, PropertiesFile

public abstract class BasePropertiesFile
extends java.lang.Object

In-memory representation of a properties file. It may contain comments and empty lines as well as property definitions. When writing the order of the properties and the user comments are kept.

A property in a properties file can be protected or non-protected. Protected properties normally have their keys prefixed with BasePropertiesFiles.PROTECT_PREFIX. Protected properties may have their values encrypted. If a property value is encrypted, it will be prefixed with BasePropertiesFiles.PROTECT_VAL_PREFIX. If a property's value is encrypted, the property is considered protected no matter if it is actually marked as protected.

Since:
7.1
See Also:
PropertiesFile

Nested Class Summary
protected static class BasePropertiesFile.Property
          A property from a properties file.
 
Field Summary
protected  java.util.List<java.lang.StringBuilder> lines
          All lines of the properties file - including comments, empty lines, include directives and property definitions.
protected  boolean modified
          Whether any of the lines in this properties file has been modified.
protected  java.util.Map<java.lang.String,BasePropertiesFile.Property> properties
           The property definitions of the properties file the mapping is: property key -> BasePropertiesFile.Property object.
protected  Crypto propertyCrypto
          Object to encrypt/decrypt the values of protected properties.
static java.lang.String PROTECT_PREFIX
          A prefix for the keys of protected properties.
static java.lang.String PROTECT_VAL_PREFIX
          A prefix for encrypted property values.
protected static ResourceHash resHash
           
 
Constructor Summary
BasePropertiesFile()
          Create an empty object.
BasePropertiesFile(Crypto propertyCrypto)
          Create an empty object with crypto module.
 
Method Summary
 java.lang.String getProperty(java.lang.String key)
          Return the property value as plain text.
 java.lang.String getProperty(java.lang.String key, Log log)
          Return the property value as plain text.
 boolean isModified()
          Determine whether the contents of this file has been modified, e.g.
 boolean isPropertyEncrypted(java.lang.String key)
           
 boolean isPropertyProtected(java.lang.String key)
           
 java.util.Iterator<java.lang.String> keys()
           
 void removeProperty(java.lang.String key)
          Remove a property from this properties file.
 void setProperty(java.lang.String key, java.lang.String value)
          Set a property.
 void setPropertyEncrypted(java.lang.String key, boolean encrypt)
          Change the encrypted status of a property's value.
 void setPropertyProtected(java.lang.String key, boolean protect)
          Change the protected status of a property.
abstract  void store(java.lang.String path)
          Write the contents of this properties file to disk.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

PROTECT_PREFIX

public static final java.lang.String PROTECT_PREFIX
A prefix for the keys of protected properties. A protected property may or may not have an encrypted value. However, if a property's value is encrypted, the property must be protected.

See Also:
Constant Field Values

PROTECT_VAL_PREFIX

public static final java.lang.String PROTECT_VAL_PREFIX
A prefix for encrypted property values.

See Also:
Constant Field Values

lines

protected java.util.List<java.lang.StringBuilder> lines
All lines of the properties file - including comments, empty lines, include directives and property definitions. The contents of referenced property files are not contained in this list. Each line is a StringBuilder object, so that a line can be modified, without modifying the list.


properties

protected java.util.Map<java.lang.String,BasePropertiesFile.Property> properties

The property definitions of the properties file the mapping is: property key -> BasePropertiesFile.Property object. The key is not marked with a protect prefix.

Only the last encountered definition of a property is kept. If for example a properties file contains two equal properties, then the definition from the last property will be kept.


modified

protected boolean modified
Whether any of the lines in this properties file has been modified.


propertyCrypto

protected Crypto propertyCrypto
Object to encrypt/decrypt the values of protected properties.


resHash

protected static final ResourceHash resHash
Constructor Detail

BasePropertiesFile

public BasePropertiesFile()
Create an empty object.


BasePropertiesFile

public BasePropertiesFile(Crypto propertyCrypto)
Create an empty object with crypto module.

Parameters:
propertyCrypto - object used to encrypt/decrypt values of protected properties
Method Detail

keys

public java.util.Iterator<java.lang.String> keys()
Returns:
the keys of all properties; removing properties through this iterator will result in an undefined behavior

getProperty

public java.lang.String getProperty(java.lang.String key)
                             throws java.lang.Exception
Return the property value as plain text. The value will be decrypted if necessary. If the property is not found, the method returns null.

Parameters:
key - the property key
Returns:
the property value
Throws:
java.lang.Exception - decryption error

setProperty

public void setProperty(java.lang.String key,
                        java.lang.String value)
                 throws java.lang.Exception
Set a property. Either override an existing property or add a new one. If overriding a protected existing property, the property will stay protected. If overriding an encrypted existing property, the property will stay encrypted. If the specified value is encrypted, the property will be considered encrypted (and protected).

Parameters:
key - a property key; can be marked as protected
value - a property value; can be encrypted
Throws:
java.lang.Exception - encryption error (if setting a non-encrypted value to an encrypted property)

removeProperty

public void removeProperty(java.lang.String key)
Remove a property from this properties file.

Parameters:
key - property key

isPropertyProtected

public boolean isPropertyProtected(java.lang.String key)
Parameters:
key - a property key
Returns:
whether the property is marked as protected

isPropertyEncrypted

public boolean isPropertyEncrypted(java.lang.String key)
Parameters:
key - a property key
Returns:
whether the property value is encrypted

setPropertyProtected

public void setPropertyProtected(java.lang.String key,
                                 boolean protect)
                          throws java.lang.Exception
Change the protected status of a property. Not protected implies that the property is not encrypted, so the property value will be decrypted if the property is transformed from protected to not protected.

Parameters:
key - a property key
protect - whether the property will be protected
Throws:
java.lang.Exception - decryption error

setPropertyEncrypted

public void setPropertyEncrypted(java.lang.String key,
                                 boolean encrypt)
                          throws java.lang.Exception
Change the encrypted status of a property's value. Encrypted implies that the property is protected, so the property will automatically become protected if it is encrypted.

Parameters:
key - a property key
encrypt - whether the property value will be encrypted
Throws:
java.lang.Exception - encryption/decryption error

isModified

public boolean isModified()
Determine whether the contents of this file has been modified, e.g. the status of a property has been changed.

Returns:
whether the in-memory contents of the properties file are modified

store

public abstract void store(java.lang.String path)
                    throws java.lang.Exception
Write the contents of this properties file to disk.

Parameters:
path - a file, whether the contents will be saved
Throws:
java.lang.Exception - error while writing the file

getProperty

public java.lang.String getProperty(java.lang.String key,
                                    Log log)
                             throws java.lang.Exception
Return the property value as plain text. The value will be decrypted if necessary. If the property is not found, the method returns null.

Parameters:
key -
log -
Returns:
the property value
Throws:
java.lang.Exception