Module org.bzdev.base
Package org.bzdev.util

Class ConfigProperties

java.lang.Object
org.bzdev.util.ConfigProperties
public class ConfigProperties extends Object
Convenience class used to create a Properties instance formatted to match the ConfigPropertyEditor conventions. The "set" methods return the object being modified to allow methods to be chained. For example, 

 ConfigProperties props =
       new ConfigProperties("application/vnd.bzdev.sblauncher")
       .setProperty("user.description", "Example")
       .setProperty("user.base", "https://example.com/contents/")
       .setProperty("user.uri", "$(user.base)/login.html")
       ...;

Mostly, the methods in this class merely call the corresponding static methods provided by ConfigPropUtilities.

  • Constructor Details

    • ConfigProperties

      public ConfigProperties(String mediaType)
      Constructor.
      Parameters:
      mediaType - the media (MIME) type

    • ConfigProperties

      public ConfigProperties(File f, String mediaType) throws IOException
      Constructor given a file. Media types are encoded in the first line of the file, which is expected to be 
      
 #(!M.T MEDIATYPE)
      where MEDIATYPE is the media (or MIME type) as defined in RFC 2045 and subsequent RFCs. The mediatype is converted to lower case for testing.
      Parameters:
      f - the file to load
      mediaType - the media (MIME) type
      Throws:
      IOException - if an IO error occurred

    • ConfigProperties

      public ConfigProperties(InputStream is, String mediaType) throws IOException
      Constructor given an input stream. Media types are encoded in the first line of the file, which is expected to be 
      
 #(!M.T MEDIATYPE)
      where MEDIATYPE is the media (or MIME type) as defined in RFC 2045 and subsequent RFCs. The mediatype is converted to lower case for testing.
      Parameters:
      is - the input stream
      mediaType - the media (MIME) type
      Throws:
      IOException - if an IO error occurred

    • ConfigProperties

      public ConfigProperties(String b64data, String mediaType) throws IOException
      Constructor given a string containing Base64-encoded GZIPed ConfigProperties file. Media types are encoded in the first line of the file, which is expected to be 
      
 #(!M.T MEDIATYPE)
      where MEDIATYPE is the media (or MIME type) as defined in RFC 2045 and subsequent RFCs. The mediatype is converted to lower case for testing.
      Parameters:
      b64data - a Base-64 encoded string representing this object.
      mediaType - the media (MIME) type
      Throws:
      IOException - if the media type does not match that of the Base-64 encoded representation

  • Method Details

    • getKeys

      public Set<String> getKeys()
      Get the current property names.
      Returns:
      the property names

    • getDecryptedProperty

      public char[] getDecryptedProperty(String key, char[] passphrase) throws GeneralSecurityException
      Get the value, decrypted if necessary, stored in this object under a given key.
      Parameters:
      key - the key
      passphrase - the GPG passphrase for decryption.
      Returns:
      the decrypted value
      Throws:
      GeneralSecurityException - if decryption failed

    • getDecryptedProperty

      public char[] getDecryptedProperty(String key, char[] passphrase, String gpgdir) throws GeneralSecurityException
      Get the value, decrypted if necessary, stored this object under a given key and a GPG home directory. The GPG home directory is the argument for the GPG --homedir command-line option. When gpgdir is non-null, a GPG TOFU (Trust On First Use) trust model is used.
      Parameters:
      key - the key
      passphrase - the GPG passphrase for decryption
      gpgdir - the GPG 'home' directory to use
      Returns:
      the decrypted value
      Throws:
      GeneralSecurityException - if decryption failed

    • getProperty

      public String getProperty(String key) throws IllegalStateException
      Get the value stored in this object under a given key. Values whose keys start with "base64." are decoded using a Base-64 decoder. Otherwise, the sequence "$(KEY)", where KEY is some key, is replaced with the value stored for KEY in the value provided for the given key.

      If an error occurs due to a key recursively referencing itself, the method ConfigPropUtilities.getCyclicKeys() can be used to help find the cycle provided that method is called immediately after the exception is thrown.

      Parameters:
      key - the key
      Returns:
      the value for the given key; null if the key does not exist
      Throws:
      IllegalStateException - if a key is part of a cyclic reference

    • getProperty

      public String getProperty(String key, boolean literal)
      Get the value stored in this object under a given key, optionally providing a literal value.

      This method is provided primarily for use with setProperty(java.lang.String,java.lang.String,boolean), and is useful when properties have to be copied "as is" between two instances of this class.

      Parameters:
      key - the key
      literal - true if value of the property should be returned as is; false for the behavior specified by getProperty(String)
      Returns:
      the value for the given key; null if the key does not exist

    • setProperty

      public ConfigProperties setProperty(String key, String value) throws IllegalArgumentException
      Set a property. When decoded, each '$$' will be replaced with a single '$' and substrings of the form "$(KEY)" will be replaced with the value for the specified KEY, unless the key starts with "base64.", in which case the value will be base-64 encoded. for storage.
      Parameters:
      key - the property key
      value - the property value
      Throws:
      IllegalArgumentException - if the key starts with "ebase64."
      See Also:

    • setProperty

      public ConfigProperties setProperty(String key, String value, boolean literal) throws IllegalArgumentException
      Set a property for an instance of Properties. When the argument literal is false, a '$' must be escaped by replacing it with the pair "$$", and substrings of the form "$(KEY)" are replaced with the value of KEY. A check for circularity is not performed at this point. Each "$" in the value will be replaced with "$$" because of ConfigPropertyEditor conventions, unless the key starts with "base64.", in which case the value will be Base-64 encoded.
      Parameters:
      key - the property key
      value - the property value
      literal - true if the value is a literal string; false if variable substitution is allowed
      Throws:
      IllegalArgumentException - if the key starts with "ebase64."
      See Also:

    • getRecipients

      public String[] getRecipients(String key) throws IllegalStateException
      Get GPG recipients that were stored using the specified key.
      Parameters:
      key - the property key
      Returns:
      the recipients
      Throws:
      IllegalStateException - if the object stored using the specified key cannot be decoded

    • setRecipients

      public ConfigProperties setRecipients(String key, String[] recipients)
      Set GPG recipients that were stored using the specified key.
      Parameters:
      key - the property key
      recipients - the recipients
      Returns:
      this object

    • setProperty

      public ConfigProperties setProperty(String key, String value, char[] password) throws IllegalArgumentException
      Set a property for this object when symmetric* encryption is used.

      Note: When a ConfigPropertyEditor is used, either all encrypted entries should use either symmetric encryption or public key encryption, but these should not be mixed. All encrypted entries should use the same password or passphrase.

      Parameters:
      key - the property key
      value - the property value
      password - the password for symmetric encryption
      Returns:
      this object
      Throws:
      IllegalArgumentException - if the password is null or empty
      See Also:

    • setProperty

      public ConfigProperties setProperty(String key, char[] value, char[] password) throws IllegalArgumentException
      Set a property for this object when symmetric* encryption is used and the value is a char array.

      Note: When a ConfigPropertyEditor is used, either all encrypted entries should use either symmetric encryption or public key encryption, but these should not be mixed. All encrypted entries should use the same password or passphrase.

      Parameters:
      key - the property key
      value - the property value
      password - the password for symmetric encryption
      Returns:
      this object
      Throws:
      IllegalArgumentException - if the password is null or empty
      See Also:

    • setProperty

      public ConfigProperties setProperty(String key, String value, String gpgdir, String[] recipients)
      Set a property for this object when GPG encryption is used. The recipient's list must contain strings that GPG can use to look up a public key.

      Note: When a ConfigPropertyEditor is used, either all encrypted entries should use either symmetric encryption or public key encryption, but these should not be mixed. All encrypted entries should use the same password or passphrase.

      When gpgdir is non-null, a GPG TOFU (Trust On First Use) trust model is used.

      Parameters:
      key - the property key
      value - the property value
      gpgdir - The GPG home directory used to store public an private keys; null for the default
      recipients - the recipients
      Throws:
      IllegalArgumentException - if there are no recipients or if the key does not start with "ebase64"
      See Also:

    • setProperty

      public ConfigProperties setProperty(String key, char[] value, String gpgdir, String[] recipients)
      Set a property for this object when GPG encryption is used and the value of the property is a char array. The recipient's list must contain strings that GPG can use to look up a public key.

      Note: When a ConfigPropertyEditor is used, either all encrypted entries should use either symmetric encryption or public key encryption, but these should not be mixed. All encrypted entries should use the same password or passphrase.

      When gpgdir is non-null, a GPG TOFU (Trust On First Use) trust model is used.

      Parameters:
      key - the property key
      value - the property value
      gpgdir - The GPG home directory used to store public an private keys; null for the default
      recipients - the recipients
      Throws:
      IllegalArgumentException - if there are no recipients or if the key does not start with "ebase64"
      See Also:

    • store

      public ConfigProperties store(File file) throws IOException
      Store this object, given an output file, using the ConfigPropertyEditor format The file is created by using Properties.store(Writer,String) with a writer that uses the UTF-8 character set with CRLF line separators. The file will start with a comment "#(!M.T " MEDIATYPE)" where MEDIATYPE is the media type in lower case.
      Parameters:
      file - the file
      Throws:
      IOException - if an IO error occurred

    • store

      public ConfigProperties store(OutputStream os) throws IOException
      Store this object given an output stream, using the ConfigPropertyEditor format. The output is created by using Properties.store(Writer,String) with a writer that uses the UTF-8 character set with CRLF line separators. The output will start with a comment "#(!M.T " MEDIATYPE)" where MEDIATYPE is the media type in lower case.
      Parameters:
      os - the output stream
      Throws:
      IOException - if an IO error occurred

    • store

      public String store()
      Store this object as a Base-64 encoded string. A byte array is produced by in effect first creating a text file using the UTF-8 charset and with a CRLF sequence terminating each line, optionally compressing that file. The text-file format is that produced by Properties.store(Writer,String). This byte array is finally base-64 encoded and turned into a string using the UTF-8 character set. The properties file will start with a comment "#(!M.T " MEDIATYPE)" where MEDIATYPE is the media type in lower case.
      Returns:
      the Base-64 encoded string.

    • storeBytes

      public byte[] storeBytes(boolean gzip)
      Store this object as a byte array. The byte array is produced by in effect first creating a text file using the UTF-8 charset and with a CRLF sequence terminating each line, optionally compressing that file. The text-file format is that produced by Properties.store(Writer,String). The properties file will start with a comment "#(!M.T " MEDIATYPE)" where MEDIATYPE is the media type in lower case.
      Parameters:
      gzip - true if the result is compressed using GZIP
      Returns:
      an array of bytes containing the properties