com.ibm.di.util
Class PropertiesFile

java.lang.Object
  com.ibm.di.util.PropertiesFile

public class PropertiesFile
extends java.lang.Object

In-memory representation of a TDI properties file. It may contain comments and empty lines as well as property definitions. It may also contain references to other properties files.

A property in a TDI properties file can be protected or non-protected. Protected properties normally have their keys prefixed with PropertiesFile.PROTECT_PREFIX. Protected properties may have their values encrypted. If a property value is encrypted, it will be prefixed with PropertiesFile.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:

TDI 7.0

Field Summary

static java.lang.String	INCLUDE_DIRECTIVE Include directive "!include <other-file/url>"
static java.lang.String	MERGE_DIRECTIVE Merge directive - "!merge <other-file/url>".
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.

Constructor Summary

PropertiesFile(Crypto propertyCrypto)
Create an empty object.

PropertiesFile(Crypto propertyCrypto, java.lang.String path, boolean resolveReferences)
Load a properties file in memory.

PropertiesFile(Crypto propertyCrypto, java.lang.String path, boolean resolveReferences, Crypto fileCrypto, java.lang.String prefixToSkip)
Load a properties file in memory.

PropertiesFile(java.lang.String path, boolean resolveReferences)
Load a properties file in memory.

Method Summary

java.lang.String	getProperty(java.lang.String key) Return the property value as plaintext.
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.
void	store(java.lang.String path, java.lang.String header, Crypto fileCrypto) 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

INCLUDE_DIRECTIVE

public static final java.lang.String INCLUDE_DIRECTIVE

Include directive "!include <other-file/url>"

Include one properties file into another properties file. Properties defined in the main properties file before the include directive can be potentially overridden by properties from the included file. Properties defined in the main properties file after the include directive can potentially override properties from the included file.

See Also:

Constant Field Values

MERGE_DIRECTIVE

public static final java.lang.String MERGE_DIRECTIVE

Merge directive - "!merge <other-file/url>".

Merge the contents of one properties file into another properties file. Properties defined in the main properties file before the merge directive will not be overwritten by the properties from the merged file. Properties defined in the main properties file after the merge directive can potentially override properties from the merged file.

See Also:

Constant Field Values

PROTECT_PREFIX

public static final java.lang.String PROTECT_PREFIX

A prefix for the keys of protected properties. A protected proeprty 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

Constructor Detail

PropertiesFile

public PropertiesFile(Crypto propertyCrypto)

Create an empty object.

Parameters:

propertyCrypto - object used to encrypt/decrypt values of protected properties

PropertiesFile

public PropertiesFile(java.lang.String path,
                      boolean resolveReferences)
               throws java.lang.Exception

Load a properties file in memory. Uses a default Crypto.

Parameters:

path - properties file to load

resolveReferences - whether to load the properties files that the specified file references

Throws:

java.lang.Exception - error while reading the properties file

PropertiesFile

public PropertiesFile(Crypto propertyCrypto,
                      java.lang.String path,
                      boolean resolveReferences)
               throws java.lang.Exception

Load a properties file in memory.

Parameters:

propertyCrypto - object used to encrypt/decrypt values of protected properties

path - properties file to load

resolveReferences - whether to load the properties files that the specified file references

Throws:

java.lang.Exception - error while reading the properties file

PropertiesFile

public PropertiesFile(Crypto propertyCrypto,
                      java.lang.String path,
                      boolean resolveReferences,
                      Crypto fileCrypto,
                      java.lang.String prefixToSkip)
               throws java.lang.Exception

Load a properties file in memory. If the specified file is encrypted as a whole, a cryptographic object to decrypt the file must be provided. If a file is encrypted as a whole, all the files it references are expected to be encrypted too. The specified crypto object will be used to decrypt them also.

Parameters:

propertyCrypto - object used to encrypt/decrypt values of protected properties

path - properties file to load

resolveReferences - whether to load the properties files that the specified file references

fileCrypto - object used to decrypt the file; pass null if the properties file is not encrypted as a whole

prefixToSkip - prefix that matches lines from the properties file, which will be skipped during processing; pass null to read all lines

Throws:

java.lang.Exception - error while reading the properties file, or error while decrypting it

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

store

public void store(java.lang.String path,
                  java.lang.String header,
                  Crypto fileCrypto)
           throws java.lang.Exception

Write the contents of this properties file to disk.

Parameters:

path - a file, whether the contents will be saved

header - an optional header, that will be put as the first line in the properties file; must be a single comment line

fileCrypto - object used to encrypt the file as a whole; if null the file will not be encrypted as a whole

Throws:

java.lang.Exception - error while writing the file or error while encrypting the file

getProperty

public java.lang.String getProperty(java.lang.String key)
                             throws java.lang.Exception

Return the property value as plaintext. 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. Changes to properties that do not originate from this file but rather from some of the files it references, do not count as modifications.

Returns:

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