diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 6374b8c..98af2de 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -39,3 +39,11 @@ jobs:
**/target/surefire-reports/*.xml
**/target/site/
retention-days: 7
+
+ - name: Upload Javadoc
+ if: success()
+ uses: actions/upload-artifact@50769540e7f4bd5e21e526ee35c689e35e0d6874 # v4.4.0
+ with:
+ name: javadoc
+ path: target/apidocs/
+ retention-days: 7
diff --git a/pom.xml b/pom.xml
index 5e822da..017903b 100755
--- a/pom.xml
+++ b/pom.xml
@@ -150,8 +150,8 @@
The map stores a {@link java.util.List} for each key in an underlying map, which is a {@link + * java.util.LinkedHashMap} unless another one is given to the constructor. Keys therefore come in + * insertion order by default. The values of a key are in insertion order too. A value can be {@code + * null}. + * + *
The inherited {@link java.util.Map} methods work on the whole key as described in {@link + * MultiMap}. The differences from a plain map are these: {@link #size()} counts keys, not values; + * {@link #values()} returns all the values of all the keys, so it can have more elements than + * {@link #size()}; {@link #entrySet()} has one entry for each key, and the entry reads and replaces + * the last value. The class does not override {@code equals} and {@code hashCode}, so two maps are + * equal only if they are the same object. + * + *
Thread safety. The class has no synchronization. Several threads can read a
+ * map built on the default underlying map while no thread changes it. A map built on a collection
+ * that changes on reads, such as an access-ordered {@link java.util.LinkedHashMap}, is not safe to
+ * read from several threads. Any change needs outside locking.
+ *
+ * @param The given map is used directly, not copied, so changes to it show in this map and the other
+ * way round. It must map each key to a modifiable list. The order of the keys is the iteration
+ * order of the given map.
+ *
+ * @param impl the underlying map, used as it is
+ */
@edu.umd.cs.findbugs.annotations.SuppressFBWarnings("EI_EXPOSE_REP2")
public BasicMultiMap(Map The set is a new one and is not backed by the map: removing from it does not change the map,
+ * and it is not ordered. The value of an entry is the last value of its key, and {@link
+ * java.util.Map.Entry#setValue(Object)} replaces that last value.
+ *
+ * @return a new set of entries
+ */
@Override
public Set The set is a live view of the underlying map, so removing a key from it removes all the
+ * values of the key.
+ *
+ * @return the set of keys
+ */
@Override
public Set If the argument is a {@link MultiMap}, all the values of each of its keys replace the values
+ * of that key in this map (as {@link #putAll(Object, List)} does). Otherwise each entry replaces
+ * the last value of its key.
+ *
+ * @param map the map to copy from
+ */
@SuppressWarnings(Warnings.UNCHECKED)
@Override
public void putAll(Map extends K, ? extends V> map) {
@@ -155,6 +216,17 @@ public void putAll(Map extends K, ? extends V> map) {
}
}
+ /**
+ * Replaces all the values of a key with a copy of the given list.
+ *
+ * Do not pass an empty list. The key would then be in the map with no value, and {@link
+ * #get(Object)} for it would throw an {@link IndexOutOfBoundsException}.
+ *
+ * @param key the key
+ * @param values the new values, copied
+ * @return the list of values the key had before, as the map stored it, or {@code null} if the key
+ * was not in the map
+ */
@Override
public List The collection is a new list, in key order and, for each key, in value order. Changes to it
+ * do not change the map.
+ *
+ * @return a new collection of values
+ */
@Override
public Collection It is a {@link CommonMultiMap} of option names to values, so every option name can have
+ * several values and a comment. The conversion, variable and bean methods are described in {@link
+ * OptionMap}. Variables are resolved by the {@code fetch} methods, except {@link #fetch(Object,
+ * String)}, up to the depth given by the configuration (see {@link Config#getMaxResolveDepth()}).
+ * This class uses {@link Config#getGlobal()} for that limit; {@link Options} and the sections of an
+ * {@link Ini} use their own configuration.
+ *
+ * The {@link #as(Class)} methods create a dynamic proxy with the context class loader of the
+ * calling thread, so the interface must be visible from that class loader.
+ *
+ * The thread safety of {@link BasicMultiMap} applies.
+ *
+ * @see Options
+ * @see Profile.Section
+ * @since 0.5.0
+ */
public class BasicOptionMap extends CommonMultiMap The names of bean properties are used as they are for the option names.
+ */
public BasicOptionMap() {
this(false);
}
+ /**
+ * Creates an empty option map and tells how bean property names map to option names.
+ *
+ * @param propertyFirstUpper if {@code true}, the first letter of a bean property name is changed
+ * to upper case to get the option name (see {@link #as(Class)})
+ */
public BasicOptionMap(boolean propertyFirstUpper) {
_propertyFirstUpper = propertyFirstUpper;
}
@@ -110,6 +140,26 @@ public String fetch(Object key, int index) {
return fetchInternal(key, index, 0);
}
+ /**
+ * Returns the value of an option at the given position, with variables resolved at a given
+ * nesting depth.
+ *
+ * The {@code fetch} methods call this method, except {@link #fetch(Object, String)}, which
+ * does not resolve variables. A subclass can override it to change how variables are resolved.
+ * {@code depth} is {@code 0} when a value is fetched by a caller, and it is one more for a value
+ * that is fetched because a variable refers to it. When {@code depth} has reached the limit of
+ * {@link Config#getMaxResolveDepth()}, a value that contains a dollar sign throws a {@link
+ * CircularReferenceException}, whether or not it holds a valid variable. A value without a dollar
+ * sign is returned as it is.
+ *
+ * @param key the option name
+ * @param index the position of the value
+ * @param depth the current nesting depth of variable references
+ * @return the value with its variables resolved, or {@code null} if the option is missing
+ * @throws IndexOutOfBoundsException if the option exists and the index is out of range
+ * @throws CircularReferenceException if {@code depth} has reached the depth limit and the value
+ * contains a dollar sign
+ */
protected String fetchInternal(Object key, int index, int depth) {
String value = get(key, index);
@@ -253,6 +303,19 @@ void resolve(StringBuilder buffer) {
resolve(buffer, 0);
}
+ /**
+ * Replaces the variables in a buffer with their values.
+ *
+ * The buffer is changed in place. After each replacement the scan starts again from the
+ * beginning, so a value that holds a variable is resolved as well. A variable whose option,
+ * environment variable or system property is missing stays in the text. The variable syntax is
+ * described in {@link OptionMap}.
+ *
+ * @param buffer the text to resolve
+ * @param depth the nesting depth of this call
+ * @throws CircularReferenceException if {@code depth} has reached {@link
+ * Config#getMaxResolveDepth()}
+ */
void resolve(StringBuilder buffer, int depth) {
if (depth >= getConfig().getMaxResolveDepth()) {
throw new CircularReferenceException(getConfig().getMaxResolveDepth());
@@ -271,7 +334,7 @@ void resolve(StringBuilder buffer, int depth) {
value = Config.getSystemProperty(name.substring(SYSTEM_PROPERTY_PREFIX_LEN));
} else {
if (index == -1) {
- // When no index specified, use the default behavior: get the last value
+ // When no index is specified, use the default behavior: get the last value
int len = length(name);
value = (len == 0) ? null : fetchInternal(name, len - 1, depth + 1);
} else {
diff --git a/src/main/java/org/ini4j/BasicProfile.java b/src/main/java/org/ini4j/BasicProfile.java
index 116e9f0..313b0cf 100644
--- a/src/main/java/org/ini4j/BasicProfile.java
+++ b/src/main/java/org/ini4j/BasicProfile.java
@@ -23,6 +23,27 @@
import org.ini4j.spi.BeanTool;
import org.ini4j.spi.IniHandler;
+/**
+ * The default implementation of {@link Profile}.
+ *
+ * It is a {@link CommonMultiMap} of section names to sections, so a name can have several
+ * sections and each section has a comment. The sections are {@link Profile.Section}s that resolve
+ * variables through this profile, so a variable can name an option of another section (see {@link
+ * #fetch(Object, Object)}).
+ *
+ * This class works with the path separator {@link #PATH_SEPARATOR} and with {@link
+ * Config#getGlobal()} for the limit of variable nesting. {@link Ini} and {@link Reg} take the path
+ * separator, the tree mode and the property naming rule from their own {@link Config} instead.
+ *
+ * The {@link #as(Class)} methods create a dynamic proxy with the context class loader of the
+ * calling thread, so the interface must be visible from that class loader.
+ *
+ * The thread safety of {@link BasicMultiMap} applies.
+ *
+ * @see Ini
+ * @see BasicRegistry
+ * @since 0.5.0
+ */
public class BasicProfile extends CommonMultiMap The buffer is changed in place. After each replacement the scan starts again from the
+ * beginning, so a value that holds a variable is resolved as well. A variable whose option,
+ * section, environment variable or system property is missing stays in the text. The variable
+ * syntax is described in {@link Profile#fetch(Object, Object)}.
+ *
+ * @param buffer the text to resolve
+ * @param owner the section of the option that holds the text; a variable without a section name
+ * refers to it
+ * @param depth the nesting depth of this call
+ * @throws CircularReferenceException if {@code depth} has reached {@link
+ * Config#getMaxResolveDepth()}
+ */
void resolve(StringBuilder buffer, Section owner, int depth) {
if (depth >= getConfig().getMaxResolveDepth()) {
throw new CircularReferenceException(getConfig().getMaxResolveDepth());
@@ -187,7 +232,7 @@ void resolve(StringBuilder buffer, Section owner, int depth) {
} else if (section instanceof BasicProfileSection) {
BasicProfileSection bps = (BasicProfileSection) section;
if (optionIndex == -1) {
- // When no index specified, use the default behavior: get the last value
+ // When no index is specified, use the default behavior: get the last value
int len = bps.length(optionName);
value = (len == 0) ? null : bps.fetchInternal(optionName, len - 1, depth + 1);
} else {
diff --git a/src/main/java/org/ini4j/BasicRegistry.java b/src/main/java/org/ini4j/BasicRegistry.java
index 9c0d1c4..c8d7e0c 100644
--- a/src/main/java/org/ini4j/BasicRegistry.java
+++ b/src/main/java/org/ini4j/BasicRegistry.java
@@ -19,10 +19,20 @@
import org.ini4j.spi.RegEscapeTool;
import org.ini4j.spi.TypeValuesPair;
+/**
+ * The default implementation of {@link Registry}.
+ *
+ * It is a {@link BasicProfile} whose sections are {@link Registry.Key}s. The methods that return
+ * a section return a key instead. The version header starts as {@link Registry#VERSION}.
+ *
+ * @see Reg
+ * @since 0.5.0
+ */
public class BasicRegistry extends BasicProfile implements Registry {
private static final long serialVersionUID = -6432826330714504802L;
private String _version;
+ /** Creates an empty registry with the version header {@link Registry#VERSION}. */
public BasicRegistry() {
_version = VERSION;
}
diff --git a/src/main/java/org/ini4j/CircularReferenceException.java b/src/main/java/org/ini4j/CircularReferenceException.java
index 2a97d71..cd6e2ba 100644
--- a/src/main/java/org/ini4j/CircularReferenceException.java
+++ b/src/main/java/org/ini4j/CircularReferenceException.java
@@ -16,11 +16,12 @@
package org.ini4j;
/**
- * Exception thrown when a circular reference is detected during variable resolution.
+ * Signals that variable substitution went deeper than the allowed depth.
*
- * This exception is thrown when the maximum recursion depth is exceeded while resolving variable
- * substitutions in INI files or option maps. This typically indicates a circular reference in the
- * configuration, such as:
+ * The variables in a value can refer to options whose values contain variables again, and the
+ * resolver follows them one level at a time. The exception is thrown when the nesting reaches the
+ * limit set by {@link Config#getMaxResolveDepth()}. The usual cause is a circular reference, such
+ * as:
*
* This exception prevents {@link StackOverflowError} that would otherwise occur from infinite
- * recursion.
+ * The limit also stops a very deep chain of references that is not circular. It is an {@link
+ * IllegalArgumentException}, so it is unchecked. The limit prevents the {@link StackOverflowError}
+ * that unbounded recursion would cause.
*
- * Security Note: This exception is part of the fix for CVE-2022-41404, which addressed a
- * Denial of Service vulnerability where circular variable references could crash the JVM.
+ * The limit was added to fix CVE-2022-41404, a denial of service through circular variable
+ * references.
*
* @see Config#getMaxResolveDepth()
* @see Config#setMaxResolveDepth(int)
+ * @see OptionMap#fetch(Object)
* @since 0.6.0
*/
public class CircularReferenceException extends IllegalArgumentException {
private static final long serialVersionUID = 1L;
/**
- * Constructs a new circular reference exception with the specified maximum resolve depth.
+ * Creates an exception with a standard message that names the depth limit.
*
- * @param maxResolveDepth the maximum recursion depth that was exceeded
+ * @param maxResolveDepth the depth limit that was reached
*/
public CircularReferenceException(int maxResolveDepth) {
super(
@@ -59,7 +62,7 @@ public CircularReferenceException(int maxResolveDepth) {
}
/**
- * Constructs a new circular reference exception with the specified detail message.
+ * Creates an exception with a detail message.
*
* @param message the detail message
*/
@@ -68,7 +71,7 @@ public CircularReferenceException(String message) {
}
/**
- * Constructs a new circular reference exception with the specified detail message and cause.
+ * Creates an exception with a detail message and a cause.
*
* @param message the detail message
* @param cause the cause
diff --git a/src/main/java/org/ini4j/CommentedMap.java b/src/main/java/org/ini4j/CommentedMap.java
index fbed485..f50fd85 100644
--- a/src/main/java/org/ini4j/CommentedMap.java
+++ b/src/main/java/org/ini4j/CommentedMap.java
@@ -17,10 +17,52 @@
import java.util.Map;
+/**
+ * A {@link Map} that can keep a comment for each key.
+ *
+ * A comment belongs to a key, not to one of its values. A key can have no comment, which is
+ * reported as {@code null}. When {@link Config#isComment()} is on, loading a file stores the
+ * comment lines in front of an option or a section as the comment of that option or section, with
+ * two exceptions: only the comment directly in front of the entry is kept, and the comment at the
+ * top of the file becomes the comment of the whole {@link Profile} or {@link Options} object when
+ * {@link Config#isHeaderComment()} is on (see {@link org.ini4j.spi.IniBuilder}). The leading
+ * comment character of each line is removed, and the lines are joined with the line separator of
+ * the {@link Config}. Storing a file writes the comments back.
+ *
+ * In {@link CommonMultiMap}, removing a key with {@code remove(Object)}, removing its last value
+ * with {@code remove(Object, int)}, and {@code clear()} also remove the comment. Removing a key in
+ * another way, for example through {@code keySet()}, does not.
+ *
+ * @param The key does not have to be in the map. {@link CommonMultiMap} stores the comment anyway.
+ *
+ * @param key the key
+ * @param comment the new comment
+ * @return the previous comment of the key, or {@code null} if it had none
+ */
String putComment(K key, String comment);
+ /**
+ * Removes the comment of a key.
+ *
+ * @param key the key
+ * @return the removed comment, or {@code null} if the key had none
+ */
String removeComment(Object key);
}
diff --git a/src/main/java/org/ini4j/CommonMultiMap.java b/src/main/java/org/ini4j/CommonMultiMap.java
index 5293e5c..6857db2 100644
--- a/src/main/java/org/ini4j/CommonMultiMap.java
+++ b/src/main/java/org/ini4j/CommonMultiMap.java
@@ -19,6 +19,22 @@
import java.util.SortedMap;
import java.util.TreeMap;
+/**
+ * A {@link BasicMultiMap} that also keeps a comment for each key.
+ *
+ * The comments are kept in a separate map and are removed together with the key by {@link
+ * #remove(Object)}, by {@link #remove(Object, int)} when it removes the last value of the key, and
+ * by {@link #clear()}. A key removed in another way, for example through {@link #keySet()}, keeps
+ * its comment. Adding or replacing values does not change comments.
+ *
+ * {@link #putAll(Map)} from another {@code CommonMultiMap} also copies all the per-key data of
+ * that map, which are its comments and, for a {@link Registry.Key}, the types of its values.
+ *
+ * @param A configuration is a set of flags and a few other values, such as the file encoding and the
+ * line separator. They decide, for example, whether an option can have several values, whether
+ * comments are kept and how special characters are escaped. {@link Ini}, {@link Options} and {@link
+ * Reg} are {@link Configurable}, and the parsers and formatters of the {@code org.ini4j.spi}
+ * package read it. Each option is described once, at its getter. The matching setter, the {@code
+ * PROP_} constant (the name of the system property) and the {@code DEFAULT_} constant point to it.
+ *
+ * The initial value of an option is read from a system property whose name is {@link
+ * #KEY_PREFIX} followed by the {@code PROP_} constant, for example {@code
+ * -Dorg.ini4j.config.multiSection=true}. If the property is not set, the {@code DEFAULT_} constant
+ * is used. The properties are read when a {@code Config} is created and again by {@link #reset()}.
+ *
+ * To change the behavior of one object, give it its own copy:
+ *
+ * A {@code Config} can be serialized, but the file encoding is not part of the serialized form:
+ * it is {@code null} in a deserialized object.
+ *
+ * Thread safety. A {@code Config} has no synchronization. {@link #getGlobal()}
+ * is shared by all the {@link Ini} objects that use it, so a change to it is a change to all of
+ * them, and it is not safe while another thread reads or writes. Set up a configuration before
+ * sharing it.
+ *
+ * @see Configurable
+ * @since 0.4.0
+ */
@SuppressWarnings("PMD.ExcessivePublicCount")
@edu.umd.cs.findbugs.annotations.SuppressFBWarnings({
"SING_SINGLETON_IMPLEMENTS_CLONEABLE",
"SING_SINGLETON_IMPLEMENTS_SERIALIZABLE"
})
public class Config implements Cloneable, Serializable {
+ /**
+ * The prefix of the system properties that set the initial values of a {@link Config}.
+ *
+ * The full name of a property is this prefix followed by the {@code PROP_} constant of the
+ * option, for example {@code org.ini4j.config.multiSection}.
+ */
public static final String KEY_PREFIX = "org.ini4j.config.";
+
+ /**
+ * The system property {@code org.ini4j.config.emptyOption} sets the initial value of {@link
+ * #isEmptyOption()}. This constant is the part after {@link #KEY_PREFIX}.
+ */
public static final String PROP_EMPTY_OPTION = "emptyOption";
+
+ /**
+ * The system property {@code org.ini4j.config.emptySection} sets the initial value of {@link
+ * #isEmptySection()}. This constant is the part after {@link #KEY_PREFIX}.
+ */
public static final String PROP_EMPTY_SECTION = "emptySection";
+
+ /**
+ * The system property {@code org.ini4j.config.globalSection} sets the initial value of {@link
+ * #isGlobalSection()}. This constant is the part after {@link #KEY_PREFIX}.
+ */
public static final String PROP_GLOBAL_SECTION = "globalSection";
+
+ /**
+ * The system property {@code org.ini4j.config.globalSectionName} sets the initial value of {@link
+ * #getGlobalSectionName()}. This constant is the part after {@link #KEY_PREFIX}.
+ */
public static final String PROP_GLOBAL_SECTION_NAME = "globalSectionName";
+
+ /**
+ * The system property {@code org.ini4j.config.include} sets the initial value of {@link
+ * #isInclude()}. This constant is the part after {@link #KEY_PREFIX}.
+ */
public static final String PROP_INCLUDE = "include";
+
+ /**
+ * The system property {@code org.ini4j.config.lowerCaseOption} sets the initial value of {@link
+ * #isLowerCaseOption()}. This constant is the part after {@link #KEY_PREFIX}.
+ */
public static final String PROP_LOWER_CASE_OPTION = "lowerCaseOption";
+
+ /**
+ * The system property {@code org.ini4j.config.lowerCaseSection} sets the initial value of {@link
+ * #isLowerCaseSection()}. This constant is the part after {@link #KEY_PREFIX}.
+ */
public static final String PROP_LOWER_CASE_SECTION = "lowerCaseSection";
+
+ /**
+ * The system property {@code org.ini4j.config.multiOption} sets the initial value of {@link
+ * #isMultiOption()}. This constant is the part after {@link #KEY_PREFIX}.
+ */
public static final String PROP_MULTI_OPTION = "multiOption";
+
+ /**
+ * The system property {@code org.ini4j.config.multiSection} sets the initial value of {@link
+ * #isMultiSection()}. This constant is the part after {@link #KEY_PREFIX}.
+ */
public static final String PROP_MULTI_SECTION = "multiSection";
+
+ /**
+ * The system property {@code org.ini4j.config.strictOperator} sets the initial value of {@link
+ * #isStrictOperator()}. This constant is the part after {@link #KEY_PREFIX}.
+ */
public static final String PROP_STRICT_OPERATOR = "strictOperator";
+
+ /**
+ * The system property {@code org.ini4j.config.unnamedSection} sets the initial value of {@link
+ * #isUnnamedSection()}. This constant is the part after {@link #KEY_PREFIX}.
+ */
public static final String PROP_UNNAMED_SECTION = "unnamedSection";
+
+ /**
+ * The system property {@code org.ini4j.config.escape} sets the initial value of {@link
+ * #isEscape()}. This constant is the part after {@link #KEY_PREFIX}.
+ */
public static final String PROP_ESCAPE = "escape";
+
+ /**
+ * The system property {@code org.ini4j.config.escapeNewline} sets the initial value of {@link
+ * #isEscapeNewline()}. This constant is the part after {@link #KEY_PREFIX}.
+ */
public static final String PROP_ESCAPE_NEWLINE = "escapeNewline";
+
+ /**
+ * The system property {@code org.ini4j.config.escapeKey} sets the initial value of {@link
+ * #isEscapeKeyOnly()}. This constant is the part after {@link #KEY_PREFIX}.
+ *
+ * The value is {@code escapeKey}, not {@code escapeKeyOnly}.
+ */
public static final String PROP_ESCAPE_KEY_ONLY = "escapeKey";
+
+ /**
+ * The system property {@code org.ini4j.config.pathSeparator} sets the initial value of {@link
+ * #getPathSeparator()}. This constant is the part after {@link #KEY_PREFIX}.
+ */
public static final String PROP_PATH_SEPARATOR = "pathSeparator";
+
+ /**
+ * The system property {@code org.ini4j.config.tree} sets the initial value of {@link #isTree()}.
+ * This constant is the part after {@link #KEY_PREFIX}.
+ */
public static final String PROP_TREE = "tree";
+
+ /**
+ * The system property {@code org.ini4j.config.propertyFirstUpper} sets the initial value of
+ * {@link #isPropertyFirstUpper()}. This constant is the part after {@link #KEY_PREFIX}.
+ */
public static final String PROP_PROPERTY_FIRST_UPPER = "propertyFirstUpper";
+
+ /**
+ * The system property {@code org.ini4j.config.fileEncoding} sets the initial value of {@link
+ * #getFileEncoding()}. This constant is the part after {@link #KEY_PREFIX}.
+ */
public static final String PROP_FILE_ENCODING = "fileEncoding";
+
+ /**
+ * The system property {@code org.ini4j.config.lineSeparator} sets the initial value of {@link
+ * #getLineSeparator()}. This constant is the part after {@link #KEY_PREFIX}.
+ */
public static final String PROP_LINE_SEPARATOR = "lineSeparator";
+
+ /**
+ * The system property {@code org.ini4j.config.comment} sets the initial value of {@link
+ * #isComment()}. This constant is the part after {@link #KEY_PREFIX}.
+ */
public static final String PROP_COMMENT = "comment";
+
+ /**
+ * The system property {@code org.ini4j.config.headerComment} sets the initial value of {@link
+ * #isHeaderComment()}. This constant is the part after {@link #KEY_PREFIX}.
+ */
public static final String PROP_HEADER_COMMENT = "headerComment";
+
+ /**
+ * The system property {@code org.ini4j.config.maxResolveDepth} sets the initial value of {@link
+ * #getMaxResolveDepth()}. This constant is the part after {@link #KEY_PREFIX}.
+ */
public static final String PROP_MAX_RESOLVE_DEPTH = "maxResolveDepth";
+
+ /** The default of {@link #isEmptyOption()}: {@code false}. */
public static final boolean DEFAULT_EMPTY_OPTION = false;
+
+ /** The default of {@link #isEmptySection()}: {@code false}. */
public static final boolean DEFAULT_EMPTY_SECTION = false;
+
+ /** The default of {@link #isGlobalSection()}: {@code false}. */
public static final boolean DEFAULT_GLOBAL_SECTION = false;
+
+ /** The default of {@link #getGlobalSectionName()}: {@code "?"}. */
public static final String DEFAULT_GLOBAL_SECTION_NAME = "?";
+
+ /** The default of {@link #isInclude()}: {@code false}. */
public static final boolean DEFAULT_INCLUDE = false;
+
+ /** The default of {@link #isLowerCaseOption()}: {@code false}. */
public static final boolean DEFAULT_LOWER_CASE_OPTION = false;
+
+ /** The default of {@link #isLowerCaseSection()}: {@code false}. */
public static final boolean DEFAULT_LOWER_CASE_SECTION = false;
+
+ /** The default of {@link #isMultiOption()}: {@code true}. */
public static final boolean DEFAULT_MULTI_OPTION = true;
+
+ /** The default of {@link #isMultiSection()}: {@code false}. */
public static final boolean DEFAULT_MULTI_SECTION = false;
+
+ /** The default of {@link #isStrictOperator()}: {@code false}. */
public static final boolean DEFAULT_STRICT_OPERATOR = false;
+
+ /** The default of {@link #isUnnamedSection()}: {@code false}. */
public static final boolean DEFAULT_UNNAMED_SECTION = false;
+
+ /** The default of {@link #isEscape()}: {@code true}. */
public static final boolean DEFAULT_ESCAPE = true;
+
+ /** The default of {@link #isEscapeNewline()}: {@code true}. */
public static final boolean DEFAULT_ESCAPE_NEWLINE = true;
+
+ /** The default of {@link #isEscapeKeyOnly()}: {@code false}. */
public static final boolean DEFAULT_ESCAPE_KEY_ONLY = false;
+
+ /** The default of {@link #isTree()}: {@code true}. */
public static final boolean DEFAULT_TREE = true;
+
+ /** The default of {@link #isPropertyFirstUpper()}: {@code false}. */
public static final boolean DEFAULT_PROPERTY_FIRST_UPPER = false;
+
+ /** The default of {@link #isComment()}: {@code true}. */
public static final boolean DEFAULT_COMMENT = true;
+
+ /** The default of {@link #isHeaderComment()}: {@code true}. */
public static final boolean DEFAULT_HEADER_COMMENT = true;
+
+ /** The default of {@link #getPathSeparator()}: {@code '/'}. */
public static final char DEFAULT_PATH_SEPARATOR = '/';
+
+ /**
+ * The default of {@link #getLineSeparator()}: the value of the system property {@code
+ * line.separator}, or {@code "\n"} if that cannot be read.
+ */
public static final String DEFAULT_LINE_SEPARATOR = getSystemProperty("line.separator", "\n");
+
+ /** The default of {@link #getFileEncoding()}: UTF-8. */
public static final Charset DEFAULT_FILE_ENCODING = StandardCharsets.UTF_8;
+
+ /** The default of {@link #getMaxResolveDepth()}: {@code 16}. */
public static final int DEFAULT_MAX_RESOLVE_DEPTH = 16;
+
private static final Config GLOBAL = new Config();
private static final long serialVersionUID = 2865793267410367814L;
private boolean _comment;
@@ -95,15 +298,43 @@ public class Config implements Cloneable, Serializable {
private boolean _unnamedSection;
private int _maxResolveDepth;
+ /**
+ * Creates a configuration.
+ *
+ * Every option gets the value of its system property, or its default if the property is not
+ * set. See {@link #reset()}.
+ *
+ * @throws StringIndexOutOfBoundsException if the {@link #PROP_PATH_SEPARATOR} property is empty
+ * @throws java.nio.charset.UnsupportedCharsetException if the {@link #PROP_FILE_ENCODING}
+ * property names an unknown character set
+ * @throws java.nio.charset.IllegalCharsetNameException if the {@link #PROP_FILE_ENCODING}
+ * property is not a legal character set name
+ */
@edu.umd.cs.findbugs.annotations.SuppressFBWarnings("SING_SINGLETON_HAS_NONPRIVATE_CONSTRUCTOR")
public Config() {
reset();
}
+ /**
+ * Returns an environment variable.
+ *
+ * @param name the name of the variable
+ * @return the value, or {@code null} if the variable is not set or cannot be read
+ */
public static String getEnvironment(String name) {
return getEnvironment(name, null);
}
+ /**
+ * Returns an environment variable, or a default.
+ *
+ * A {@link SecurityException} from the security manager is treated as if the variable were not
+ * set.
+ *
+ * @param name the name of the variable
+ * @param defaultValue the value to return when the variable is not set or cannot be read
+ * @return the value of the variable, or {@code defaultValue}
+ */
public static String getEnvironment(String name, String defaultValue) {
String value;
@@ -116,15 +347,43 @@ public static String getEnvironment(String name, String defaultValue) {
return (value == null) ? defaultValue : value;
}
+ /**
+ * Returns the global configuration.
+ *
+ * The global configuration is one shared object. {@link Ini} starts with it directly, while
+ * {@link Options} and {@link Reg} start with a copy of it. {@link BasicProfile} and {@link
+ * BasicOptionMap} objects that are not one of those classes use it too, and so do the parsers and
+ * formatters of the {@code org.ini4j.spi} package until they are given another configuration. A
+ * change to it therefore affects all of them. It reads the system properties once, when this
+ * class is loaded.
+ *
+ * @return the global configuration, not a copy
+ */
@edu.umd.cs.findbugs.annotations.SuppressFBWarnings("MS_EXPOSE_REP")
public static Config getGlobal() {
return GLOBAL;
}
+ /**
+ * Returns a system property.
+ *
+ * @param name the name of the property
+ * @return the value, or {@code null} if the property is not set or cannot be read
+ */
public static String getSystemProperty(String name) {
return getSystemProperty(name, null);
}
+ /**
+ * Returns a system property, or a default.
+ *
+ * A {@link SecurityException} from the security manager is treated as if the property were not
+ * set.
+ *
+ * @param name the name of the property
+ * @param defaultValue the value to return when the property is not set or cannot be read
+ * @return the value of the property, or {@code defaultValue}
+ */
public static String getSystemProperty(String name, String defaultValue) {
String value;
@@ -137,182 +396,580 @@ public static String getSystemProperty(String name, String defaultValue) {
return (value == null) ? defaultValue : value;
}
+ /**
+ * Sets the value of {@link #isComment()}.
+ *
+ * @param value the new value
+ */
public void setComment(boolean value) {
_comment = value;
}
+ /**
+ * Tells whether special characters are escaped with a backslash.
+ *
+ * When it is on, the parser decodes backslash sequences in names and values: {@code \t},
+ * {@code \n}, {@code \f}, {@code \b}, {@code \r}, {@code \:}, {@code \=} and {@code \\}, and a
+ * backslash followed by {@code u} and four hexadecimal digits for a character by its code. A
+ * backslash before any other character is dropped. A malformed sequence with {@code u} throws an
+ * {@link IllegalArgumentException}. The formatter writes those characters in the same form, and
+ * every other character outside the printable ASCII range with the {@code u} form, even if the
+ * file encoding could hold it. Section names are escaped like option names. See also {@link
+ * #isEscapeKeyOnly()}.
+ *
+ * {@link Reg} starts with it off.
+ *
+ * The initial value comes from the system property {@code org.ini4j.config.escape} if it is
+ * set, otherwise from {@link #DEFAULT_ESCAPE}.
+ *
+ * @return {@code true} if it is on
+ */
public boolean isEscape() {
return _escape;
}
+ /**
+ * Tells whether a backslash at the end of a line continues the line.
+ *
+ * When it is on, the parser removes a backslash that ends a line (an odd number of
+ * backslashes) and appends the next line, with its leading white space removed, to the same
+ * logical line. This applies to the parser only.
+ *
+ * The initial value comes from the system property {@code org.ini4j.config.escapeNewline} if
+ * it is set, otherwise from {@link #DEFAULT_ESCAPE_NEWLINE}.
+ *
+ * @return {@code true} if it is on
+ */
public boolean isEscapeNewline() {
return _escapeNewline;
}
+ /**
+ * Tells whether the parser follows include lines.
+ *
+ * When it is on, a line of the form {@code The initial value comes from the system property {@code org.ini4j.config.include} if it is
+ * set, otherwise from {@link #DEFAULT_INCLUDE}.
+ *
+ * @return {@code true} if it is on
+ */
public boolean isInclude() {
return _include;
}
+ /**
+ * Tells whether adding a section also adds its missing parents.
+ *
+ * When it is on, {@link Profile#add(String)} on an {@link Ini} or a {@link Reg} adds the
+ * sections for the missing levels of the name first, so that adding {@code a/b/c} also adds
+ * {@code a} and {@code a/b}. The tree methods of {@link Profile.Section} work either way, but
+ * they find only the sections that exist.
+ *
+ * The initial value comes from the system property {@code org.ini4j.config.tree} if it is set,
+ * otherwise from {@link #DEFAULT_TREE}.
+ *
+ * @return {@code true} if it is on
+ */
public boolean isTree() {
return _tree;
}
+ /**
+ * Sets the value of {@link #isEmptyOption()}.
+ *
+ * @param value the new value
+ */
public void setEmptyOption(boolean value) {
_emptyOption = value;
}
+ /**
+ * Sets the value of {@link #isEmptySection()}.
+ *
+ * @param value the new value
+ */
public void setEmptySection(boolean value) {
_emptySection = value;
}
+ /**
+ * Sets the value of {@link #isEscape()}.
+ *
+ * @param value the new value
+ */
public void setEscape(boolean value) {
_escape = value;
}
+ /**
+ * Sets the value of {@link #isEscapeKeyOnly()}.
+ *
+ * @param value the new value
+ */
public void setEscapeKeyOnly(boolean value) {
_escapeKeyOnly = value;
}
+ /**
+ * Sets the value of {@link #isEscapeNewline()}.
+ *
+ * @param value the new value
+ */
public void setEscapeNewline(boolean value) {
_escapeNewline = value;
}
+ /**
+ * Returns the character set used to read and write streams and files.
+ *
+ * It is used by the load and store methods that take a stream, a file or a URL. The methods
+ * that take a {@link java.io.Reader} or a {@link java.io.Writer} do not use it. When an {@link
+ * Ini} or an {@link Options} loads from a URL or a file, a byte order mark at the start of the
+ * input overrides it. {@link Reg} starts with UTF-16 little endian.
+ *
+ * The initial value comes from the system property {@code org.ini4j.config.fileEncoding} if it
+ * is set, otherwise from {@link #DEFAULT_FILE_ENCODING}.
+ *
+ * @return the character set
+ */
public Charset getFileEncoding() {
return _fileEncoding;
}
+ /**
+ * Sets the value of {@link #getFileEncoding()}.
+ *
+ * @param value the new value
+ */
public void setFileEncoding(Charset value) {
_fileEncoding = value;
}
+ /**
+ * Sets the value of {@link #isGlobalSection()}.
+ *
+ * @param value the new value
+ */
public void setGlobalSection(boolean value) {
_globalSection = value;
}
+ /**
+ * Returns the name of the section that holds the options before the first section header.
+ *
+ * It is used only when {@link #isGlobalSection()} is on.
+ *
+ * The initial value comes from the system property {@code org.ini4j.config.globalSectionName}
+ * if it is set, otherwise from {@link #DEFAULT_GLOBAL_SECTION_NAME}.
+ *
+ * @return the section name
+ */
public String getGlobalSectionName() {
return _globalSectionName;
}
+ /**
+ * Sets the value of {@link #getGlobalSectionName()}.
+ *
+ * @param value the new value
+ */
public void setGlobalSectionName(String value) {
_globalSectionName = value;
}
+ /**
+ * Sets the value of {@link #isHeaderComment()}.
+ *
+ * @param value the new value
+ */
public void setHeaderComment(boolean value) {
_headerComment = value;
}
+ /**
+ * Sets the value of {@link #isInclude()}.
+ *
+ * @param value the new value
+ */
public void setInclude(boolean value) {
_include = value;
}
+ /**
+ * Returns the line separator.
+ *
+ * The formatter ends every line with it. The parser joins the lines of a multi-line comment
+ * with it, and the formatter splits a comment into lines at it. {@link Reg} starts with {@code CR
+ * LF}.
+ *
+ * The initial value comes from the system property {@code org.ini4j.config.lineSeparator} if
+ * it is set, otherwise from {@link #DEFAULT_LINE_SEPARATOR}.
+ *
+ * @return the line separator
+ */
public String getLineSeparator() {
return _lineSeparator;
}
+ /**
+ * Sets the value of {@link #getLineSeparator()}.
+ *
+ * @param value the new value
+ */
public void setLineSeparator(String value) {
_lineSeparator = value;
}
+ /**
+ * Sets the value of {@link #isLowerCaseOption()}.
+ *
+ * @param value the new value
+ */
public void setLowerCaseOption(boolean value) {
_lowerCaseOption = value;
}
+ /**
+ * Sets the value of {@link #isLowerCaseSection()}.
+ *
+ * @param value the new value
+ */
public void setLowerCaseSection(boolean value) {
_lowerCaseSection = value;
}
+ /**
+ * Sets the value of {@link #isMultiOption()}.
+ *
+ * @param value the new value
+ */
public void setMultiOption(boolean value) {
_multiOption = value;
}
+ /**
+ * Sets the value of {@link #isMultiSection()}.
+ *
+ * @param value the new value
+ */
public void setMultiSection(boolean value) {
_multiSection = value;
}
+ /**
+ * Tells whether an option may have no value.
+ *
+ * When it is on, the parser accepts a line that has no operator and reads it as an option with
+ * that text as its name and a {@code null} value. The formatter writes a {@code null} value as an
+ * empty value. When it is off, the parser reports such a line as an {@link
+ * InvalidFileFormatException} and the formatter leaves the option out.
+ *
+ * {@link Options} and {@link Reg} start with it on.
+ *
+ * The initial value comes from the system property {@code org.ini4j.config.emptyOption} if it
+ * is set, otherwise from {@link #DEFAULT_EMPTY_OPTION}.
+ *
+ * @return {@code true} if it is on
+ */
public boolean isEmptyOption() {
return _emptyOption;
}
+ /**
+ * Tells whether sections without options are stored.
+ *
+ * When it is off, {@link Ini#store(java.io.Writer)} leaves out the sections that have no
+ * options. Loading is not affected: a section with no options in the input is loaded either way.
+ *
+ * {@link Reg} starts with it on.
+ *
+ * The initial value comes from the system property {@code org.ini4j.config.emptySection} if it
+ * is set, otherwise from {@link #DEFAULT_EMPTY_SECTION}.
+ *
+ * @return {@code true} if it is on
+ */
public boolean isEmptySection() {
return _emptySection;
}
+ /**
+ * Tells whether options before the first section header are allowed.
+ *
+ * When it is on, the parser puts such options in a section named {@link
+ * #getGlobalSectionName()}. The formatter writes the options of that section without a section
+ * header. When it is off, the parser reports an option before the first header as an {@link
+ * InvalidFileFormatException}.
+ *
+ * The initial value comes from the system property {@code org.ini4j.config.globalSection} if
+ * it is set, otherwise from {@link #DEFAULT_GLOBAL_SECTION}.
+ *
+ * @return {@code true} if it is on
+ */
public boolean isGlobalSection() {
return _globalSection;
}
+ /**
+ * Tells whether the parser converts option names to lower case.
+ *
+ * The conversion uses the default locale. It applies when loading only; names set in code are
+ * not changed.
+ *
+ * The initial value comes from the system property {@code org.ini4j.config.lowerCaseOption} if
+ * it is set, otherwise from {@link #DEFAULT_LOWER_CASE_OPTION}.
+ *
+ * @return {@code true} if it is on
+ */
public boolean isLowerCaseOption() {
return _lowerCaseOption;
}
+ /**
+ * Tells whether the parser converts section names to lower case.
+ *
+ * The conversion uses the default locale. It applies when loading only; names set in code are
+ * not changed.
+ *
+ * The initial value comes from the system property {@code org.ini4j.config.lowerCaseSection}
+ * if it is set, otherwise from {@link #DEFAULT_LOWER_CASE_SECTION}.
+ *
+ * @return {@code true} if it is on
+ */
public boolean isLowerCaseSection() {
return _lowerCaseSection;
}
+ /**
+ * Tells whether an option name can have several values.
+ *
+ * When it is on, the parser keeps every value of an option that appears more than once in a
+ * section, and the formatter writes them all. When it is off, a later value replaces the earlier
+ * one when loading. When storing an {@link Ini}, only the last value of each option is written,
+ * and when storing an {@link Options}, only the first. {@link Reg} starts with it on, and always
+ * writes all the values of a registry value name.
+ *
+ * The initial value comes from the system property {@code org.ini4j.config.multiOption} if it
+ * is set, otherwise from {@link #DEFAULT_MULTI_OPTION}.
+ *
+ * @return {@code true} if it is on
+ */
public boolean isMultiOption() {
return _multiOption;
}
+ /**
+ * Tells whether a section name can be used for several sections.
+ *
+ * When it is on, every section header in the input adds a new section, even if a section of
+ * that name exists already. When it is off, the options under a repeated header are added to the
+ * existing section. It applies when loading only.
+ *
+ * The initial value comes from the system property {@code org.ini4j.config.multiSection} if it
+ * is set, otherwise from {@link #DEFAULT_MULTI_SECTION}.
+ *
+ * @return {@code true} if it is on
+ */
public boolean isMultiSection() {
return _multiSection;
}
+ /**
+ * Tells whether a section may have an empty name.
+ *
+ * When it is on, the parser accepts the header {@code []}. When it is off, it reports that
+ * header as an {@link InvalidFileFormatException}.
+ *
+ * The initial value comes from the system property {@code org.ini4j.config.unnamedSection} if
+ * it is set, otherwise from {@link #DEFAULT_UNNAMED_SECTION}.
+ *
+ * @return {@code true} if it is on
+ */
public boolean isUnnamedSection() {
return _unnamedSection;
}
+ /**
+ * Returns the character that separates the levels of a section name.
+ *
+ * A section named {@code a/b} (with the default) is a child of the section {@code a}. See
+ * {@link #isTree()} and {@link Profile.Section}. {@link Reg} starts with a backslash.
+ *
+ * The initial value comes from the system property {@code org.ini4j.config.pathSeparator} if
+ * it is set, otherwise from {@link #DEFAULT_PATH_SEPARATOR}.
+ *
+ * @return the path separator
+ */
public char getPathSeparator() {
return _pathSeparator;
}
+ /**
+ * Sets the value of {@link #getPathSeparator()}.
+ *
+ * @param value the new value
+ */
public void setPathSeparator(char value) {
_pathSeparator = value;
}
+ /**
+ * Sets the value of {@link #isPropertyFirstUpper()}.
+ *
+ * @param value the new value
+ */
public void setPropertyFirstUpper(boolean value) {
_propertyFirstUpper = value;
}
+ /**
+ * Tells whether bean property names start with an upper case letter in the file.
+ *
+ * When it is on, the bean methods ({@link OptionMap#as(Class)}, {@link
+ * OptionMap#from(Object)}, {@link OptionMap#to(Object)} and {@link Profile#as(Class)}) change the
+ * first letter of the property name to upper case to get the option or section name, so the
+ * property {@code age} is the option {@code Age}.
+ *
+ * The initial value comes from the system property {@code org.ini4j.config.propertyFirstUpper}
+ * if it is set, otherwise from {@link #DEFAULT_PROPERTY_FIRST_UPPER}.
+ *
+ * @return {@code true} if it is on
+ */
public boolean isPropertyFirstUpper() {
return _propertyFirstUpper;
}
+ /**
+ * Tells whether options are written without spaces around the operator.
+ *
+ * When it is on, an option is written as {@code name=value}. When it is off, it is written as
+ * {@code name = value}. The parser accepts both forms either way.
+ *
+ * {@link Reg} starts with it on.
+ *
+ * The initial value comes from the system property {@code org.ini4j.config.strictOperator} if
+ * it is set, otherwise from {@link #DEFAULT_STRICT_OPERATOR}.
+ *
+ * @return {@code true} if it is on
+ */
public boolean isStrictOperator() {
return _strictOperator;
}
+ /**
+ * Sets the value of {@link #isStrictOperator()}.
+ *
+ * @param value the new value
+ */
public void setStrictOperator(boolean value) {
_strictOperator = value;
}
+ /**
+ * Tells whether comments are loaded and stored.
+ *
+ * When it is on, the parser keeps comments and the formatter writes them, as described in
+ * {@link CommentedMap}. When it is off, comments are skipped when loading and not written when
+ * storing.
+ *
+ * The initial value comes from the system property {@code org.ini4j.config.comment} if it is
+ * set, otherwise from {@link #DEFAULT_COMMENT}.
+ *
+ * @return {@code true} if it is on
+ */
public boolean isComment() {
return _comment;
}
+ /**
+ * Tells whether the first comment of a file is its header comment.
+ *
+ * When it is on, the comment at the top of the input, before the first section or option, is
+ * loaded as the comment of the whole {@link Profile} or {@link Options} object, and the formatter
+ * writes that comment first, followed by an empty line. When it is off, that comment belongs to
+ * the first section or option, and the formatter does not write the comment of the whole object.
+ * It works together with {@link #isComment()}.
+ *
+ * The initial value comes from the system property {@code org.ini4j.config.headerComment} if
+ * it is set, otherwise from {@link #DEFAULT_HEADER_COMMENT}.
+ *
+ * @return {@code true} if it is on
+ */
public boolean isHeaderComment() {
return _headerComment;
}
+ /**
+ * Sets the value of {@link #isTree()}.
+ *
+ * @param value the new value
+ */
public void setTree(boolean value) {
_tree = value;
}
+ /**
+ * Sets the value of {@link #isUnnamedSection()}.
+ *
+ * @param value the new value
+ */
public void setUnnamedSection(boolean value) {
_unnamedSection = value;
}
+ /**
+ * Tells whether only names are escaped, not values.
+ *
+ * It has an effect only when {@link #isEscape()} is on. Then names and section names are
+ * escaped and unescaped as usual, and values are not escaped or unescaped.
+ *
+ * The initial value comes from the system property {@code org.ini4j.config.escapeKey} if it is
+ * set, otherwise from {@link #DEFAULT_ESCAPE_KEY_ONLY}.
+ *
+ * @return {@code true} if it is on
+ */
public boolean isEscapeKeyOnly() {
return _escapeKeyOnly;
}
+ /**
+ * Returns the longest chain of variable references that is resolved.
+ *
+ * A value can contain variables whose values contain variables again. With a limit of {@code
+ * n}, a chain of {@code n} references is resolved, and a longer chain throws a {@link
+ * CircularReferenceException}. A value is only checked when it contains a dollar sign, and with a
+ * limit of {@code 0} every such value throws. The limit stops circular references, which would
+ * otherwise never end. A system property that is not a number is ignored. See {@link OptionMap}.
+ *
+ * The initial value comes from the system property {@code org.ini4j.config.maxResolveDepth} if
+ * it is set, otherwise from {@link #DEFAULT_MAX_RESOLVE_DEPTH}.
+ *
+ * @return the limit
+ */
public int getMaxResolveDepth() {
return _maxResolveDepth;
}
+ /**
+ * Sets the value of {@link #getMaxResolveDepth()}.
+ *
+ * @param value the new value
+ */
public void setMaxResolveDepth(int value) {
_maxResolveDepth = value;
}
+ /**
+ * Returns a copy of this configuration.
+ *
+ * @return a new configuration with the same values
+ */
@Override
public Config clone() {
try {
@@ -322,6 +979,20 @@ public Config clone() {
}
}
+ /**
+ * Sets every option to the value of its system property, or to its default if the property is not
+ * set.
+ *
+ * Values set with the setters are lost. A boolean property with a value other than {@code
+ * true} (in any letter case) is read as {@code false}, and a number property that cannot be
+ * parsed is ignored.
+ *
+ * @throws StringIndexOutOfBoundsException if the {@link #PROP_PATH_SEPARATOR} property is empty
+ * @throws java.nio.charset.UnsupportedCharsetException if the {@link #PROP_FILE_ENCODING}
+ * property names an unknown character set
+ * @throws java.nio.charset.IllegalCharsetNameException if the {@link #PROP_FILE_ENCODING}
+ * property is not a legal character set name
+ */
public final void reset() {
_emptyOption = getBoolean(PROP_EMPTY_OPTION, DEFAULT_EMPTY_OPTION);
_emptySection = getBoolean(PROP_EMPTY_SECTION, DEFAULT_EMPTY_SECTION);
diff --git a/src/main/java/org/ini4j/ConfigParser.java b/src/main/java/org/ini4j/ConfigParser.java
index 0f4a74d..93eb4f4 100644
--- a/src/main/java/org/ini4j/ConfigParser.java
+++ b/src/main/java/org/ini4j/ConfigParser.java
@@ -35,19 +35,70 @@
import org.ini4j.spi.IniHandler;
import org.ini4j.spi.Warnings;
+/**
+ * A reader and writer for INI files that follows the API of the Python {@code ConfigParser} module.
+ *
+ * It is meant for code that is ported from Python, or that wants methods such as {@link
+ * #getInt(String, String)} and {@link #items(String)}. The class is built on an {@link Ini} with
+ * its own configuration (a copy of the global one), in which escaping is off, the options of a
+ * repeated section name are added to the existing section, a repeated option replaces the earlier
+ * value, and the names of sections and options are converted to lower case when a file is read.
+ * Names given to the methods are not converted, so use lower case names to find what was read.
+ *
+ * A section named {@code DEFAULT} (in any letter case) is not a normal section. It does not show
+ * up in {@link #sections()}, and {@link #hasSection(String)} is {@code false} for it. Its options
+ * are used only to fill in the references of a value.
+ *
+ * A value can refer to other options with {@code %(name)}. It is replaced by the value of {@code
+ * name} in the same section, or, when there is no such option, in the {@code variables} map of the
+ * call, in the map given to the constructor, or in the {@code DEFAULT} section, in this order. A
+ * reference to a name that none of them has throws an {@link InterpolationMissingOptionException}.
+ * A percent sign preceded by a backslash is not a reference, and the backslash stays in the value.
+ * Unlike in Python, the reference has no trailing {@code s}. A value that refers to itself,
+ * directly or through other options, is not detected: the call does not return.
+ *
+ * The thread safety of {@link BasicMultiMap} applies.
+ *
+ * @see Ini
+ * @since 0.5.0
+ */
public class ConfigParser implements Serializable {
private static final long serialVersionUID = 9118857036229164353L;
private PyIni _ini;
+ /** Creates a parser with no default values. */
@SuppressWarnings(Warnings.UNCHECKED)
public ConfigParser() {
this(Collections.EMPTY_MAP);
}
+ /**
+ * Creates a parser with default values.
+ *
+ * The map is used as it is, not copied. It supplies values for references in the options (see
+ * the description of this class); it does not add options to the sections.
+ *
+ * @param defaults the default values for references, by option name
+ */
public ConfigParser(Map The values {@code 1}, {@code yes}, {@code true} and {@code on} give {@code true}, and {@code
+ * 0}, {@code no}, {@code false} and {@code off} give {@code false}, in any letter case.
+ *
+ * @param section the section name
+ * @param option the option name
+ * @return the value as a boolean
+ * @throws NoSectionException if the section does not exist
+ * @throws NoOptionException if the section has no such option
+ * @throws InterpolationException if a reference in the value cannot be resolved
+ * @throws IllegalArgumentException if the value is none of the accepted words; the message is the
+ * value
+ */
public boolean getBoolean(String section, String option)
throws NoSectionException, NoOptionException, InterpolationException {
boolean ret;
@@ -70,26 +121,77 @@ public boolean getBoolean(String section, String option)
return ret;
}
+ /**
+ * Returns the value of an option as a {@code double}, with references resolved.
+ *
+ * @param section the section name
+ * @param option the option name
+ * @return the value as a number
+ * @throws NoSectionException if the section does not exist
+ * @throws NoOptionException if the section has no such option
+ * @throws InterpolationException if a reference in the value cannot be resolved
+ * @throws NumberFormatException if the value is not a number
+ */
public double getDouble(String section, String option)
throws NoSectionException, NoOptionException, InterpolationException {
return Double.parseDouble(get(section, option));
}
+ /**
+ * Returns the value of an option as a {@code float}, with references resolved.
+ *
+ * @param section the section name
+ * @param option the option name
+ * @return the value as a number
+ * @throws NoSectionException if the section does not exist
+ * @throws NoOptionException if the section has no such option
+ * @throws InterpolationException if a reference in the value cannot be resolved
+ * @throws NumberFormatException if the value is not a number
+ */
public float getFloat(String section, String option)
throws NoSectionException, NoOptionException, InterpolationException {
return Float.parseFloat(get(section, option));
}
+ /**
+ * Returns the value of an option as an {@code int}, with references resolved.
+ *
+ * @param section the section name
+ * @param option the option name
+ * @return the value as a number
+ * @throws NoSectionException if the section does not exist
+ * @throws NoOptionException if the section has no such option
+ * @throws InterpolationException if a reference in the value cannot be resolved
+ * @throws NumberFormatException if the value is not an integer
+ */
public int getInt(String section, String option)
throws NoSectionException, NoOptionException, InterpolationException {
return Integer.parseInt(get(section, option));
}
+ /**
+ * Returns the value of an option as a {@code long}, with references resolved.
+ *
+ * @param section the section name
+ * @param option the option name
+ * @return the value as a number
+ * @throws NoSectionException if the section does not exist
+ * @throws NoOptionException if the section has no such option
+ * @throws InterpolationException if a reference in the value cannot be resolved
+ * @throws NumberFormatException if the value is not an integer
+ */
public long getLong(String section, String option)
throws NoSectionException, NoOptionException, InterpolationException {
return Long.parseLong(get(section, option));
}
+ /**
+ * Adds an empty section.
+ *
+ * @param section the section name, used as it is
+ * @throws DuplicateSectionException if a section with this name exists already
+ * @throws IllegalArgumentException if the name is {@code DEFAULT} in any letter case
+ */
public void addSection(String section) throws DuplicateSectionException {
if (_ini.containsKey(section)) {
throw new DuplicateSectionException(section);
@@ -100,22 +202,60 @@ public void addSection(String section) throws DuplicateSectionException {
_ini.add(section);
}
+ /**
+ * Returns the default values given to the constructor.
+ *
+ * @return the map, not a copy
+ */
public Map Changing an entry of the returned list does not change the parser.
+ *
+ * @param sectionName the section name
+ * @param raw if {@code true}, the values are returned as stored
+ * @param variables values for references that the section does not have, by option name
+ * @return a new list of entries, in no particular order
+ * @throws NoSectionException if the section does not exist
+ * @throws InterpolationMissingOptionException if a reference in a value cannot be resolved
+ */
public List The files are read one after the other with {@link #read(File)}. A later file adds to what
+ * was read before and replaces options that are in both.
+ *
+ * @param filenames the names of the files
+ * @throws IOException if a file cannot be read
+ * @throws ParsingException if a file is not valid
+ */
public void read(String... filenames) throws IOException, ParsingException {
for (String filename : filenames) {
read(new File(filename));
}
}
+ /**
+ * Reads from a reader.
+ *
+ * The content is added to what the parser holds, and replaces options that are in both.
+ *
+ * @param reader the reader to read
+ * @throws IOException if reading fails
+ * @throws ParsingException if the content is not valid
+ */
public void read(Reader reader) throws IOException, ParsingException {
try {
_ini.load(reader);
@@ -188,6 +396,16 @@ public void read(Reader reader) throws IOException, ParsingException {
}
}
+ /**
+ * Reads from a URL.
+ *
+ * The content is decoded with the file encoding that the global configuration had when this
+ * parser was created, unless a byte order mark at the start says otherwise.
+ *
+ * @param url the location to read
+ * @throws IOException if reading fails
+ * @throws ParsingException if the content is not valid
+ */
public void read(URL url) throws IOException, ParsingException {
try {
_ini.load(url);
@@ -196,6 +414,16 @@ public void read(URL url) throws IOException, ParsingException {
}
}
+ /**
+ * Reads a file.
+ *
+ * The file is decoded with the file encoding of {@link Config#getGlobal()} at the time of the
+ * call. A byte order mark is not detected.
+ *
+ * @param file the file to read
+ * @throws IOException if the file cannot be read
+ * @throws ParsingException if the content is not valid
+ */
public void read(File file) throws IOException, ParsingException {
try {
FileReader reader = new FileReader(file, Config.getGlobal().getFileEncoding());
@@ -209,6 +437,16 @@ public void read(File file) throws IOException, ParsingException {
}
}
+ /**
+ * Reads from a stream.
+ *
+ * The content is decoded with the file encoding that the global configuration had when this
+ * parser was created. A byte order mark is not detected.
+ *
+ * @param stream the stream to read
+ * @throws IOException if reading fails
+ * @throws ParsingException if the content is not valid
+ */
public void read(InputStream stream) throws IOException, ParsingException {
try {
_ini.load(stream);
@@ -217,6 +455,14 @@ public void read(InputStream stream) throws IOException, ParsingException {
}
}
+ /**
+ * Removes an option from a section.
+ *
+ * @param sectionName the section name
+ * @param optionName the option name
+ * @return {@code true} if the option existed
+ * @throws NoSectionException if the section does not exist
+ */
public boolean removeOption(String sectionName, String optionName) throws NoSectionException {
Ini.Section section = requireSection(sectionName);
boolean ret = section.containsKey(optionName);
@@ -226,6 +472,12 @@ public boolean removeOption(String sectionName, String optionName) throws NoSect
return ret;
}
+ /**
+ * Removes a section.
+ *
+ * @param sectionName the section name
+ * @return {@code true} if the section existed
+ */
public boolean removeSection(String sectionName) {
boolean ret = _ini.containsKey(sectionName);
@@ -234,10 +486,26 @@ public boolean removeSection(String sectionName) {
return ret;
}
+ /**
+ * Returns the section names.
+ *
+ * @return a new list of names, in the order of the sections, without {@code DEFAULT}
+ */
public List The option name is used as it is, not converted to lower case.
+ *
+ * @param sectionName the section name
+ * @param optionName the option name
+ * @param value the new value, stored as {@link Object#toString()}; with {@code null} the option
+ * is removed
+ * @throws NoSectionException if the section does not exist
+ */
public void set(String sectionName, String optionName, Object value) throws NoSectionException {
Ini.Section section = requireSection(sectionName);
@@ -248,14 +516,40 @@ public void set(String sectionName, String optionName, Object value) throws NoSe
}
}
+ /**
+ * Writes the sections and options.
+ *
+ * The {@code DEFAULT} section comes first. Comments are not written.
+ *
+ * @param writer the writer to write
+ * @throws IOException if writing fails
+ */
public void write(Writer writer) throws IOException {
_ini.store(writer);
}
+ /**
+ * Writes the sections and options to a stream.
+ *
+ * The content is the same as in {@link #write(Writer)}. It is encoded with the file encoding
+ * that the global configuration had when this parser was created.
+ *
+ * @param stream the stream to write
+ * @throws IOException if writing fails
+ */
public void write(OutputStream stream) throws IOException {
_ini.store(stream);
}
+ /**
+ * Writes the sections and options to a file.
+ *
+ * The content is the same as in {@link #write(Writer)}. The file is created or overwritten,
+ * and encoded with the file encoding of {@link Config#getGlobal()}.
+ *
+ * @param file the file to write
+ * @throws IOException if the file cannot be written
+ */
public void write(File file) throws IOException {
FileWriter writer = new FileWriter(file, Config.getGlobal().getFileEncoding());
try {
@@ -265,6 +559,11 @@ public void write(File file) throws IOException {
}
}
+ /**
+ * Returns the underlying {@link Ini}.
+ *
+ * @return the object that holds the sections and options
+ */
protected Ini getIni() {
return _ini;
}
@@ -291,16 +590,32 @@ private Ini.Section requireSection(String sectionName) throws NoSectionException
return section;
}
+ /**
+ * The base class of the checked exceptions of {@link ConfigParser}.
+ *
+ * @since 0.5.0
+ */
public static class ConfigParserException extends Exception {
/** Use serialVersionUID for interoperability. */
private static final long serialVersionUID = -6845546313519392093L;
+ /**
+ * Creates an exception with a detail message.
+ *
+ * @param message the detail message
+ */
public ConfigParserException(String message) {
super(message);
}
}
+ /**
+ * Signals that {@link ConfigParser#addSection(String)} was called for a section that exists. The
+ * message is the section name.
+ *
+ * @since 0.5.0
+ */
public static final class DuplicateSectionException extends ConfigParserException {
/** Use serialVersionUID for interoperability. */
@@ -311,16 +626,32 @@ private DuplicateSectionException(String message) {
}
}
+ /**
+ * The base class of the exceptions for a value that refers to other options.
+ *
+ * @since 0.5.0
+ */
public static class InterpolationException extends ConfigParserException {
/** Use serialVersionUID for interoperability. */
private static final long serialVersionUID = 8924443303158546939L;
+ /**
+ * Creates an exception with a detail message.
+ *
+ * @param message the detail message
+ */
protected InterpolationException(String message) {
super(message);
}
}
+ /**
+ * Signals that a reference in a value names an option that cannot be found. The message is the
+ * option name.
+ *
+ * @since 0.5.0
+ */
public static final class InterpolationMissingOptionException extends InterpolationException {
/** Use serialVersionUID for interoperability. */
@@ -331,6 +662,11 @@ private InterpolationMissingOptionException(String message) {
}
}
+ /**
+ * Signals that a section has no option of the requested name. The message is the option name.
+ *
+ * @since 0.5.0
+ */
public static final class NoOptionException extends ConfigParserException {
/** Use serialVersionUID for interoperability. */
@@ -341,6 +677,11 @@ private NoOptionException(String message) {
}
}
+ /**
+ * Signals that there is no section of the requested name. The message is the section name.
+ *
+ * @since 0.5.0
+ */
public static final class NoSectionException extends ConfigParserException {
/** Use serialVersionUID for interoperability. */
@@ -351,6 +692,14 @@ private NoSectionException(String message) {
}
}
+ /**
+ * Signals that a file read by a {@link ConfigParser} is not valid.
+ *
+ * The message and the cause are those of the {@link InvalidFileFormatException} that the
+ * parser raised.
+ *
+ * @since 0.5.0
+ */
public static final class ParsingException extends IOException {
/** Use serialVersionUID for interoperability. */
diff --git a/src/main/java/org/ini4j/Configurable.java b/src/main/java/org/ini4j/Configurable.java
index 074d7a5..654c280 100644
--- a/src/main/java/org/ini4j/Configurable.java
+++ b/src/main/java/org/ini4j/Configurable.java
@@ -15,8 +15,30 @@
*/
package org.ini4j;
+/**
+ * An object whose parsing and formatting behavior is set by a {@link Config}.
+ *
+ * {@link Ini}, {@link Options} and {@link Reg} are configurable. {@link Ini} starts with the
+ * {@linkplain Config#getGlobal() global} configuration itself, which other objects share, so a
+ * change to it affects all of them. {@link Options} and {@link Reg} start with their own copy of
+ * the global configuration with some flags set for their format. Call {@link #setConfig(Config)}
+ * with a {@linkplain Config#clone() clone} to change the settings of one object only.
+ *
+ * @see Config
+ * @since 0.5.0
+ */
public interface Configurable {
+ /**
+ * Returns the configuration.
+ *
+ * @return the configuration in use
+ */
Config getConfig();
+ /**
+ * Sets the configuration.
+ *
+ * @param value the configuration to use from now on
+ */
void setConfig(Config value);
}
diff --git a/src/main/java/org/ini4j/Ini.java b/src/main/java/org/ini4j/Ini.java
index f39812b..3f12e70 100755
--- a/src/main/java/org/ini4j/Ini.java
+++ b/src/main/java/org/ini4j/Ini.java
@@ -31,31 +31,98 @@
import org.ini4j.spi.IniHandler;
import org.ini4j.spi.IniParser;
+/**
+ * An INI file in memory: a {@link Profile} that can be loaded from and stored to a file.
+ *
+ * An {@code Ini} holds named sections, each with options. A section name can be used more than
+ * once and an option can have several values (see {@link MultiMap} and the flags {@link
+ * Config#isMultiSection()} and {@link Config#isMultiOption()}). Values can contain variables,
+ * comments are kept, and the sections can be read as a tree or through your own interfaces (see
+ * {@link Profile}).
+ *
+ * A new {@code Ini} uses the global {@link Config} itself, not a copy (see {@link
+ * Config#getGlobal()}). Call {@link #setConfig(Config)} to give it its own. Loading and storing go
+ * through {@link org.ini4j.spi.IniParser} and {@link org.ini4j.spi.IniFormatter}, with the
+ * configuration of this object. {@code load} adds to the existing content, as described in {@link
+ * Persistable}.
+ *
+ * The methods that read or write a stream use the file encoding of the configuration. When a
+ * file or a URL is loaded, a byte order mark at the start of the input takes precedence over it.
+ * When an {@link java.io.InputStream} is loaded, there is no such detection.
+ *
+ * This reads two options and writes a new section:
+ *
+ * The thread safety of {@link BasicMultiMap} applies.
+ *
+ * @see Wini
+ * @see Options
+ * @since 0.3.0
+ */
@edu.umd.cs.findbugs.annotations.SuppressFBWarnings({"CT_CONSTRUCTOR_THROW", "EI_EXPOSE_REP"})
public class Ini extends BasicProfile implements Persistable, Configurable {
private static final long serialVersionUID = -6029486578113700585L;
private Config _config;
private File _file;
+ /** Creates an empty {@code Ini} that uses the global {@link Config}. */
public Ini() {
_config = Config.getGlobal();
}
+ /**
+ * Creates an {@code Ini} and loads it from a reader.
+ *
+ * @param input the reader to read
+ * @throws IOException if reading fails
+ * @throws InvalidFileFormatException if the content is not valid
+ */
public Ini(Reader input) throws IOException, InvalidFileFormatException {
this();
load(input);
}
+ /**
+ * Creates an {@code Ini} and loads it from a stream.
+ *
+ * @param input the stream to read
+ * @throws IOException if reading fails
+ * @throws InvalidFileFormatException if the content is not valid
+ */
public Ini(InputStream input) throws IOException, InvalidFileFormatException {
this();
load(input);
}
+ /**
+ * Creates an {@code Ini} and loads it from a URL.
+ *
+ * @param input the location to read
+ * @throws IOException if reading fails
+ * @throws InvalidFileFormatException if the content is not valid
+ */
public Ini(URL input) throws IOException, InvalidFileFormatException {
this();
load(input);
}
+ /**
+ * Creates an {@code Ini}, remembers the file and loads it.
+ *
+ * The file stays the associated file, so {@link #store()} writes back to it.
+ *
+ * @param input the file to read and later to write
+ * @throws IOException if reading fails
+ * @throws InvalidFileFormatException if the content is not valid
+ */
public Ini(File input) throws IOException, InvalidFileFormatException {
this();
_file = input;
@@ -141,10 +208,27 @@ public void store(File output) throws IOException {
}
}
+ /**
+ * Creates the handler that builds this object while a file is parsed.
+ *
+ * A subclass can override it to change how the parsed events are turned into sections and
+ * options.
+ *
+ * @return a new builder for this object
+ */
protected IniHandler newBuilder() {
return IniBuilder.newInstance(this);
}
+ /**
+ * Sends a section to a formatter, unless it is left out.
+ *
+ * A section without options is left out when {@link Config#isEmptySection()} is off. A
+ * subclass can override this method to change what is stored.
+ *
+ * @param formatter the handler that receives the events
+ * @param section the section to send
+ */
@Override
protected void store(IniHandler formatter, Profile.Section section) {
if (getConfig().isEmptySection() || (section.size() != 0)) {
@@ -152,6 +236,17 @@ protected void store(IniHandler formatter, Profile.Section section) {
}
}
+ /**
+ * Sends one value of an option to a formatter, unless it is left out.
+ *
+ * When {@link Config#isMultiOption()} is off, only the last value of an option is sent. A
+ * subclass can override this method to change what is stored.
+ *
+ * @param formatter the handler that receives the events
+ * @param section the section of the option
+ * @param option the option name
+ * @param index the position of the value
+ */
@Override
protected void store(IniHandler formatter, Profile.Section section, String option, int index) {
if (getConfig().isMultiOption() || (index == (section.length(option) - 1))) {
diff --git a/src/main/java/org/ini4j/IniPreferences.java b/src/main/java/org/ini4j/IniPreferences.java
index c7d8f5f..7f2294d 100755
--- a/src/main/java/org/ini4j/IniPreferences.java
+++ b/src/main/java/org/ini4j/IniPreferences.java
@@ -24,19 +24,51 @@
import java.util.prefs.AbstractPreferences;
import java.util.prefs.BackingStoreException;
+/**
+ * A {@link java.util.prefs.Preferences} tree on top of an {@link Ini}.
+ *
+ * The root node is the {@code Ini} itself. Its child nodes are the sections, and the keys of a
+ * section node are its options. A section named {@code a/b} (with the default path separator) is
+ * the child {@code b} of the section {@code a}. The root node has no keys: {@code put} and {@code
+ * remove} throw an {@link UnsupportedOperationException}, and {@code get} returns the default
+ * value.
+ *
+ * Asking for a node that does not exist creates the section in the {@code Ini} at once. All
+ * changes stay in memory: {@code flush} and {@code sync} do nothing, so nothing is written to a
+ * file. To keep the changes, store the {@code Ini}, which you hold if you created this object with
+ * {@link #IniPreferences(Ini)}.
+ *
+ * The nodes use the locking of {@link java.util.prefs.AbstractPreferences}. The {@link Ini}
+ * itself is not synchronized.
+ *
+ * This example reads and changes a value:
+ *
+ * This is just a helper constructor, to make simpler constructing This is just a helper constructor, to make simpler constructing This is just a helper constructor, to make simpler constructing This implementation doesn't support this operation, so allways throws
- * UnsupportedOperationException.
+ * {@link java.util.prefs.Preferences#get(String, String)} catches the exception, so it returns
+ * the default value for every key of the root node.
*
- * @return if the value associated with the specified key at this preference node, or null if
- * there is no association for this key, or the association cannot be determined at this time.
- * @param key key to getvalue for
- * @throws UnsupportedOperationException this implementation allways throws this exception
+ * @param key the key
+ * @return nothing, the method always throws
+ * @throws UnsupportedOperationException always
*/
@Override
protected String getSpi(String key) throws UnsupportedOperationException {
@@ -115,12 +136,14 @@ protected String getSpi(String key) throws UnsupportedOperationException {
}
/**
- * Implements the A section is below another one if its name contains the path separator of the {@link Config}
+ * of the {@link Ini}.
+ *
+ * @return the names of the top level sections
+ * @throws BackingStoreException never thrown by this implementation
*/
@Override
protected String[] childrenNamesSpi() throws BackingStoreException {
@@ -136,11 +159,13 @@ protected String[] childrenNamesSpi() throws BackingStoreException {
}
/**
- * Implements the If the {@link Ini} has no such section yet, it is added at once, and the node is reported as
+ * new.
*
- * @param name child name
- * @return child node
+ * @param name the name of the section
+ * @return the node of the section
*/
@Override
protected SectionPreferences childSpi(String name) {
@@ -155,13 +180,9 @@ protected SectionPreferences childSpi(String name) {
}
/**
- * Implements the This implementation does nothing.
+ * Does nothing. The changes stay in the {@link Ini} in memory and are not written anywhere.
*
- * @throws BackingStoreException if this operation cannot be completed due to a failure in the
- * backing store, or inability to communicate with it.
+ * @throws BackingStoreException never thrown by this implementation
*/
@Override
protected void flushSpi() throws BackingStoreException {
@@ -169,14 +190,10 @@ protected void flushSpi() throws BackingStoreException {
}
/**
- * Implements the This implementation allways return an empty array.
- *
- * @return an empty array.
- * @throws BackingStoreException if this operation cannot be completed due to a failure in the
- * backing store, or inability to communicate with it.
+ * @return an empty array
+ * @throws BackingStoreException never thrown by this implementation
*/
@Override
protected String[] keysSpi() throws BackingStoreException {
@@ -184,15 +201,11 @@ protected String[] keysSpi() throws BackingStoreException {
}
/**
- * Implements the This implementation doesn;t support this operation, so allways throws
- * UnsupportedOperationException.
+ * Not supported. The root node has no keys.
*
- * @param key key to set value for
- * @param value new value for key
- * @throws UnsupportedOperationException this implementation allways throws this exception
+ * @param key the key
+ * @param value the value
+ * @throws UnsupportedOperationException always
*/
@Override
protected void putSpi(String key, String value) throws UnsupportedOperationException {
@@ -200,14 +213,10 @@ protected void putSpi(String key, String value) throws UnsupportedOperationExcep
}
/**
- * Implements the This implementation doesn;t support this operation, so allways throws
- * UnsupportedOperationException.
- *
- * @throws UnsupportedOperationException this implementation allways throws this exception
- * @throws BackingStoreException this implementation never throws this exception
+ * @throws UnsupportedOperationException always
+ * @throws BackingStoreException never thrown by this implementation
*/
@Override
protected void removeNodeSpi() throws BackingStoreException, UnsupportedOperationException {
@@ -215,11 +224,10 @@ protected void removeNodeSpi() throws BackingStoreException, UnsupportedOperatio
}
/**
- * Implements the This implementation does nothing.
+ * Does nothing. The data is not read again from anywhere.
*
- * @throws BackingStoreException if this operation cannot be completed due to a failure in the
- * backing store, or inability to communicate with it.
+ * @throws BackingStoreException never thrown by this implementation
*/
@Override
protected void syncSpi() throws BackingStoreException {
assert true;
}
+ /**
+ * The node of one section.
+ *
+ * The keys of the node are the option names of the section. {@code get} returns the last value
+ * of an option with its variables resolved, {@code put} replaces the last value and {@code
+ * remove} removes all the values. The child nodes are the sections below this one in the section
+ * tree, and a child that does not exist is added to the {@link Ini} when it is requested.
+ * Removing the node removes the section from the {@link Ini}.
+ *
+ * @since 0.3.0
+ */
protected class SectionPreferences extends AbstractPreferences {
- /** underlaying This implementation just call parent's This implementation just call parent's This implementation allways returns an empty array.
- *
- * @return an emty array.
- * @throws BackingStoreException if this operation cannot be completed due to a failure in the
- * backing store, or inability to communicate with it.
+ * @return the names of the sub-sections, relative to this section
+ * @throws BackingStoreException never thrown by this implementation
*/
@Override
protected String[] childrenNamesSpi() throws BackingStoreException {
@@ -316,14 +319,13 @@ protected String[] childrenNamesSpi() throws BackingStoreException {
}
/**
- * Implements the This implementation doesn't support this operation.
+ * If the sub-section does not exist yet, it is added to the {@link Ini} at once, and the
+ * node is reported as new.
*
- * @throws UnsupportedOperationException this implementation allways throws this exception
- * @param name child name
- * @return child node
+ * @param name the name of the sub-section, relative to this section
+ * @return the node of the sub-section
*/
@Override
protected SectionPreferences childSpi(String name) throws UnsupportedOperationException {
@@ -338,13 +340,9 @@ protected SectionPreferences childSpi(String name) throws UnsupportedOperationEx
}
/**
- * Implements the This implementation does nothing.
+ * Does nothing. The changes stay in the {@link Ini} in memory and are not written anywhere.
*
- * @throws BackingStoreException if this operation cannot be completed due to a failure in the
- * backing store, or inability to communicate with it.
+ * @throws BackingStoreException never thrown by this implementation
*/
@Override
protected void flushSpi() throws BackingStoreException {
@@ -352,12 +350,10 @@ protected void flushSpi() throws BackingStoreException {
}
/**
- * Implements the This implementation does nothing.
+ * Does nothing. The data is not read again from anywhere.
*
- * @throws BackingStoreException if this operation cannot be completed due to a failure in the
- * backing store, or inability to communicate with it.
+ * @throws BackingStoreException never thrown by this implementation
*/
@Override
protected void syncSpi() throws BackingStoreException {
diff --git a/src/main/java/org/ini4j/IniPreferencesFactory.java b/src/main/java/org/ini4j/IniPreferencesFactory.java
index 6f32e84..7e35542 100755
--- a/src/main/java/org/ini4j/IniPreferencesFactory.java
+++ b/src/main/java/org/ini4j/IniPreferencesFactory.java
@@ -22,14 +22,71 @@
import java.util.prefs.Preferences;
import java.util.prefs.PreferencesFactory;
+/**
+ * A {@link PreferencesFactory} that serves the {@code java.util.prefs} API from INI files.
+ *
+ * The user root and the system root are two separate {@link IniPreferences} trees. Each is built
+ * from an {@link Ini} loaded from a location that is read from the system property {@link
+ * #KEY_USER} or {@link #KEY_SYSTEM}. If the property is not set, the same key is looked up in the
+ * file {@link #PROPERTIES}, which is searched on the class path with the context class loader of
+ * the calling thread. If there is no location, the tree starts empty.
+ *
+ * A location with a scheme, such as {@code file:/etc/app.ini}, is used as a URL. A location
+ * without a scheme is the name of a resource on the class path. A location that cannot be read
+ * throws an {@link IllegalArgumentException} when the root is first requested. The changes made
+ * through the preferences stay in memory, because {@code flush} and {@code sync} do not write
+ * anything (see {@link IniPreferences}).
+ *
+ * To let {@link Preferences#userRoot()} use it, name the class in the system property {@code
+ * java.util.prefs.PreferencesFactory} before the preferences API is used for the first time,
+ * because the factory is chosen only once:
+ *
+ * Thread safety. {@link #systemRoot()} and {@link #userRoot()} are
+ * synchronized. Each root is created on the first call and every later call returns the same
+ * object.
+ *
+ * @see IniPreferences
+ * @since 0.3.0
+ */
@edu.umd.cs.findbugs.annotations.SuppressFBWarnings("EI_EXPOSE_REP")
public class IniPreferencesFactory implements PreferencesFactory {
+ /**
+ * The name of the class path resource that can hold the locations, as a properties file with the
+ * keys {@link #KEY_USER} and {@link #KEY_SYSTEM}.
+ */
public static final String PROPERTIES = "ini4j.properties";
+
+ /**
+ * The key of the location of the user preferences, used as a system property and as a key in
+ * {@link #PROPERTIES}.
+ */
public static final String KEY_USER = "org.ini4j.prefs.user";
+
+ /**
+ * The key of the location of the system preferences, used as a system property and as a key in
+ * {@link #PROPERTIES}.
+ */
public static final String KEY_SYSTEM = "org.ini4j.prefs.system";
+
private Preferences _system;
private Preferences _user;
+ /**
+ * Returns the root of the system preferences.
+ *
+ * The root is created on the first call, from the location named by {@link #KEY_SYSTEM}.
+ *
+ * @return the same root on every call
+ * @throws IllegalArgumentException if the location cannot be read or is not valid on the first
+ * call
+ */
@Override
public synchronized Preferences systemRoot() {
if (_system == null) {
@@ -39,6 +96,15 @@ public synchronized Preferences systemRoot() {
return _system;
}
+ /**
+ * Returns the root of the user preferences.
+ *
+ * The root is created on the first call, from the location named by {@link #KEY_USER}.
+ *
+ * @return the same root on every call
+ * @throws IllegalArgumentException if the location cannot be read or is not valid on the first
+ * call
+ */
@Override
public synchronized Preferences userRoot() {
if (_user == null) {
diff --git a/src/main/java/org/ini4j/InvalidFileFormatException.java b/src/main/java/org/ini4j/InvalidFileFormatException.java
index 5a75dc7..1550070 100755
--- a/src/main/java/org/ini4j/InvalidFileFormatException.java
+++ b/src/main/java/org/ini4j/InvalidFileFormatException.java
@@ -17,9 +17,25 @@
import java.io.IOException;
+/**
+ * Signals that the content being loaded is not valid for the format.
+ *
+ * The parsers throw it, for example, for a line that is neither a section header nor an option,
+ * or for a registry file with a missing or unsupported version header. The message of a parse error
+ * names the line number and the line. It is an {@link IOException}, so the {@code load} methods of
+ * {@link Persistable} declare it without a new checked type.
+ *
+ * @see Persistable#load()
+ * @since 0.5.0
+ */
public class InvalidFileFormatException extends IOException {
private static final long serialVersionUID = -4354616830804732309L;
+ /**
+ * Constructs an exception with a detail message.
+ *
+ * @param message the detail message
+ */
public InvalidFileFormatException(String message) {
super(message);
}
diff --git a/src/main/java/org/ini4j/MultiMap.java b/src/main/java/org/ini4j/MultiMap.java
index d363d20..4b5c552 100644
--- a/src/main/java/org/ini4j/MultiMap.java
+++ b/src/main/java/org/ini4j/MultiMap.java
@@ -18,20 +18,111 @@
import java.util.List;
import java.util.Map;
+/**
+ * A {@link Map} that can hold more than one value for a key.
+ *
+ * The values of a key are kept in insertion order and are addressed by a zero-based index. The
+ * methods inherited from {@link Map} work on the whole key: {@link #get(Object)} returns the last
+ * value, {@link #put(Object, Object)} replaces the last value (or adds the first one) and {@link
+ * #remove(Object)} removes every value of the key. The methods declared here give access to the
+ * other values.
+ *
+ * A {@link Profile} is a multi-map of sections and an {@link OptionMap} is a multi-map of
+ * options, so a profile can hold several sections with the same name and a section can hold several
+ * options with the same name. {@link Config#isMultiSection()} and {@link Config#isMultiOption()}
+ * decide whether loading a file keeps such repeats. For example, if a section has the option {@code
+ * fortuneNumber} three times, {@code section.get("fortuneNumber", 1)} returns the second one and
+ * {@code section.length("fortuneNumber")} returns {@code 3}.
+ *
+ * @param {@link BasicMultiMap} returns the list it stores, not a copy, so changes to the list change
+ * the map.
+ *
+ * @param key the key
+ * @return the values of the key in insertion order, or {@code null} if the key is not in the map
+ */
List The values at that position and after it move one place up.
+ *
+ * @param key the key; it is added to the map if it is not there yet
+ * @param value the value to insert
+ * @param index the position of the new value
+ * @throws IndexOutOfBoundsException if the index is negative or greater than the number of values
+ * the key has
+ */
void add(K key, V value, int index);
+ /**
+ * Returns the value of a key at the given position.
+ *
+ * @param key the key
+ * @param index the position of the value
+ * @return the value, or {@code null} if the key is not in the map
+ * @throws IndexOutOfBoundsException if the key is in the map and the index is out of range
+ */
V get(Object key, int index);
+ /**
+ * Returns the number of values a key has.
+ *
+ * @param key the key
+ * @return the number of values, or {@code 0} if the key is not in the map
+ */
int length(Object key);
+ /**
+ * Replaces the value of a key at the given position.
+ *
+ * @param key the key; it must be in the map
+ * @param value the new value
+ * @param index the position of the value to replace
+ * @return the value that was replaced
+ * @throws IndexOutOfBoundsException if the index is out of range
+ * @throws NullPointerException if the key is not in the map (this is what {@link BasicMultiMap}
+ * does)
+ */
V put(K key, V value, int index);
+ /**
+ * Replaces all the values of a key with a copy of the given values.
+ *
+ * @param key the key
+ * @param values the new values; {@link BasicMultiMap} copies the list, so later changes to it do
+ * not affect the map
+ * @return the list of the values the key had before, or {@code null} if the key was not in the
+ * map
+ */
List When the last value of a key is removed, the key is removed from the map too.
+ *
+ * @param key the key
+ * @param index the position of the value to remove
+ * @return the removed value, or {@code null} if the key is not in the map
+ * @throws IndexOutOfBoundsException if the key is in the map and the index is out of range
+ */
V remove(Object key, int index);
}
diff --git a/src/main/java/org/ini4j/OptionMap.java b/src/main/java/org/ini4j/OptionMap.java
index 8943d00..add928f 100644
--- a/src/main/java/org/ini4j/OptionMap.java
+++ b/src/main/java/org/ini4j/OptionMap.java
@@ -15,50 +15,366 @@
*/
package org.ini4j;
+/**
+ * A map of named options, where each option can have several values.
+ *
+ * An option map is the content of a section of a {@link Profile}, or of an {@link Options} file.
+ * Names and values are strings. The values of one name are indexed as in {@link MultiMap}, and
+ * every name can also have a comment as in {@link CommentedMap}. A stored value can be {@code
+ * null}, for example for an option that has a name but no value in the file.
+ *
+ * On top of the string access this interface offers methods that convert values, resolve
+ * variables and work with beans.
+ *
+ * The {@code get} and {@code getAll} methods with a {@link Class} argument convert the stored
+ * text to another type. Supported types are the primitive types and their wrappers, {@link String},
+ * {@link Character}, {@link java.io.File}, {@link java.net.URL}, {@link java.net.URI}, {@link
+ * Class}, {@link java.util.TimeZone}, and any class with a static {@code valueOf(String)} method. A
+ * conversion that fails throws an {@link IllegalArgumentException}, except that converting an empty
+ * value to {@link Character} throws a {@link StringIndexOutOfBoundsException}. A missing name or a
+ * {@code null} value converts to the zero value of a primitive type ({@code 0}, {@code false} or
+ * {@code '\0'}) and to {@code null} for any other type. The {@code put} and {@code add} methods
+ * that take an {@link Object} store {@link String#valueOf(Object)} of the value, and keep {@code
+ * null} as {@code null}.
+ *
+ * The {@code fetch} methods work like the {@code get} methods, but they first replace variables
+ * in the value. A variable is written as {@code ${name}} for the last value of the option {@code
+ * name} in the same map, or {@code ${name[2]}} for the value at index 2. A variable written as
+ * {@code ${@env/NAME}} reads the environment variable {@code NAME} and {@code ${@prop/name}} reads
+ * the system property {@code name}. A variable with a backslash in front of the dollar sign is not
+ * resolved. A variable that refers to a missing option, environment variable or property is left in
+ * the text unchanged. A value can contain variables that contain variables, up to the limit of
+ * {@link Config#getMaxResolveDepth()}; deeper nesting, such as an option that refers to itself,
+ * throws a {@link CircularReferenceException}. In a section of a {@link Profile} a variable can
+ * also name an option of another section; see {@link Profile#fetch(Object, Object)}.
+ *
+ * {@link #as(Class)} gives a typed view of the map through an interface, and {@link
+ * #from(Object)} and {@link #to(Object)} copy the values between the map and a bean. The option
+ * name of a bean property is the property name, for example {@code homeDir} for {@code
+ * getHomeDir()}, with the first letter in upper case if the map was created that way (see {@link
+ * Config#isPropertyFirstUpper()}).
+ *
+ * @see Profile.Section
+ * @see Options
+ * @since 0.4.1
+ */
public interface OptionMap extends MultiMap The values are returned as stored, without variable substitution. Use {@link
+ * #fetchAll(Object, Class)} to resolve variables.
+ *
+ * @param The returned object is a dynamic proxy. It is backed by this map, so it always shows the
+ * current content and its setters change the map. A getter such as {@code getAge()} reads the
+ * option {@code age} as {@link #fetch(Object)} does (variables are resolved) and converts the
+ * value to the return type. A getter returns the zero value of its type if the option is missing
+ * or the value cannot be converted. A setter such as {@code setAge(int)} replaces the last value
+ * of the option with the given value. A {@code hasAge()} method tells whether the option exists.
+ * For an array property, the getter reads all the values and the setter replaces all of them. A
+ * setter does not accept {@code null}: it throws a {@link NullPointerException} for a {@code
+ * null} value, array or array element, and an array setter has already removed the existing
+ * values by then. Interfaces can also declare the {@code addPropertyChangeListener} and {@code
+ * addVetoableChangeListener} methods (and the matching {@code remove} methods), which take the
+ * property name and the listener. The proxy does not implement the methods of {@link Object}:
+ * {@code toString()} returns {@code null}, and {@code equals} and {@code hashCode} throw an
+ * exception.
+ *
+ * @param It works like {@link #as(Class)}, except that the option for a property is named by the
+ * prefix followed by the property name. With the prefix {@code "dwarf."}, the getter {@code
+ * getAge()} reads the option {@code dwarf.age}.
+ *
+ * @param See the description of this interface for the variable syntax.
+ *
+ * @param key the option name
+ * @return the resolved value, or {@code null} if the option is missing or its value is {@code
+ * null}
+ * @throws CircularReferenceException if the variables are nested deeper than {@link
+ * Config#getMaxResolveDepth()}
+ */
String fetch(Object key);
+ /**
+ * Returns the last value of an option, or a default if the option is missing.
+ *
+ * In {@link BasicOptionMap} the value is returned as stored, the same as {@link #get(Object,
+ * String)}: variables are not resolved.
+ *
+ * @param key the option name
+ * @param defaultValue the value to return when there is no value
+ * @return the last value, or {@code defaultValue} if there is none
+ */
String fetch(Object key, String defaultValue);
+ /**
+ * Returns the value of an option at the given position, with variables resolved.
+ *
+ * @param key the option name
+ * @param index the position of the value
+ * @return the resolved value, or {@code null} if the option is missing
+ * @throws IndexOutOfBoundsException if the option exists and the index is out of range
+ * @throws CircularReferenceException if the variables are nested deeper than {@link
+ * Config#getMaxResolveDepth()}
+ */
String fetch(Object key, int index);
+ /**
+ * Returns the last value of an option, with variables resolved, converted to a type.
+ *
+ * @param Each readable property (except {@code class}) whose value is not {@code null} is written to
+ * the option of the same name, as {@link String#valueOf(Object)} of the value. A single value
+ * replaces the last value of the option. The elements of an array property are added after the
+ * existing values.
+ *
+ * @param bean the bean to read
+ * @throws IllegalArgumentException if a property cannot be read
+ */
void from(Object bean);
+ /**
+ * Copies the properties of a bean into this map, with a prefix on the option names.
+ *
+ * It works like {@link #from(Object)}, except that the option for a property is named by the
+ * prefix followed by the property name.
+ *
+ * @param bean the bean to read
+ * @param keyPrefix the text put in front of every property name
+ * @throws IllegalArgumentException if a property cannot be read
+ */
void from(Object bean, String keyPrefix);
+ /**
+ * Returns the last value of an option, or a default if the option is missing.
+ *
+ * The value is returned as stored, without variable substitution.
+ *
+ * @param key the option name
+ * @param defaultValue the value to return when there is no value
+ * @return the last value, or {@code defaultValue} if there is none
+ */
String get(Object key, String defaultValue);
+ /**
+ * Returns the last value of an option, converted to a type.
+ *
+ * The value is converted as stored, without variable substitution.
+ *
+ * @param The value is converted as stored, without variable substitution.
+ *
+ * @param The value is converted as stored, without variable substitution.
+ *
+ * @param If the option has no value yet, the value is added.
+ *
+ * @param key the option name
+ * @param value the value; it is stored as {@link String#valueOf(Object)}, or as {@code null} if
+ * it is {@code null}
+ * @return the replaced value, or {@code null} if there was none
+ */
String put(String key, Object value);
+ /**
+ * Replaces the value of an option at the given position.
+ *
+ * @param key the option name; it must be in the map
+ * @param value the value; it is stored as {@link String#valueOf(Object)}, or as {@code null} if
+ * it is {@code null}
+ * @param index the position of the value to replace
+ * @return the replaced value
+ * @throws IndexOutOfBoundsException if the index is out of range
+ * @throws NullPointerException if the option is not in the map (this is what {@link
+ * BasicOptionMap} does)
+ */
String put(String key, Object value, int index);
+ /**
+ * Replaces all the values of an option with the elements of an array.
+ *
+ * The option is removed first, so its comment is removed too. Each element is stored as {@link
+ * String#valueOf(Object)}, or as {@code null} if it is {@code null}. If {@code value} is {@code
+ * null}, the option is only removed.
+ *
+ * @param key the option name
+ * @param value an array, of an object or a primitive type, or {@code null}
+ * @throws IllegalArgumentException if {@code value} is not an array
+ */
void putAll(String key, Object value);
+ /**
+ * Copies the values of this map into the properties of a bean.
+ *
+ * For each writable property of the bean that has an option of the same name, the option value
+ * is read as {@link #fetch(Object)} does (variables are resolved), converted to the property type
+ * and set. An array property gets all the values. A property without an option is not touched.
+ *
+ * @param bean the bean to change
+ * @throws IllegalArgumentException if a property cannot be set; the message names the property
+ */
void to(Object bean);
+ /**
+ * Copies the values of this map into the properties of a bean, with a prefix on the option names.
+ *
+ * It works like {@link #to(Object)}, except that the option for a property is named by the
+ * prefix followed by the property name.
+ *
+ * @param bean the bean to change
+ * @param keyPrefix the text put in front of every property name
+ * @throws IllegalArgumentException if a property cannot be set; the message names the property
+ */
void to(Object bean, String keyPrefix);
}
diff --git a/src/main/java/org/ini4j/Options.java b/src/main/java/org/ini4j/Options.java
index 9b349fa..0f2fde2 100644
--- a/src/main/java/org/ini4j/Options.java
+++ b/src/main/java/org/ini4j/Options.java
@@ -31,6 +31,35 @@
import org.ini4j.spi.OptionsHandler;
import org.ini4j.spi.OptionsParser;
+/**
+ * An {@link OptionMap} that can be loaded from and stored to a file of options without sections.
+ *
+ * The file has one option on each line, written as {@code name=value} or {@code name:value}. A
+ * line that starts with {@code !} or {@code #} is a comment. It looks like a Java properties file.
+ * Unlike a properties file, an option name can have several values, comments are kept, values can
+ * contain variables (see {@link OptionMap}), and the content can be read through your own
+ * interfaces.
+ *
+ * A new {@code Options} has its own copy of the global {@link Config}, with {@link
+ * Config#isEmptyOption()} turned on. The methods that read or write a stream use its file encoding.
+ * When a file or a URL is loaded, a byte order mark at the start of the input takes precedence over
+ * it.
+ *
+ * This reads an option and writes the file back:
+ *
+ * The thread safety of {@link BasicMultiMap} applies.
+ *
+ * @see Ini
+ * @since 0.4.1
+ */
@edu.umd.cs.findbugs.annotations.SuppressFBWarnings({"CT_CONSTRUCTOR_THROW", "EI_EXPOSE_REP"})
public class Options extends BasicOptionMap implements Persistable, Configurable {
private static final long serialVersionUID = -1119753444859181822L;
@@ -38,36 +67,80 @@ public class Options extends BasicOptionMap implements Persistable, Configurable
private Config _config;
private File _file;
+ /** Creates an empty {@code Options} with its own configuration. */
public Options() {
_config = Config.getGlobal().clone();
_config.setEmptyOption(true);
}
+ /**
+ * Creates an {@code Options} and loads it from a reader.
+ *
+ * @param input the reader to read
+ * @throws IOException if reading fails
+ * @throws InvalidFileFormatException if the content is not valid
+ */
public Options(Reader input) throws IOException, InvalidFileFormatException {
this();
load(input);
}
+ /**
+ * Creates an {@code Options} and loads it from a stream.
+ *
+ * @param input the stream to read
+ * @throws IOException if reading fails
+ * @throws InvalidFileFormatException if the content is not valid
+ */
public Options(InputStream input) throws IOException, InvalidFileFormatException {
this();
load(input);
}
+ /**
+ * Creates an {@code Options} and loads it from a URL.
+ *
+ * @param input the location to read
+ * @throws IOException if reading fails
+ * @throws InvalidFileFormatException if the content is not valid
+ */
public Options(URL input) throws IOException, InvalidFileFormatException {
this();
load(input);
}
+ /**
+ * Creates an {@code Options}, remembers the file and loads it.
+ *
+ * The file stays the associated file, so {@link #store()} writes back to it.
+ *
+ * @param input the file to read and later to write
+ * @throws IOException if reading fails
+ * @throws InvalidFileFormatException if the content is not valid
+ */
public Options(File input) throws IOException, InvalidFileFormatException {
this();
_file = input;
load();
}
+ /**
+ * Returns the header comment of the options.
+ *
+ * When a file is loaded with {@link Config#isHeaderComment()} and {@link Config#isComment()}
+ * on, the comment at the top of the file, before the first option, becomes the header comment.
+ *
+ * @return the comment, or {@code null} if there is none
+ */
public String getComment() {
return _comment;
}
+ /**
+ * Sets the header comment of the options.
+ *
+ * @param value the new comment, or {@code null} to have none
+ */
public void setComment(String value) {
_comment = value;
}
@@ -151,10 +224,28 @@ public void store(File output) throws IOException {
}
}
+ /**
+ * Creates the handler that builds this object while a file is parsed.
+ *
+ * A subclass can override it to change how the parsed events are turned into options.
+ *
+ * @return a new builder for this object
+ */
protected OptionsHandler newBuilder() {
return OptionsBuilder.newInstance(this);
}
+ /**
+ * Sends the content to a formatter.
+ *
+ * The handler gets {@link OptionsHandler#startOptions()}, the header comment, then for each
+ * option its comment and its values, and {@link OptionsHandler#endOptions()}. When {@link
+ * Config#isMultiOption()} is off, only the first value of each option is sent. A subclass can
+ * override this method to change what is stored.
+ *
+ * @param formatter the handler that receives the events
+ * @throws IOException if the handler fails
+ */
protected void store(OptionsHandler formatter) throws IOException {
formatter.startOptions();
storeComment(formatter, _comment);
diff --git a/src/main/java/org/ini4j/Persistable.java b/src/main/java/org/ini4j/Persistable.java
index 7258b4f..37d6c46 100644
--- a/src/main/java/org/ini4j/Persistable.java
+++ b/src/main/java/org/ini4j/Persistable.java
@@ -23,26 +23,132 @@
import java.io.Writer;
import java.net.URL;
+/**
+ * An object that can load its content from, and store it to, a file, a stream, a reader or a
+ * writer, or a URL.
+ *
+ * An object can have an associated file, which is used by {@link #load()} and {@link #store()}.
+ * The constructors of {@link Ini}, {@link Options} and {@link Reg} that take a {@link File} set it.
+ *
+ * Loading does not clear the object first. It adds what it reads to the existing content, and
+ * the {@link Config} flags such as {@link Config#isMultiSection()} and {@link
+ * Config#isMultiOption()} decide what happens to names that are already there. When loading has
+ * read the input to its end, it closes the input. If loading fails before that, the input is left
+ * open.
+ *
+ * Storing writes the content as the {@link Config} flags allow. For example, comments, empty
+ * sections, options without a value and, when {@link Config#isMultiOption()} is off, all but one
+ * value of an option can be left out (see that method for the value that is kept). The methods that
+ * take an {@link OutputStream} or a {@link Writer} flush it but do not close it. {@link
+ * #store(File)} creates the file or overwrites it, and closes it. The text is encoded with {@link
+ * Config#getFileEncoding()}. The writers used for storing are {@link java.io.PrintWriter}s, which
+ * do not throw an exception when a write fails. An {@link IOException} is mostly raised when a file
+ * cannot be opened.
+ *
+ * @see Configurable
+ * @since 0.5.0
+ */
public interface Persistable {
+ /**
+ * Returns the file used by {@link #load()} and {@link #store()}.
+ *
+ * @return the file, or {@code null} if none is set
+ */
File getFile();
+ /**
+ * Sets the file used by {@link #load()} and {@link #store()}.
+ *
+ * @param value the file, or {@code null} to have none
+ */
void setFile(File value);
+ /**
+ * Loads the content from the associated file.
+ *
+ * @throws java.io.FileNotFoundException if there is no associated file, or the file does not
+ * exist
+ * @throws IOException if reading fails
+ * @throws InvalidFileFormatException if the content is not valid
+ */
void load() throws IOException, InvalidFileFormatException;
+ /**
+ * Loads the content from a stream.
+ *
+ * The bytes are decoded with {@link Config#getFileEncoding()}.
+ *
+ * @param input the stream to read
+ * @throws IOException if reading fails
+ * @throws InvalidFileFormatException if the content is not valid
+ */
void load(InputStream input) throws IOException, InvalidFileFormatException;
+ /**
+ * Loads the content from a reader.
+ *
+ * @param input the reader to read
+ * @throws IOException if reading fails
+ * @throws InvalidFileFormatException if the content is not valid
+ */
void load(Reader input) throws IOException, InvalidFileFormatException;
+ /**
+ * Loads the content from a file.
+ *
+ * This does not change the associated file.
+ *
+ * @param input the file to read
+ * @throws IOException if the file cannot be read
+ * @throws InvalidFileFormatException if the content is not valid
+ */
void load(File input) throws IOException, InvalidFileFormatException;
+ /**
+ * Loads the content from a URL.
+ *
+ * @param input the location to read
+ * @throws IOException if reading fails
+ * @throws InvalidFileFormatException if the content is not valid
+ */
void load(URL input) throws IOException, InvalidFileFormatException;
+ /**
+ * Stores the content to the associated file.
+ *
+ * @throws java.io.FileNotFoundException if there is no associated file, or it cannot be opened
+ * @throws IOException if writing fails
+ */
void store() throws IOException;
+ /**
+ * Stores the content to a stream.
+ *
+ * The text is encoded with {@link Config#getFileEncoding()}. The stream is flushed, not
+ * closed.
+ *
+ * @param output the stream to write
+ * @throws IOException if writing fails
+ */
void store(OutputStream output) throws IOException;
+ /**
+ * Stores the content to a writer.
+ *
+ * The writer is flushed, not closed.
+ *
+ * @param output the writer to write
+ * @throws IOException if writing fails
+ */
void store(Writer output) throws IOException;
+ /**
+ * Stores the content to a file.
+ *
+ * This does not change the associated file.
+ *
+ * @param output the file to write; it is created or overwritten
+ * @throws IOException if the file cannot be opened or written
+ */
void store(File output) throws IOException;
}
diff --git a/src/main/java/org/ini4j/Profile.java b/src/main/java/org/ini4j/Profile.java
index b51ed3d..611593a 100644
--- a/src/main/java/org/ini4j/Profile.java
+++ b/src/main/java/org/ini4j/Profile.java
@@ -15,51 +15,297 @@
*/
package org.ini4j;
+/**
+ * A set of named sections, each holding options.
+ *
+ * A profile is a {@link MultiMap} from section names to {@link Section}s and a {@link
+ * CommentedMap}, so a name can have several sections and every section can have a comment. The
+ * profile itself can have a header comment. Besides the plain map access, it offers shortcuts that
+ * address an option by section name and option name, for example {@link #get(Object, Object)} and
+ * {@link #put(String, String, Object)}.
+ *
+ * Section names can form a tree. The name {@code dwarfs/happy} is the name of a child of the
+ * section {@code dwarfs}, and {@code /} is the path separator (see {@link #PATH_SEPARATOR} and
+ * {@link Config#getPathSeparator()}). The {@link Section} interface has methods to walk this tree.
+ *
+ * The example reads two options from a file, adds a section and writes the file back.
+ *
+ * When a file is loaded with {@link Config#isHeaderComment()} and {@link Config#isComment()}
+ * on, the comment at the top of the file, before the first section or option, becomes the header
+ * comment.
+ *
+ * @return the comment, or {@code null} if there is none
+ */
String getComment();
+ /**
+ * Sets the header comment of the profile.
+ *
+ * @param value the new comment, or {@code null} to have none
+ */
void setComment(String value);
+ /**
+ * Adds a new, empty section.
+ *
+ * A section is added even if one with this name exists already. In tree mode (see {@link
+ * Config#isTree()}), if the section name has a parent (for example {@code a/b} for {@code a/b/c})
+ * and the parent is missing, the parent is added first, as far up as needed.
+ *
+ * @param sectionName the name of the new section
+ * @return the new section
+ */
Section add(String sectionName);
+ /**
+ * Adds an option value to a section.
+ *
+ * The section is the last one with the given name; it is created if there is none. The value
+ * is added after the values the option has already.
+ *
+ * @param sectionName the section name
+ * @param optionName the option name
+ * @param value the value, stored as in {@link OptionMap#add(String, Object)}
+ */
void add(String sectionName, String optionName, Object value);
+ /**
+ * Returns a view of this profile as an object of the given interface.
+ *
+ * The returned object is a dynamic proxy backed by this profile. Each property of the
+ * interface stands for a section of the same name, and its value is a view of that section
+ * created as {@link OptionMap#as(Class)} does. A property of an array type stands for all the
+ * sections of that name. A getter returns the zero value of its type if there is no such section.
+ * A setter removes the sections of that name and adds new ones filled with {@link
+ * OptionMap#from(Object)}; a {@code null} value only removes them. The listener methods work as
+ * described in {@link OptionMap#as(Class)}.
+ *
+ * @param It works like {@link #as(Class)}, except that the section for a property is named by the
+ * prefix followed by the property name. In {@link BasicProfile}, the prefix is not applied when
+ * {@link Config#isPropertyFirstUpper()} is on.
+ *
+ * @param The section is the last one with the given name. Variables are written as described in
+ * {@link OptionMap}, with these additions:
+ *
+ * The section is the last one with the given name. Variables are not resolved.
+ *
+ * @param sectionName the section name
+ * @param optionName the option name
+ * @return the value, or {@code null} if the section or the option is missing
+ */
String get(Object sectionName, Object optionName);
+ /**
+ * Returns the last value of an option, as stored, converted to a type.
+ *
+ * @param The section is the last one with the given name; it is created if there is none. The value
+ * replaces the last value of the option.
+ *
+ * @param sectionName the section name
+ * @param optionName the option name
+ * @param value the value, stored as in {@link OptionMap#put(String, Object)}
+ * @return the replaced value, or {@code null} if there was none
+ */
String put(String sectionName, String optionName, Object value);
+ /**
+ * Removes the sections that have the name of the given section.
+ *
+ * The removal is by name: every section with that name is removed, not only the given object.
+ *
+ * @param section the section whose name is removed
+ * @return the first section that was removed, or {@code null} if there was none
+ */
Section remove(Profile.Section section);
+ /**
+ * Removes all the values of an option from a section.
+ *
+ * The section is the last one with the given name.
+ *
+ * @param sectionName the section name
+ * @param optionName the option name
+ * @return the first value that was removed, or {@code null} if there was none or the section is
+ * missing
+ */
String removeOption(Object sectionName, Object optionName);
+ /**
+ * A section of a {@link Profile}: a named {@link OptionMap}.
+ *
+ * A section knows the profile it belongs to. Its name can contain path separators, which makes
+ * it a node in the section tree of the profile. The tree methods build the names of the related
+ * sections from this name and look them up in the profile, so they only find sections that exist.
+ * Variables in the values of a section are resolved by the profile, so they can refer to other
+ * sections, see {@link Profile#fetch(Object, Object)}.
+ *
+ * @since 0.5.0
+ */
interface Section extends OptionMap {
+ /**
+ * Returns a child section.
+ *
+ * @param key the name of the child relative to this section, for example {@code b} for the
+ * child {@code a/b} of {@code a}
+ * @return the child, or {@code null} if there is none; if several sections have the name, the
+ * last one
+ */
Section getChild(String key);
+ /**
+ * Returns the full name of the section.
+ *
+ * @return the name, including the path of its ancestors
+ */
String getName();
+ /**
+ * Returns the parent section.
+ *
+ * @return the section whose name is this name up to the last path separator, or {@code null} if
+ * the name has no path separator or there is no such section
+ */
Section getParent();
+ /**
+ * Returns the last part of the section name.
+ *
+ * @return the name after the last path separator, or the whole name if there is none
+ */
String getSimpleName();
+ /**
+ * Adds a new child section.
+ *
+ * It works like {@link Profile#add(String)} with the name of this section, a path separator
+ * and the key.
+ *
+ * @param key the name of the child relative to this section
+ * @return the new section
+ */
Section addChild(String key);
+ /**
+ * Returns the names of the child sections.
+ *
+ * Only direct children are listed, and each name is relative to this section. They come in
+ * the order of the profile.
+ *
+ * @return a new array of names; it is empty if there are no children
+ */
String[] childrenNames();
+ /**
+ * Finds a descendant section by its path below this section.
+ *
+ * The parts are joined with the path separator, so {@code lookup("b", "c")} on the section
+ * {@code a} finds {@code a/b/c}.
+ *
+ * @param path the names of the sections on the way down from this section
+ * @return the section, or {@code null} if there is none
+ */
Section lookup(String... path);
+ /**
+ * Removes a child section.
+ *
+ * The sections with that name are removed. Their own children stay.
+ *
+ * @param key the name of the child relative to this section
+ */
void removeChild(String key);
}
}
diff --git a/src/main/java/org/ini4j/Reg.java b/src/main/java/org/ini4j/Reg.java
index d4e75f0..d83a893 100644
--- a/src/main/java/org/ini4j/Reg.java
+++ b/src/main/java/org/ini4j/Reg.java
@@ -32,11 +32,45 @@
import org.ini4j.spi.IniParser;
import org.ini4j.spi.RegBuilder;
+/**
+ * A {@link Registry} that reads and writes Windows registry export files, and on Windows can
+ * exchange keys with the real registry.
+ *
+ * A {@code .reg} file starts with a version header (see {@link Registry#VERSION}), followed by
+ * keys written as sections, whose options are the registry values with their types. The model is
+ * described in {@link Registry}. The load methods require the first line to be the version header,
+ * and they skip the line after it.
+ *
+ * A new {@code Reg} has its own copy of the global {@link Config} with the settings of this
+ * format: escaping is off, the global section is off, an option without a value, an option with
+ * several values and a section without options are allowed, operators are written without spaces,
+ * the path separator is a backslash ({@link Registry#KEY_SEPARATOR}), the file encoding is {@link
+ * Registry#FILE_ENCODING} and the line separator is {@link Registry#LINE_SEPARATOR}.
+ *
+ * Only the methods {@link #read(String)}, {@link #write()} and the constructor that takes a key
+ * name work with the real registry. They run the Windows {@code reg} command, so they are for
+ * Windows only (see {@link #isWindows()}) and throw an {@link UnsupportedOperationException}
+ * elsewhere. All the other methods work on every system.
+ *
+ * The thread safety of {@link BasicMultiMap} applies.
+ *
+ * @see Registry
+ * @since 0.5.0
+ */
@edu.umd.cs.findbugs.annotations.SuppressFBWarnings({"CT_CONSTRUCTOR_THROW", "EI_EXPOSE_REP"})
public class Reg extends BasicRegistry implements Persistable, Configurable {
private static final long serialVersionUID = -1485602876922985912L;
+
+ /**
+ * The file name suffix of the temporary files used by {@link #read(String)} and {@link #write()}.
+ */
protected static final String DEFAULT_SUFFIX = ".reg";
+
+ /**
+ * The file name prefix of the temporary files used by {@link #read(String)} and {@link #write()}.
+ */
protected static final String TMP_PREFIX = "reg-";
+
private static final int STDERR_BUFF_SIZE = 8192;
private static final String PROP_OS_NAME = "os.name";
private static final boolean WINDOWS =
@@ -46,6 +80,10 @@ public class Reg extends BasicRegistry implements Persistable, Configurable {
private Config _config;
private File _file;
+ /**
+ * Creates an empty registry with its own configuration, which has the settings of the registry
+ * file format.
+ */
public Reg() {
Config cfg = Config.getGlobal().clone();
@@ -61,32 +99,81 @@ public Reg() {
_config = cfg;
}
+ /**
+ * Creates a registry and reads a key of the real registry into it.
+ *
+ * It is the same as {@link #Reg()} followed by {@link #read(String)}.
+ *
+ * @param registryKey the path of the key, for example {@code HKEY_CURRENT_USER\Software\ini4j}
+ * @throws IOException if the {@code reg} command fails
+ * @throws UnsupportedOperationException if this is not Windows
+ */
public Reg(String registryKey) throws IOException {
this();
read(registryKey);
}
+ /**
+ * Creates a registry, remembers the file and loads it.
+ *
+ * @param input the file to read and later to write
+ * @throws IOException if reading fails
+ * @throws InvalidFileFormatException if the version header is missing or unsupported, or the
+ * content is not valid
+ */
public Reg(File input) throws IOException, InvalidFileFormatException {
this();
_file = input;
load();
}
+ /**
+ * Creates a registry and loads it from a URL.
+ *
+ * @param input the location to read
+ * @throws IOException if reading fails
+ * @throws InvalidFileFormatException if the version header is missing or unsupported, or the
+ * content is not valid
+ */
public Reg(URL input) throws IOException, InvalidFileFormatException {
this();
load(input);
}
+ /**
+ * Creates a registry and loads it from a stream.
+ *
+ * @param input the stream to read
+ * @throws IOException if reading fails
+ * @throws InvalidFileFormatException if the version header is missing or unsupported, or the
+ * content is not valid
+ */
public Reg(InputStream input) throws IOException, InvalidFileFormatException {
this();
load(input);
}
+ /**
+ * Creates a registry and loads it from a reader.
+ *
+ * @param input the reader to read
+ * @throws IOException if reading fails
+ * @throws InvalidFileFormatException if the version header is missing or unsupported, or the
+ * content is not valid
+ */
public Reg(Reader input) throws IOException, InvalidFileFormatException {
this();
load(input);
}
+ /**
+ * Tells whether the program runs on Windows.
+ *
+ * The answer is taken from the system property {@code os.name}, which must start with {@code
+ * Windows}. It is read once, when this class is loaded.
+ *
+ * @return {@code true} on Windows
+ */
public static boolean isWindows() {
return WINDOWS;
}
@@ -161,6 +248,18 @@ public void load(File input) throws IOException, InvalidFileFormatException {
load(input.toURI().toURL());
}
+ /**
+ * Reads a key of the real registry into this object.
+ *
+ * The key is exported with {@code reg export} to a temporary file, and that file is loaded.
+ * The temporary file is deleted afterwards. As with every load, the content is added to what the
+ * object holds already.
+ *
+ * @param registryKey the path of the key, for example {@code HKEY_CURRENT_USER\Software\ini4j}
+ * @throws IOException if the {@code reg} command fails (the message is the text it wrote to its
+ * error output) or the exported file cannot be loaded
+ * @throws UnsupportedOperationException if this is not Windows
+ */
@edu.umd.cs.findbugs.annotations.SuppressFBWarnings("RV_RETURN_VALUE_IGNORED_BAD_PRACTICE")
public void read(String registryKey) throws IOException {
File tmp = createTempFile();
@@ -206,6 +305,16 @@ public void store(File output) throws IOException {
}
}
+ /**
+ * Writes this object to the real registry.
+ *
+ * The content is stored to a temporary file, which is imported with {@code reg import}, and
+ * then deleted. This changes the registry of the machine.
+ *
+ * @throws IOException if the {@code reg} command fails (the message is the text it wrote to its
+ * error output)
+ * @throws UnsupportedOperationException if this is not Windows
+ */
@edu.umd.cs.findbugs.annotations.SuppressFBWarnings("RV_RETURN_VALUE_IGNORED_BAD_PRACTICE")
public void write() throws IOException {
File tmp = createTempFile();
@@ -218,6 +327,13 @@ public void write() throws IOException {
}
}
+ /**
+ * Creates the handler that builds this object while a file is parsed.
+ *
+ * A subclass can override it to change how the parsed events are turned into keys and values.
+ *
+ * @return a new builder for this object
+ */
protected IniHandler newBuilder() {
return RegBuilder.newInstance(this);
}
diff --git a/src/main/java/org/ini4j/Registry.java b/src/main/java/org/ini4j/Registry.java
index 515aac7..e9552f4 100644
--- a/src/main/java/org/ini4j/Registry.java
+++ b/src/main/java/org/ini4j/Registry.java
@@ -19,28 +19,103 @@
import java.util.HashMap;
import java.util.Map;
+/**
+ * A {@link Profile} that models a Windows registry as it appears in a {@code .reg} export file.
+ *
+ * The sections are registry {@linkplain Key keys}. The name of a key is its full path, written
+ * with {@link #KEY_SEPARATOR} between the parts and starting with a {@linkplain Hive hive}, for
+ * example {@code HKEY_CURRENT_USER\Software\ini4j}. The options of a key are its values; the option
+ * named {@link Key#DEFAULT_NAME} is the default value of the key. Each value also has a {@linkplain
+ * Type type}.
+ *
+ * The constants of this interface describe the {@code .reg} file format: a version header line
+ * followed by the keys, in UTF-16 little endian text with {@code CR LF} line ends. The class that
+ * reads, writes and, on Windows, exchanges data with the real registry is {@link Reg}.
+ *
+ * @see Reg
+ * @see BasicRegistry
+ * @since 0.5.0
+ */
public interface Registry extends Profile {
+ /**
+ * The root keys of the registry, called hives.
+ *
+ * Their names, as returned by {@link #toString()}, are the first part of a key path.
+ *
+ * @since 0.5.0
+ */
enum Hive {
+ /** The root key {@code HKEY_CLASSES_ROOT}. */
HKEY_CLASSES_ROOT,
+
+ /** The root key {@code HKEY_CURRENT_CONFIG}. */
HKEY_CURRENT_CONFIG,
+
+ /** The root key {@code HKEY_CURRENT_USER}. */
HKEY_CURRENT_USER,
+
+ /** The root key {@code HKEY_LOCAL_MACHINE}. */
HKEY_LOCAL_MACHINE,
+
+ /** The root key {@code HKEY_USERS}. */
HKEY_USERS;
}
// TODO handle delete operations with special Type
+ /**
+ * The type of a registry value.
+ *
+ * The text form of a type, returned by {@link #toString()}, is the prefix that a {@code .reg}
+ * file puts in front of the data of a value, for example {@code dword} in {@code dword:0000002a}.
+ * A string value has no prefix, so the text of {@link #REG_SZ} is empty. This differs from {@link
+ * #name()}.
+ *
+ * @since 0.5.0
+ */
enum Type {
+ /** A value with no defined type. The data text is kept as written in the file. */
REG_NONE("hex(0)"),
+
+ /** A string, written in double quotes. This is the type of a value that has no prefix. */
REG_SZ(""),
+
+ /**
+ * A string that can contain references to environment variables. The file holds the string as
+ * hexadecimal UTF-16 little endian bytes, and the value in the map is the decoded text.
+ */
REG_EXPAND_SZ("hex(2)"),
+
+ /** Binary data. The data text is kept as written in the file. */
REG_BINARY("hex"),
+
+ /**
+ * A 32-bit number. The file holds it as eight hexadecimal digits, and the value in the map is
+ * the decimal text.
+ */
REG_DWORD("dword"),
+
+ /** A 32-bit number in big endian order. The data text is kept as written in the file. */
REG_DWORD_BIG_ENDIAN("hex(5)"),
+
+ /** A symbolic link. The data text is kept as written in the file. */
REG_LINK("hex(6)"),
+
+ /**
+ * A list of strings. The file holds them as hexadecimal UTF-16 little endian bytes, and the map
+ * has one value for each string.
+ */
REG_MULTI_SZ("hex(7)"),
+
+ /** A resource list. The data text is kept as written in the file. */
REG_RESOURCE_LIST("hex(8)"),
+
+ /** A full resource descriptor. The data text is kept as written in the file. */
REG_FULL_RESOURCE_DESCRIPTOR("hex(9)"),
+
+ /** A resource requirements list. The data text is kept as written in the file. */
REG_RESOURCE_REQUIREMENTS_LIST("hex(a)"),
+
+ /** A 64-bit number. The data text is kept as written in the file. */
REG_QWORD("hex(b)");
private static final Map {@link Reg} writes it as the first line when storing, and requires it to be the first line
+ * when loading.
+ *
+ * @param value the header text
+ */
void setVersion(String value);
+ /**
+ * Returns the last key with the given path.
+ *
+ * @param key the key path
+ * @return the key, or {@code null} if there is none
+ */
@Override
Key get(Object key);
+ /**
+ * Returns the key with the given path at the given position.
+ *
+ * @param key the key path
+ * @param index the position of the key among the keys with the same path
+ * @return the key, or {@code null} if the path is not in the registry
+ * @throws IndexOutOfBoundsException if the path is in the registry and the index is out of range
+ */
@Override
Key get(Object key, int index);
+ /**
+ * Replaces the last key with the given path.
+ *
+ * @param key the key path
+ * @param value the new key
+ * @return the replaced key, or {@code null} if there was none
+ */
@Override
Key put(String key, Section value);
+ /**
+ * Replaces the key with the given path at the given position.
+ *
+ * The path must be in the registry already.
+ *
+ * @param key the key path
+ * @param value the new key
+ * @param index the position of the key to replace
+ * @return the replaced key
+ * @throws IndexOutOfBoundsException if the index is out of range
+ * @throws NullPointerException if the path is not in the registry (this is what {@link
+ * BasicRegistry} does)
+ */
@Override
Key put(String key, Section value, int index);
+ /**
+ * Removes all the keys with the given path.
+ *
+ * @param key the key path
+ * @return the first key that was removed, or {@code null} if there was none
+ */
@Override
Key remove(Object key);
+ /**
+ * Removes the key with the given path at the given position.
+ *
+ * @param key the key path
+ * @param index the position of the key to remove
+ * @return the removed key, or {@code null} if the path is not in the registry
+ * @throws IndexOutOfBoundsException if the path is in the registry and the index is out of range
+ */
@Override
Key remove(Object key, int index);
+ /**
+ * A registry key: a {@link Section} whose options are registry values.
+ *
+ * A key also remembers the {@linkplain Type type} of each value. The type applies to all the
+ * values of one name. The tree methods inherited from {@link Section} work on the key paths and
+ * return keys.
+ *
+ * @since 0.5.0
+ */
interface Key extends Section {
+ /** The name of the default value of a key. */
String DEFAULT_NAME = "@";
@Override
@@ -109,8 +289,21 @@ interface Key extends Section {
@Override
Key getParent();
+ /**
+ * Returns the type of a value.
+ *
+ * @param key the value name
+ * @return the type, or {@code null} if no type was set
+ */
Type getType(Object key);
+ /**
+ * Returns the type of a value, or a default.
+ *
+ * @param key the value name
+ * @param defaulType the type to return if none was set
+ * @return the type, or {@code defaulType} if none was set
+ */
Type getType(Object key, Type defaulType);
@Override
@@ -119,8 +312,24 @@ interface Key extends Section {
@Override
Key lookup(String... path);
+ /**
+ * Sets the type of a value.
+ *
+ * When storing, a value with no type is written as {@link Type#REG_SZ}. Loading sets a type
+ * only for the values that are not {@link Type#REG_SZ}.
+ *
+ * @param key the value name
+ * @param type the type
+ * @return the previous type, or {@code null} if none was set
+ */
Type putType(String key, Type type);
+ /**
+ * Removes the type of a value.
+ *
+ * @param key the value name
+ * @return the removed type, or {@code null} if none was set
+ */
Type removeType(Object key);
}
}
diff --git a/src/main/java/org/ini4j/Wini.java b/src/main/java/org/ini4j/Wini.java
index b876b0e..1e1e1b6 100644
--- a/src/main/java/org/ini4j/Wini.java
+++ b/src/main/java/org/ini4j/Wini.java
@@ -22,11 +22,39 @@
import java.net.URL;
import org.ini4j.spi.WinEscapeTool;
+/**
+ * An {@link Ini} set up for the files that Windows applications use.
+ *
+ * A new {@code Wini} has its own copy of the global {@link Config} with these differences:
+ *
+ * Since escaping is off, a backslash in a name or a value is read and written as it is. The
+ * methods {@link #escape(String)} and {@link #unescape(String)} are there for the cases where you
+ * want to handle the Windows forms of escapes yourself.
+ *
+ * @see Ini
+ * @since 0.5.0
+ */
@edu.umd.cs.findbugs.annotations.SuppressFBWarnings("CT_CONSTRUCTOR_THROW")
public class Wini extends Ini {
private static final long serialVersionUID = -2781377824232440728L;
+
+ /**
+ * The path separator of section names in a {@code Wini}: a backslash. It hides {@link
+ * Profile#PATH_SEPARATOR}.
+ */
public static final char PATH_SEPARATOR = '\\';
+ /** Creates an empty {@code Wini}. */
public Wini() {
Config cfg = Config.getGlobal().clone();
@@ -39,31 +67,82 @@ public Wini() {
setConfig(cfg);
}
+ /**
+ * Creates a {@code Wini}, remembers the file and loads it.
+ *
+ * @param input the file to read and later to write
+ * @throws IOException if reading fails
+ * @throws InvalidFileFormatException if the content is not valid
+ */
public Wini(File input) throws IOException, InvalidFileFormatException {
this();
setFile(input);
load();
}
+ /**
+ * Creates a {@code Wini} and loads it from a URL.
+ *
+ * @param input the location to read
+ * @throws IOException if reading fails
+ * @throws InvalidFileFormatException if the content is not valid
+ */
public Wini(URL input) throws IOException, InvalidFileFormatException {
this();
load(input);
}
+ /**
+ * Creates a {@code Wini} and loads it from a stream.
+ *
+ * @param input the stream to read
+ * @throws IOException if reading fails
+ * @throws InvalidFileFormatException if the content is not valid
+ */
public Wini(InputStream input) throws IOException, InvalidFileFormatException {
this();
load(input);
}
+ /**
+ * Creates a {@code Wini} and loads it from a reader.
+ *
+ * @param input the reader to read
+ * @throws IOException if reading fails
+ * @throws InvalidFileFormatException if the content is not valid
+ */
public Wini(Reader input) throws IOException, InvalidFileFormatException {
this();
load(input);
}
+ /**
+ * Escapes a text in the Windows style.
+ *
+ * A backslash, tab, line feed, form feed, backspace, carriage return, colon and equals sign
+ * are written as a backslash and a letter ({@code \\}, {@code \t}, {@code \n}, {@code \f}, {@code
+ * \b}, {@code \r}, {@code \:} and {@code \=}). Any other character outside the printable ASCII
+ * range is written as {@code \x} and two hexadecimal digits, which hold only the low byte of the
+ * character.
+ *
+ * @param value the text to escape
+ * @return the escaped text
+ */
public String escape(String value) {
return WinEscapeTool.getInstance().escape(value);
}
+ /**
+ * Reverses {@link #escape(String)}.
+ *
+ * Besides the forms that {@link #escape(String)} writes, it reads {@code \o} followed by three
+ * octal digits and {@code \x} followed by two hexadecimal digits as a character with that code. A
+ * backslash before any other character is dropped.
+ *
+ * @param value the text to unescape
+ * @return the unescaped text
+ * @throws IllegalArgumentException if a {@code \x} or {@code \o} sequence is malformed
+ */
public String unescape(String value) {
return WinEscapeTool.getInstance().unescape(value);
}
diff --git a/src/main/java/org/ini4j/package-info.java b/src/main/java/org/ini4j/package-info.java
new file mode 100644
index 0000000..09236d5
--- /dev/null
+++ b/src/main/java/org/ini4j/package-info.java
@@ -0,0 +1,72 @@
+/*
+ * Copyright 2005,2009 Ivan SZKIBA
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * The main API of ini4j: reading, changing and writing INI files, option files and Windows registry
+ * files.
+ *
+ * The file formats and their classes:
+ *
+ * {@link org.ini4j.ConfigParser} offers the API of the Python {@code ConfigParser} on top of
+ * {@code Ini}, and {@link org.ini4j.IniPreferences} and {@link org.ini4j.IniPreferencesFactory}
+ * serve the {@code java.util.prefs} API from an INI file. The behavior of parsing and writing is
+ * set with {@link org.ini4j.Config}. The parsers, the formatters and the events between them are in
+ * the package {@code org.ini4j.spi}.
+ *
+ * This example loads a file, reads a value, changes it and stores the file:
+ *
+ * These words have a fixed meaning in the documentation:
+ *
+ * This package contains [ini4j] API. This is a very small library, so
- no interface and implementation separation neccessary. This is why [ini4j]
- has only one package.
- The handler maps the methods of the proxy to properties by the first letters of the method
+ * name: {@code getX} and {@code isX} read the property {@code x}, {@code setX} writes it, and
+ * {@code hasX} tells whether it exists. The property name is the rest of the method name changed as
+ * {@link java.beans.Introspector#decapitalize(String)} does. The methods {@code
+ * addPropertyChangeListener}, {@code addVetoableChangeListener} and the two matching {@code remove}
+ * methods take the property name and a listener. Only the start of the name is checked, so a method
+ * such as {@code issue()} is a read of the property {@code sue}.
+ *
+ * A subclass tells how to read, write and test a property in the store. The text from the store
+ * is converted to the type of the property here. A read that fails with an exception gives the
+ * {@linkplain BeanTool#zero(Class) zero value} of the type, not an exception. A write first asks
+ * the vetoable listeners of the property, if there are some, then writes, then tells the property
+ * change listeners. The old value for the listeners is read only if there are listeners.
+ *
+ * The methods of {@link Object} are not handled. A call of {@code toString()} returns {@code
+ * null}, {@code equals} throws a {@link NullPointerException}, and {@code hashCode} throws a {@link
+ * ClassCastException} because its name starts with {@code has}.
+ *
+ * Thread safety. The methods that read or write a property, and the ones that
+ * change the listeners, are synchronized on the handler, so two threads do not run them at the same
+ * time. The store behind it is not protected.
+ *
+ * @see BeanTool
+ * @since 0.4.1
+ */
public abstract class AbstractBeanInvocationHandler implements InvocationHandler {
private static final String PROPERTY_CHANGE_LISTENER = "PropertyChangeListener";
private static final String VETOABLE_CHANGE_LISTENER = "VetoableChangeListener";
@@ -79,6 +107,15 @@ public String getValue() {
private Object _proxy;
private VetoableChangeSupport _vcSupport;
+ /**
+ * Handles a call of a method of the proxy, as described in the description of this class.
+ *
+ * @param proxy the proxy
+ * @param method the method that was called
+ * @param args the arguments of the call
+ * @return the value for a read or a {@code has} method, and {@code null} otherwise
+ * @throws PropertyVetoException if a vetoable listener rejects the new value of a write
+ */
@Override
public Object invoke(Object proxy, Method method, Object[] args) throws PropertyVetoException {
Object ret = null;
@@ -129,12 +166,41 @@ public Object invoke(Object proxy, Method method, Object[] args) throws Property
return ret;
}
+ /**
+ * Reads a property from the store.
+ *
+ * @param property the property name
+ * @param clazz the type of the property
+ * @return the value; text is converted to {@code clazz} by the caller, and for an array type the
+ * caller accepts an array of text. {@code null} means that there is no value
+ */
protected abstract Object getPropertySpi(String property, Class> clazz);
+ /**
+ * Writes a property to the store.
+ *
+ * @param property the property name
+ * @param value the new value
+ * @param clazz the type of the property
+ */
protected abstract void setPropertySpi(String property, Object value, Class> clazz);
+ /**
+ * Tells whether the store has a property.
+ *
+ * @param property the property name
+ * @return {@code true} if the property has a value
+ */
protected abstract boolean hasPropertySpi(String property);
+ /**
+ * Reads a property and converts it to a type.
+ *
+ * @param property the property name
+ * @param clazz the type of the property
+ * @return the value, or the zero value of the type if there is none or the read or the conversion
+ * fails
+ */
@edu.umd.cs.findbugs.annotations.SuppressFBWarnings("REC_CATCH_EXCEPTION")
protected synchronized Object getProperty(String property, Class> clazz) {
Object o;
@@ -160,6 +226,17 @@ protected synchronized Object getProperty(String property, Class> clazz) {
return o;
}
+ /**
+ * Writes a property and notifies the listeners.
+ *
+ * A value of a type other than {@link String} for a {@code String} property is stored as its
+ * text.
+ *
+ * @param property the property name
+ * @param value the new value
+ * @param clazz the type of the property
+ * @throws PropertyVetoException if a vetoable listener rejects the new value
+ */
protected synchronized void setProperty(String property, Object value, Class> clazz)
throws PropertyVetoException {
boolean pc = (_pcSupport != null) && _pcSupport.hasListeners(property);
@@ -184,10 +261,22 @@ protected synchronized void setProperty(String property, Object value, Class>
}
}
+ /**
+ * Returns the proxy that this handler serves.
+ *
+ * @return the proxy, or {@code null} if no method that the handler maps to a property or a
+ * listener has been called yet
+ */
protected synchronized Object getProxy() {
return _proxy;
}
+ /**
+ * Adds a listener for the changes of a property.
+ *
+ * @param property the property name
+ * @param listener the listener
+ */
protected synchronized void addPropertyChangeListener(
String property, PropertyChangeListener listener) {
if (_pcSupport == null) {
@@ -197,6 +286,12 @@ protected synchronized void addPropertyChangeListener(
_pcSupport.addPropertyChangeListener(property, listener);
}
+ /**
+ * Adds a listener that can veto the changes of a property.
+ *
+ * @param property the property name
+ * @param listener the listener
+ */
protected synchronized void addVetoableChangeListener(
String property, VetoableChangeListener listener) {
if (_vcSupport == null) {
@@ -206,6 +301,13 @@ protected synchronized void addVetoableChangeListener(
_vcSupport.addVetoableChangeListener(property, listener);
}
+ /**
+ * Tells the property change listeners about a change.
+ *
+ * @param property the property name
+ * @param oldValue the old value
+ * @param newValue the new value
+ */
protected synchronized void firePropertyChange(
String property, Object oldValue, Object newValue) {
if (_pcSupport != null) {
@@ -213,6 +315,14 @@ protected synchronized void firePropertyChange(
}
}
+ /**
+ * Asks the vetoable change listeners about a change.
+ *
+ * @param property the property name
+ * @param oldValue the old value
+ * @param newValue the new value
+ * @throws PropertyVetoException if a listener rejects the change
+ */
protected synchronized void fireVetoableChange(String property, Object oldValue, Object newValue)
throws PropertyVetoException {
if (_vcSupport != null) {
@@ -220,6 +330,12 @@ protected synchronized void fireVetoableChange(String property, Object oldValue,
}
}
+ /**
+ * Tells whether a property has a value.
+ *
+ * @param property the property name
+ * @return {@code true} if it has; {@code false} if it has not, or the test fails
+ */
protected synchronized boolean hasProperty(String property) {
boolean ret;
@@ -232,10 +348,24 @@ protected synchronized boolean hasProperty(String property) {
return ret;
}
+ /**
+ * Converts a text to a type with {@link BeanTool#parse(String, Class)}.
+ *
+ * @param value the text
+ * @param clazz the type
+ * @return the value
+ * @throws IllegalArgumentException if the text cannot be converted
+ */
protected Object parse(String value, Class> clazz) throws IllegalArgumentException {
return BeanTool.getInstance().parse(value, clazz);
}
+ /**
+ * Removes a listener for the changes of a property.
+ *
+ * @param property the property name
+ * @param listener the listener
+ */
protected synchronized void removePropertyChangeListener(
String property, PropertyChangeListener listener) {
if (_pcSupport != null) {
@@ -243,6 +373,12 @@ protected synchronized void removePropertyChangeListener(
}
}
+ /**
+ * Removes a listener that can veto the changes of a property.
+ *
+ * @param property the property name
+ * @param listener the listener
+ */
protected synchronized void removeVetoableChangeListener(
String property, VetoableChangeListener listener) {
if (_vcSupport != null) {
@@ -250,6 +386,12 @@ protected synchronized void removeVetoableChangeListener(
}
}
+ /**
+ * Returns the zero value of a type with {@link BeanTool#zero(Class)}.
+ *
+ * @param clazz the type
+ * @return the zero value
+ */
protected Object zero(Class> clazz) {
return BeanTool.getInstance().zero(clazz);
}
diff --git a/src/main/java/org/ini4j/spi/AbstractFormatter.java b/src/main/java/org/ini4j/spi/AbstractFormatter.java
index c4e75b5..9cc2f94 100644
--- a/src/main/java/org/ini4j/spi/AbstractFormatter.java
+++ b/src/main/java/org/ini4j/spi/AbstractFormatter.java
@@ -18,6 +18,14 @@
import java.io.PrintWriter;
import org.ini4j.Config;
+/**
+ * The common part of the formatters: it writes comments and options as text.
+ *
+ * The output goes to a {@link java.io.PrintWriter}, which hides write errors instead of throwing
+ * them. The text is written as the {@link org.ini4j.Config} says.
+ *
+ * @since 0.5.0
+ */
abstract class AbstractFormatter implements HandlerBase {
private static final char OPERATOR = '=';
private static final char COMMENT = '#';
@@ -26,6 +34,20 @@ abstract class AbstractFormatter implements HandlerBase {
private boolean _header = true;
private PrintWriter _output;
+ /**
+ * Writes a comment.
+ *
+ * The comment is written as lines that start with {@code #}, one for each line of the comment,
+ * where a line ends at the line separator of the configuration ({@link
+ * org.ini4j.Config#getLineSeparator()}). Nothing is written if {@link
+ * org.ini4j.Config#isComment()} is off, or if the comment is {@code null} or empty.
+ *
+ * The first call of this method, if it comes before any option or section, is for the header
+ * comment. A header comment is followed by an empty line, and it is written only if {@link
+ * org.ini4j.Config#isHeaderComment()} is on.
+ *
+ * @param comment the comment, or {@code null} for none
+ */
@Override
public void handleComment(String comment) {
if (getConfig().isComment()
@@ -46,6 +68,19 @@ public void handleComment(String comment) {
_header = false;
}
+ /**
+ * Writes an option.
+ *
+ * The option is written as {@code name=value} if {@link org.ini4j.Config#isStrictOperator()}
+ * is on, and as {@code name = value} otherwise. The name, and the value unless {@link
+ * org.ini4j.Config#isEscapeKeyOnly()} is on, are escaped if {@link org.ini4j.Config#isEscape()}
+ * is on. An option whose value is {@code null} is written with an empty value if {@link
+ * org.ini4j.Config#isEmptyOption()} is on, and it is left out otherwise. Every line ends with the
+ * line separator of the configuration.
+ *
+ * @param optionName the name of the option
+ * @param optionValue the value, or {@code null} for an option without a value
+ */
@Override
public void handleOption(String optionName, String optionValue) {
if (getConfig().isStrictOperator()) {
@@ -77,18 +112,39 @@ public void handleOption(String optionName, String optionValue) {
setHeader(false);
}
+ /**
+ * Returns the configuration.
+ *
+ * @return the configuration in use; it is {@link org.ini4j.Config#getGlobal()} until another one
+ * is set
+ */
protected Config getConfig() {
return _config;
}
+ /**
+ * Sets the configuration.
+ *
+ * @param value the configuration to use from now on
+ */
protected void setConfig(Config value) {
_config = value;
}
+ /**
+ * Returns the output.
+ *
+ * @return the writer that receives the text
+ */
protected PrintWriter getOutput() {
return _output;
}
+ /**
+ * Sets the output.
+ *
+ * @param value the writer that receives the text; it is flushed at the end but never closed
+ */
protected void setOutput(PrintWriter value) {
_output = value;
}
diff --git a/src/main/java/org/ini4j/spi/AbstractParser.java b/src/main/java/org/ini4j/spi/AbstractParser.java
index 9074327..84d2c13 100644
--- a/src/main/java/org/ini4j/spi/AbstractParser.java
+++ b/src/main/java/org/ini4j/spi/AbstractParser.java
@@ -23,24 +23,59 @@
import org.ini4j.Config;
import org.ini4j.InvalidFileFormatException;
+/**
+ * The common part of the parsers: it holds the configuration and parses the lines with options.
+ *
+ * A subclass tells the characters that begin a comment line and the characters that separate an
+ * option name from its value. The parsing of an option line follows the {@link org.ini4j.Config}
+ * flags such as {@link org.ini4j.Config#isEscape()}, {@link org.ini4j.Config#isEmptyOption()} and
+ * {@link org.ini4j.Config#isLowerCaseOption()}.
+ *
+ * @since 0.5.0
+ */
abstract class AbstractParser {
private final String _comments;
private Config _config = Config.getGlobal();
private final String _operators;
+ /**
+ * Creates a parser.
+ *
+ * @param operators the characters that separate the name of an option from its value; the first
+ * one in the line that is not escaped with a backslash counts
+ * @param comments the characters that begin a comment line
+ */
protected AbstractParser(String operators, String comments) {
_operators = operators;
_comments = comments;
}
+ /**
+ * Returns the configuration.
+ *
+ * @return the configuration in use; it is {@link org.ini4j.Config#getGlobal()} until another one
+ * is set
+ */
protected Config getConfig() {
return _config;
}
+ /**
+ * Sets the configuration.
+ *
+ * @param value the configuration to use from now on
+ */
protected void setConfig(Config value) {
_config = value;
}
+ /**
+ * Reports a line that cannot be parsed.
+ *
+ * @param line the text of the line
+ * @param lineNumber the number of the line in the input
+ * @throws InvalidFileFormatException always; the message contains the line number and the line
+ */
protected void parseError(String line, int lineNumber) throws InvalidFileFormatException {
throw new InvalidFileFormatException("parse error (at line: " + lineNumber + "): " + line);
}
@@ -57,6 +92,21 @@ IniSource newIniSource(URL input, HandlerBase handler) throws IOException {
return new IniSource(input, handler, _comments, getConfig());
}
+ /**
+ * Parses a line with an option and sends it to the handler.
+ *
+ * The name is the text before the first operator that is not preceded by a backslash. When
+ * there is an operator, the name and the value are unescaped according to the configuration and
+ * trimmed. A line without an operator is an option without a value if {@link
+ * org.ini4j.Config#isEmptyOption()} is on, with the whole line as its name, and an error
+ * otherwise. An empty name is an error. With {@link org.ini4j.Config#isLowerCaseOption()} the
+ * name is converted to lower case.
+ *
+ * @param line the trimmed line
+ * @param handler the receiver of the option
+ * @param lineNumber the number of the line, for error messages
+ * @throws InvalidFileFormatException if the line is not a valid option
+ */
void parseOptionLine(String line, HandlerBase handler, int lineNumber)
throws InvalidFileFormatException {
int idx = indexOfOperator(line);
diff --git a/src/main/java/org/ini4j/spi/AbstractProfileBuilder.java b/src/main/java/org/ini4j/spi/AbstractProfileBuilder.java
index 025ecb1..285d8b4 100644
--- a/src/main/java/org/ini4j/spi/AbstractProfileBuilder.java
+++ b/src/main/java/org/ini4j/spi/AbstractProfileBuilder.java
@@ -20,25 +20,44 @@
import org.ini4j.Ini;
import org.ini4j.Profile;
+/**
+ * The common part of the builders that fill a {@link org.ini4j.Profile} from the events of a
+ * parser.
+ *
+ * The rules are described in {@link IniBuilder}.
+ *
+ * @since 0.5.0
+ */
abstract class AbstractProfileBuilder implements IniHandler {
private Profile.Section _currentSection;
private boolean _header;
private String _lastComment;
+ /**
+ * Ends the file. A comment that is the only content of the file becomes the comment of the
+ * profile, if {@link org.ini4j.Config#isComment()} and {@link org.ini4j.Config#isHeaderComment()}
+ * are on. The rules are described in {@link IniBuilder}.
+ */
@Override
public void endIni() {
- // comment only .ini files....
+ // a file that has nothing but a comment
if ((_lastComment != null) && _header) {
setHeaderComment();
}
}
+ /** Ends the current section. */
@Override
public void endSection() {
_currentSection = null;
}
+ /**
+ * Receives a comment.
+ *
+ * @param comment the text of the comment
+ */
@Override
public void handleComment(String comment) {
if ((_lastComment != null) && _header) {
@@ -49,6 +68,16 @@ public void handleComment(String comment) {
_lastComment = comment;
}
+ /**
+ * Adds an option to the current section.
+ *
+ * The value is added or replaces the last value as {@link org.ini4j.Config#isMultiOption()}
+ * says. A held comment becomes the comment of the option.
+ *
+ * @param name the name of the option
+ * @param value the value of the option, or {@code null}
+ * @throws NullPointerException if there is no current section
+ */
@Override
public void handleOption(String name, String value) {
_header = false;
@@ -64,6 +93,7 @@ public void handleOption(String name, String value) {
}
}
+ /** Starts the file. */
@Override
public void startIni() {
if (getConfig().isHeaderComment()) {
@@ -71,6 +101,15 @@ public void startIni() {
}
}
+ /**
+ * Starts a section.
+ *
+ * The section is added to the profile, or an existing one is reused as {@link
+ * org.ini4j.Config#isMultiSection()} says. A held comment becomes the comment of the section, or
+ * of the profile if no section or option came before it and header comments are on.
+ *
+ * @param sectionName the name of the section
+ */
@Override
public void startSection(String sectionName) {
if (getConfig().isMultiSection()) {
diff --git a/src/main/java/org/ini4j/spi/BeanAccess.java b/src/main/java/org/ini4j/spi/BeanAccess.java
index 23781a0..a998250 100644
--- a/src/main/java/org/ini4j/spi/BeanAccess.java
+++ b/src/main/java/org/ini4j/spi/BeanAccess.java
@@ -15,18 +15,77 @@
*/
package org.ini4j.spi;
+/**
+ * A view of a store of named, multi-valued properties, as a bean needs it.
+ *
+ * {@link BeanTool} uses it to copy values between a bean and a store such as an {@link
+ * org.ini4j.OptionMap}. The names are the names of bean properties, and each can have several
+ * values, indexed from zero. {@link org.ini4j.OptionMap#as(Class)} and {@link
+ * org.ini4j.OptionMap#from(Object)} are built on it. In the implementation of {@link
+ * org.ini4j.BasicOptionMap}, the property name is turned into an option name with the prefix and
+ * the upper case rule, and reading resolves variables.
+ *
+ * @since 0.4.1
+ */
public interface BeanAccess {
+ /**
+ * Adds a value after the existing values of a property.
+ *
+ * @param propertyName the name of the property
+ * @param value the value
+ */
void propAdd(String propertyName, String value);
+ /**
+ * Removes all the values of a property.
+ *
+ * @param propertyName the name of the property
+ * @return a removed value; {@link org.ini4j.BasicOptionMap} returns the first one, or {@code
+ * null} if there was none
+ */
String propDel(String propertyName);
+ /**
+ * Returns the last value of a property.
+ *
+ * @param propertyName the name of the property
+ * @return the value, or {@code null} if there is none
+ */
String propGet(String propertyName);
+ /**
+ * Returns a value of a property.
+ *
+ * @param propertyName the name of the property
+ * @param index the position of the value
+ * @return the value, or {@code null} if the property has no value
+ */
String propGet(String propertyName, int index);
+ /**
+ * Returns the number of values of a property.
+ *
+ * @param propertyName the name of the property
+ * @return the number of values, {@code 0} if there is none
+ */
int propLength(String propertyName);
+ /**
+ * Replaces the last value of a property, or adds it if there is none.
+ *
+ * @param propertyName the name of the property
+ * @param value the new value
+ * @return the replaced value, or {@code null} if there was none
+ */
String propSet(String propertyName, String value);
+ /**
+ * Replaces a value of a property.
+ *
+ * @param propertyName the name of the property
+ * @param value the new value
+ * @param index the position of the value to replace
+ * @return the replaced value
+ */
String propSet(String propertyName, String value, int index);
}
diff --git a/src/main/java/org/ini4j/spi/BeanTool.java b/src/main/java/org/ini4j/spi/BeanTool.java
index 775cd82..0efc924 100644
--- a/src/main/java/org/ini4j/spi/BeanTool.java
+++ b/src/main/java/org/ini4j/spi/BeanTool.java
@@ -26,14 +26,46 @@
import java.net.URL;
import java.util.TimeZone;
+/**
+ * Converts text to Java values and connects beans with a store of properties.
+ *
+ * It does the work behind {@link org.ini4j.OptionMap#get(Object, Class)}, {@link
+ * org.ini4j.OptionMap#as(Class)}, {@link org.ini4j.OptionMap#from(Object)} and {@link
+ * org.ini4j.OptionMap#to(Object)}. Properties are found with {@link java.beans.Introspector}, so
+ * the property names are those of the Java Beans conventions.
+ *
+ * The instance is created once, when the class is first used, with the provider lookup described
+ * in {@link IniParser#newInstance()}, using the name {@code org.ini4j.spi.BeanTool}. A provider
+ * that cannot be created makes the class initialization fail. The class has no state, so it can be
+ * used from several threads.
+ *
+ * @see BeanAccess
+ * @since 0.4.1
+ */
public class BeanTool {
private static final String PARSE_METHOD = "valueOf";
private static final BeanTool INSTANCE = ServiceFinder.findService(BeanTool.class);
+ /**
+ * Returns the shared instance.
+ *
+ * @return the instance
+ */
public static final BeanTool getInstance() {
return INSTANCE;
}
+ /**
+ * Copies the values of a store into the properties of a bean.
+ *
+ * Each writable property of the bean for which the store has a value is set. An array property
+ * gets all the values, and any other property gets the last one, converted with {@link
+ * #parse(String, Class)}. Other properties are not touched.
+ *
+ * @param bean the bean to change
+ * @param props the store to read
+ * @throws IllegalArgumentException if a property cannot be set; the message names the property
+ */
public void inject(Object bean, BeanAccess props) {
for (PropertyDescriptor pd : getPropertyDescriptors(bean.getClass())) {
try {
@@ -63,6 +95,17 @@ public void inject(Object bean, BeanAccess props) {
}
}
+ /**
+ * Copies the properties of a bean into a store.
+ *
+ * Each readable property, except {@code class}, whose value is not {@code null} is written as
+ * the text of the value. The elements of an array property are added one by one after the
+ * existing values, and any other value replaces the last one.
+ *
+ * @param props the store to change
+ * @param bean the bean to read
+ * @throws IllegalArgumentException if a property cannot be read; the message names the property
+ */
public void inject(BeanAccess props, Object bean) {
for (PropertyDescriptor pd : getPropertyDescriptors(bean.getClass())) {
try {
@@ -93,6 +136,24 @@ public void inject(BeanAccess props, Object bean) {
}
}
+ /**
+ * Converts a text to a value of a type.
+ *
+ * A {@code null} text gives the {@linkplain #zero(Class) zero value} of the type. A primitive
+ * type is parsed with the {@code valueOf} method of its wrapper, so any text other than {@code
+ * true} (in any letter case) is {@code false} for a {@code boolean}. {@link String} is returned
+ * as it is, and {@link Character} is the first character. {@link java.io.File}, {@link
+ * java.net.URL}, {@link java.net.URI}, {@link Class} (by name) and {@link java.util.TimeZone} are
+ * created from the text. Any other type must have a static {@code valueOf(String)} method.
+ *
+ * @param The object is a dynamic proxy that is created with the context class loader of the calling
+ * thread. The rules for the methods are described in {@link org.ini4j.OptionMap#as(Class)}.
+ *
+ * @param A subclass can override it to support more types.
+ *
+ * @param value the text
+ * @param clazz the type
+ * @return the value
+ * @throws IllegalArgumentException if the text cannot be converted; the cause tells why
+ */
protected Object parseSpecialValue(String value, Class> clazz) throws IllegalArgumentException {
Object o;
diff --git a/src/main/java/org/ini4j/spi/EscapeTool.java b/src/main/java/org/ini4j/spi/EscapeTool.java
index 10b6943..fda9681 100644
--- a/src/main/java/org/ini4j/spi/EscapeTool.java
+++ b/src/main/java/org/ini4j/spi/EscapeTool.java
@@ -15,6 +15,26 @@
*/
package org.ini4j.spi;
+/**
+ * Converts text to and from the backslash-escaped form of INI and options files.
+ *
+ * This is the escaping that is used when {@link org.ini4j.Config#isEscape()} is on. The
+ * characters backslash, tab, line feed, form feed, backspace, carriage return, colon and equals
+ * sign are written as a backslash and a letter or sign ({@code \\}, {@code \t}, {@code \n}, {@code
+ * \f}, {@code \b}, {@code \r}, {@code \:} and {@code \=}). Every other character outside the
+ * printable ASCII range ({@code U+0020} to {@code U+007E}) is written as a backslash, the letter
+ * {@code u} and four lower case hexadecimal digits. {@link #unescape(String)} reverses {@link
+ * #escape(String)} for any text. {@link WinEscapeTool} and {@link RegEscapeTool} have their own
+ * forms.
+ *
+ * The instance is created once, when the class is first used, with the provider lookup described
+ * in {@link IniParser#newInstance()}, using the name {@code org.ini4j.spi.EscapeTool}. A provider
+ * that cannot be created makes the class initialization fail.
+ *
+ * The class has no state, so it can be used from several threads.
+ *
+ * @since 0.4.1
+ */
public class EscapeTool {
private static final String ESCAPE_LETTERS = "\\tnfbr:=";
private static final String ESCAPEABLE_CHARS = "\\\t\n\f\b\r:=";
@@ -31,10 +51,21 @@ public class EscapeTool {
private static final int UNICODE_HEX_DIGITS = 4;
static final char DOUBLE_QUOTE = '"';
+ /**
+ * Returns the shared instance.
+ *
+ * @return the instance
+ */
public static EscapeTool getInstance() {
return INSTANCE;
}
+ /**
+ * Escapes a text.
+ *
+ * @param line the text to escape
+ * @return the escaped text
+ */
public String escape(String line) {
int len = line.length();
StringBuilder buffer = new StringBuilder(len * 2);
@@ -58,6 +89,15 @@ public String escape(String line) {
return buffer.toString();
}
+ /**
+ * Puts a text in double quotes.
+ *
+ * A backslash and a double quote inside the text get a backslash in front of them.
+ *
+ * @param value the text to quote
+ * @return the quoted text; {@code null} and an empty text are returned as they are, without
+ * quotes
+ */
public String quote(String value) {
String ret = value;
@@ -82,6 +122,19 @@ public String quote(String value) {
return ret;
}
+ /**
+ * Unescapes a text.
+ *
+ * A backslash followed by a letter or sign of the table in the description of this class gives
+ * the character. A backslash followed by {@code u} and four hexadecimal digits gives the
+ * character with that code. A backslash before any other character is dropped and the character
+ * stays.
+ *
+ * @param line the escaped text
+ * @return the unescaped text
+ * @throws IllegalArgumentException if an escape with {@code u} is malformed
+ * @throws StringIndexOutOfBoundsException if the text ends with a single backslash
+ */
public String unescape(String line) {
int n = line.length();
StringBuilder buffer = new StringBuilder(n);
@@ -113,6 +166,17 @@ public String unescape(String line) {
return buffer.toString();
}
+ /**
+ * Removes the quotes from a quoted text.
+ *
+ * The first and the last character are removed, whatever they are. The text is expected to
+ * have the form that {@link #quote(String)} writes, where a backslash before a backslash or a
+ * double quote is removed. Other uses of the backslash are not handled consistently: a backslash
+ * before any other character is dropped, and the next backslash after it is then kept.
+ *
+ * @param value the quoted text
+ * @return the text without the quotes
+ */
public String unquote(String value) {
StringBuilder buff = new StringBuilder();
boolean escape = false;
@@ -136,6 +200,14 @@ public String unquote(String value) {
return buff.toString();
}
+ /**
+ * Writes a character that has no short form as a {@code u} escape.
+ *
+ * A subclass overrides it to use another form.
+ *
+ * @param buff the buffer to write to
+ * @param c the character
+ */
void escapeBinary(StringBuilder buff, char c) {
buff.append("\\u");
buff.append(HEX[(c >>> HEX_DIGIT_1_OFFSET) & HEX_DIGIT_MASK]);
@@ -144,6 +216,19 @@ void escapeBinary(StringBuilder buff, char c) {
buff.append(HEX[c & HEX_DIGIT_MASK]);
}
+ /**
+ * Reads an escape that has more than one character after the backslash.
+ *
+ * A subclass overrides it to read other forms. When the type is not one it knows, it returns
+ * {@code index} and the caller treats the type as a plain escaped character.
+ *
+ * @param buff the buffer to write the character to
+ * @param escapeType the character after the backslash
+ * @param line the whole text
+ * @param index the position after {@code escapeType}
+ * @return the position after the escape, or {@code index} if this is not an escape of this kind
+ * @throws IllegalArgumentException if the escape is malformed
+ */
int unescapeBinary(StringBuilder buff, char escapeType, String line, int index) {
int ret = index;
diff --git a/src/main/java/org/ini4j/spi/HandlerBase.java b/src/main/java/org/ini4j/spi/HandlerBase.java
index 9ed0525..2c7e3e6 100644
--- a/src/main/java/org/ini4j/spi/HandlerBase.java
+++ b/src/main/java/org/ini4j/spi/HandlerBase.java
@@ -15,8 +15,28 @@
*/
package org.ini4j.spi;
+/**
+ * The events that the parsers and the formatters of both file formats share.
+ *
+ * A parser calls these methods while it reads a file, and a profile calls them while it is
+ * stored. The formats add their own start and end events: see {@link IniHandler} and {@link
+ * OptionsHandler}.
+ *
+ * @since 0.5.0
+ */
interface HandlerBase {
+ /**
+ * Receives a comment.
+ *
+ * @param comment the text of the comment, see the description of the subinterface
+ */
void handleComment(String comment);
+ /**
+ * Receives an option.
+ *
+ * @param optionName the name of the option
+ * @param optionValue the value of the option
+ */
void handleOption(String optionName, String optionValue);
}
diff --git a/src/main/java/org/ini4j/spi/IniBuilder.java b/src/main/java/org/ini4j/spi/IniBuilder.java
index 3246357..f72a59b 100644
--- a/src/main/java/org/ini4j/spi/IniBuilder.java
+++ b/src/main/java/org/ini4j/spi/IniBuilder.java
@@ -19,10 +19,43 @@
import org.ini4j.Ini;
import org.ini4j.Profile;
+/**
+ * Fills an {@link org.ini4j.Ini} from the events of an {@link IniParser}.
+ *
+ * The builder receives the events described in {@link IniHandler}. {@code startSection} adds a
+ * section to the {@code Ini}, or, if {@link org.ini4j.Config#isMultiSection()} is off and a section
+ * of that name exists, selects the existing one. {@code handleOption} adds the value to the current
+ * section, or replaces the last value if {@link org.ini4j.Config#isMultiOption()} is off. It must
+ * be called between {@code startSection} and {@code endSection}. The configuration is that of the
+ * {@code Ini}.
+ *
+ * Comments are kept only if {@link org.ini4j.Config#isComment()} is on. A comment is held until
+ * the next section or option, and becomes the comment of that section or option. If another comment
+ * arrives first, it replaces the held one, which is lost. The exception is the first comment of the
+ * file: with {@link org.ini4j.Config#isHeaderComment()} on, the first comment before any section or
+ * option is not lost but becomes the comment of the {@code Ini} itself, whether it is followed by a
+ * section, another comment, or the end of the file. A comment that is not followed by a section or
+ * an option, such as the comments at the end of the file, is lost.
+ *
+ * {@link RegBuilder} follows the same rules.
+ *
+ * @see IniParser
+ * @since 0.5.0
+ */
@edu.umd.cs.findbugs.annotations.SuppressFBWarnings("EI_EXPOSE_REP2")
public class IniBuilder extends AbstractProfileBuilder {
private Ini _ini;
+ /**
+ * Creates a builder of this class, or of the class that a provider names, for an {@code Ini}.
+ *
+ * The lookup is the same as in {@link IniParser#newInstance()}, with the name {@code
+ * org.ini4j.spi.IniBuilder}.
+ *
+ * @param ini the object to fill; it is used directly, not copied
+ * @return a new builder
+ * @throws IllegalArgumentException if the provider cannot be found or created
+ */
public static IniBuilder newInstance(Ini ini) {
IniBuilder instance = newInstance();
@@ -31,6 +64,11 @@ public static IniBuilder newInstance(Ini ini) {
return instance;
}
+ /**
+ * Sets the object to fill.
+ *
+ * @param value the object to fill; it is used directly, not copied
+ */
public void setIni(Ini value) {
_ini = value;
}
diff --git a/src/main/java/org/ini4j/spi/IniFormatter.java b/src/main/java/org/ini4j/spi/IniFormatter.java
index b1fca30..83bd17f 100644
--- a/src/main/java/org/ini4j/spi/IniFormatter.java
+++ b/src/main/java/org/ini4j/spi/IniFormatter.java
@@ -19,7 +19,33 @@
import java.io.Writer;
import org.ini4j.Config;
+/**
+ * Writes the events of an INI file as text.
+ *
+ * Each section is written as a header {@code [name]} followed by its options, and an empty line
+ * ends the section. If {@link org.ini4j.Config#isGlobalSection()} is on, the section that has the
+ * name {@link org.ini4j.Config#getGlobalSectionName()} has no header. Section names are escaped
+ * like option names. Comments and options are written as described in {@link
+ * #handleComment(String)} and {@link #handleOption(String, String)}. The writer is flushed at the
+ * end of the file and is never closed.
+ *
+ * @see IniHandler
+ * @see IniParser
+ * @since 0.4.1
+ */
public class IniFormatter extends AbstractFormatter implements IniHandler {
+ /**
+ * Creates a formatter of this class, or of the class that a provider names.
+ *
+ * The lookup is the same as in {@link IniParser#newInstance()}, with the name {@code
+ * org.ini4j.spi.IniFormatter}.
+ *
+ * @param out the writer for the text; it is used directly if it is a {@link java.io.PrintWriter},
+ * and wrapped in one otherwise
+ * @param config the configuration to use
+ * @return a new formatter
+ * @throws IllegalArgumentException if the provider cannot be found or created
+ */
public static IniFormatter newInstance(Writer out, Config config) {
IniFormatter instance = newInstance();
@@ -29,21 +55,29 @@ public static IniFormatter newInstance(Writer out, Config config) {
return instance;
}
+ /** Flushes the writer. */
@Override
public void endIni() {
getOutput().flush();
}
+ /** Writes an empty line. */
@Override
public void endSection() {
getOutput().print(getConfig().getLineSeparator());
}
+ /** Does nothing. */
@Override
public void startIni() {
assert true;
}
+ /**
+ * Writes the header of a section, unless it is the global section.
+ *
+ * @param sectionName the name of the section
+ */
@Override
public void startSection(String sectionName) {
setHeader(false);
diff --git a/src/main/java/org/ini4j/spi/IniHandler.java b/src/main/java/org/ini4j/spi/IniHandler.java
index 069552b..8327725 100755
--- a/src/main/java/org/ini4j/spi/IniHandler.java
+++ b/src/main/java/org/ini4j/spi/IniHandler.java
@@ -15,18 +15,81 @@
*/
package org.ini4j.spi;
+/**
+ * Receives the events of an INI file, in the order of the file.
+ *
+ * The same interface is used in both directions. A {@link IniParser} calls it while it reads a
+ * file, and an {@link org.ini4j.Ini} calls it while it is stored, so a handler is either a builder
+ * of the content ({@link IniBuilder}) or a writer of it ({@link IniFormatter}).
+ *
+ * The calls come in this order: {@link #startIni()}, then the sections, then {@link #endIni()}.
+ * A section is {@link #startSection(String)}, any number of {@link #handleOption(String, String)}
+ * calls for its options in file order, and {@link #endSection()}. Options never come outside a
+ * section. If {@link org.ini4j.Config#isGlobalSection()} is on, the parser starts a section for the
+ * options that come before the first header, and uses {@link
+ * org.ini4j.Config#getGlobalSectionName()} as its name.
+ *
+ * {@link #handleComment(String)} can come at any point between those calls. A comment is
+ * reported just before the section or the option it belongs to, so the comment above a section
+ * header arrives before the {@link #endSection()} of the section before it. A comment at the end of
+ * the file arrives before the last {@link #endSection()} (or before {@link #endIni()} if there is
+ * no section). The order is promised only for a successful parse. If the parser throws an
+ * exception, the closing calls may be missing.
+ *
+ * When a file is stored, the calls between {@link #startIni()} and {@link #endIni()} are the
+ * header comment, then for each section its comment, {@link #startSection(String)}, for each option
+ * its comment and one {@link #handleOption(String, String)} call for each value, and {@link
+ * #endSection()}. In this direction a comment can be {@code null}, which means there is none. The
+ * {@link org.ini4j.Config} flags can leave things out: a section without options is skipped when
+ * {@link org.ini4j.Config#isEmptySection()} is off, and when {@link
+ * org.ini4j.Config#isMultiOption()} is off only one value of each option is sent, the last one.
+ *
+ * @see IniParser
+ * @see IniFormatter
+ * @see IniBuilder
+ * @since 0.5.0
+ */
public interface IniHandler extends HandlerBase {
+ /** Ends the file. The parser calls it after the last section. */
void endIni();
+ /** Ends the current section. */
void endSection();
+ /**
+ * Receives a comment.
+ *
+ * When a file is parsed, it is the text of the comment lines without the leading comment
+ * character. Each line is trimmed before the comment character is removed, so spaces after the
+ * comment character stay in the text. The lines are joined with the line separator of the
+ * configuration, and the last separator is cut by one character only, so with a separator of two
+ * characters, such as {@code CR LF}, the text ends with one of them. A blank line ends a comment,
+ * so one run of comment lines is one comment. A comment line with nothing after the comment
+ * character gives an empty line in the text. When a file is stored, it is the comment of the
+ * header, a section or an option, and it is {@code null} if there is none.
+ *
+ * @param comment the text of the comment
+ */
@Override
void handleComment(String comment);
+ /**
+ * Receives an option of the current section.
+ *
+ * @param optionName the name of the option, never {@code null}
+ * @param optionValue the value of the option; it is {@code null} for an option without a value,
+ * which the parser allows only when {@link org.ini4j.Config#isEmptyOption()} is on
+ */
@Override
void handleOption(String optionName, String optionValue);
+ /** Starts the file. It is the first call. */
void startIni();
+ /**
+ * Starts a section.
+ *
+ * @param sectionName the name of the section
+ */
void startSection(String sectionName);
}
diff --git a/src/main/java/org/ini4j/spi/IniParser.java b/src/main/java/org/ini4j/spi/IniParser.java
index c30b102..4f7c9c9 100755
--- a/src/main/java/org/ini4j/spi/IniParser.java
+++ b/src/main/java/org/ini4j/spi/IniParser.java
@@ -23,20 +23,85 @@
import org.ini4j.Config;
import org.ini4j.InvalidFileFormatException;
+/**
+ * Parses INI files and sends the events to an {@link IniHandler}.
+ *
+ * A line that starts with {@code [} is a section header, and it must end with {@code ]}. The
+ * name between the brackets is trimmed and unescaped. Any other line is an option, written as
+ * {@code name=value} or {@code name:value}. A line that starts with {@code ;} or {@code #} is a
+ * comment. Comments exist only on lines of their own, so a comment after an option or after a
+ * header is part of the value, or an error. Blank lines are skipped, and lines are trimmed. The
+ * {@link org.ini4j.Config} flags decide a number of details, for example {@link
+ * org.ini4j.Config#isGlobalSection()}, {@link org.ini4j.Config#isUnnamedSection()}, {@link
+ * org.ini4j.Config#isLowerCaseSection()}, {@link org.ini4j.Config#isEscapeNewline()} and {@link
+ * org.ini4j.Config#isInclude()}.
+ *
+ * The events and their order are described in {@link IniHandler}. A line that is not valid
+ * throws an {@link org.ini4j.InvalidFileFormatException} whose message has the line number and the
+ * line.
+ *
+ * The input is closed when it has been read to the end. If an error is found before that, it is
+ * left open.
+ *
+ * @see IniHandler
+ * @see IniFormatter
+ * @since 0.5.0
+ */
public class IniParser extends AbstractParser {
private static final String COMMENTS = ";#";
private static final String OPERATORS = ":=";
static final char SECTION_BEGIN = '[';
static final char SECTION_END = ']';
+ /**
+ * Creates a parser that uses {@link org.ini4j.Config#getGlobal()}.
+ *
+ * Use {@link #newInstance()} or {@link #newInstance(org.ini4j.Config)} unless you want to
+ * bypass the provider lookup.
+ */
public IniParser() {
super(OPERATORS, COMMENTS);
}
+ /**
+ * Creates a parser of this class, or of the class that a provider names.
+ *
+ * The class is looked up in this order, and the first source that has a value wins:
+ *
+ * If the system property cannot be read because of a security manager, it is skipped. A
+ * resource that cannot be read counts as not found. If the thread has no context class loader,
+ * the system class loader is used. There is no fallback after a bad name: if the provider class
+ * is not found, or it is not usable, the call fails. The provider must be a subclass that has a
+ * public constructor with no arguments. The call throws an {@link IllegalArgumentException} if
+ * the class is not found, or if it cannot be created for any reason, including an exception that
+ * its constructor throws. Only an {@link Error} that the Java runtime throws while it loads or
+ * links the class, such as a {@link NoClassDefFoundError} or an {@link
+ * ExceptionInInitializerError}, is not wrapped.
+ *
+ * @return a new parser
+ * @throws IllegalArgumentException if the provider cannot be found or created
+ */
public static IniParser newInstance() {
return ServiceFinder.findService(IniParser.class);
}
+ /**
+ * Creates a parser as {@link #newInstance()} does, and gives it a configuration.
+ *
+ * @param config the configuration to use
+ * @return a new parser
+ * @throws IllegalArgumentException if the provider cannot be found or created
+ */
public static IniParser newInstance(Config config) {
IniParser instance = newInstance();
@@ -45,16 +110,47 @@ public static IniParser newInstance(Config config) {
return instance;
}
+ /**
+ * Parses a stream.
+ *
+ * The bytes are decoded with the file encoding of the configuration, unless a byte order mark
+ * at the start of the stream says otherwise.
+ *
+ * @param input the stream to read
+ * @param handler the receiver of the events
+ * @throws IOException if reading fails
+ * @throws org.ini4j.InvalidFileFormatException if the content is not valid
+ */
public void parse(InputStream input, IniHandler handler)
throws IOException, InvalidFileFormatException {
parse(newIniSource(input, handler), handler);
}
+ /**
+ * Parses a reader.
+ *
+ * @param input the reader to read; the caller has chosen how it decodes
+ * @param handler the receiver of the events
+ * @throws IOException if reading fails
+ * @throws org.ini4j.InvalidFileFormatException if the content is not valid
+ */
public void parse(Reader input, IniHandler handler)
throws IOException, InvalidFileFormatException {
parse(newIniSource(input, handler), handler);
}
+ /**
+ * Parses the content of a URL.
+ *
+ * The bytes are decoded as in {@link #parse(InputStream, IniHandler)}. If {@link
+ * org.ini4j.Config#isInclude()} is on, relative locations in include lines are resolved against
+ * this URL.
+ *
+ * @param input the location to read
+ * @param handler the receiver of the events
+ * @throws IOException if the location cannot be opened or read
+ * @throws org.ini4j.InvalidFileFormatException if the content is not valid
+ */
public void parse(URL input, IniHandler handler) throws IOException, InvalidFileFormatException {
parse(newIniSource(input, handler), handler);
}
diff --git a/src/main/java/org/ini4j/spi/IniSource.java b/src/main/java/org/ini4j/spi/IniSource.java
index 39842af..dc1204c 100644
--- a/src/main/java/org/ini4j/spi/IniSource.java
+++ b/src/main/java/org/ini4j/spi/IniSource.java
@@ -22,6 +22,23 @@
import java.net.URL;
import org.ini4j.Config;
+/**
+ * Reads the logical lines of an INI or options file for the parsers.
+ *
+ * The source reads a line at a time and trims it. It skips blank lines, which also end a
+ * comment. It sends the comment lines to the handler (see {@link
+ * IniHandler#handleComment(String)}). Comment lines that follow each other are one comment, which
+ * is sent when a blank line, a line that is not a comment, or the end of the input comes. When
+ * {@link org.ini4j.Config#isEscapeNewline()} is on, a line that ends with an odd number of
+ * backslashes continues in the next line. When {@link org.ini4j.Config#isInclude()} is on, a line
+ * of the form {@code Because comments are sent while the source looks for the next line, they reach the handler
+ * before the parser handles that line.
+ *
+ * @since 0.5.0
+ */
class IniSource {
public static final char INCLUDE_BEGIN = '<';
public static final char INCLUDE_END = '>';
@@ -54,6 +71,13 @@ class IniSource {
_base = input;
}
+ /**
+ * Returns the number of the line that was read last.
+ *
+ * While lines of an included file are read, it is the line number in that file.
+ *
+ * @return the line number, which is 1 for the first line and 0 before any line has been read
+ */
int getLineNumber() {
int ret;
@@ -66,6 +90,17 @@ int getLineNumber() {
return ret;
}
+ /**
+ * Returns the next logical line.
+ *
+ * The line is trimmed and is neither blank nor a comment. The comments that were collected on
+ * the way have been sent to the handler by the time the method returns, and so have those at the
+ * end of the input when {@code null} is returned. Blank lines are skipped and not sent.
+ *
+ * @return the line, or {@code null} at the end of the input
+ * @throws IOException if reading fails, or an include line cannot be opened and is not optional,
+ * or its location is malformed
+ */
String readLine() throws IOException {
String line;
@@ -174,7 +209,7 @@ private String readLineSkipComments() throws IOException {
}
}
- // handle end comments
+ // report the comments at the end of the input
if ((line == null) && (comment.length() != 0)) {
handleComment(comment);
}
diff --git a/src/main/java/org/ini4j/spi/OptionsBuilder.java b/src/main/java/org/ini4j/spi/OptionsBuilder.java
index d9baa39..83c998f 100644
--- a/src/main/java/org/ini4j/spi/OptionsBuilder.java
+++ b/src/main/java/org/ini4j/spi/OptionsBuilder.java
@@ -18,12 +18,38 @@
import org.ini4j.Config;
import org.ini4j.Options;
+/**
+ * Fills an {@link org.ini4j.Options} from the events of an {@link OptionsParser}.
+ *
+ * {@code handleOption} adds the value, or replaces the last value if {@link
+ * org.ini4j.Config#isMultiOption()} is off. Comments are kept only if {@link
+ * org.ini4j.Config#isComment()} is on, as follows. A comment is held until the next option and
+ * becomes the comment of that option. If another comment arrives first, it replaces the held one,
+ * which is lost. The exception is the first comment of the file: with {@link
+ * org.ini4j.Config#isHeaderComment()} on, the first comment before the first option is not lost but
+ * becomes the comment of the {@code Options} itself, whether it is followed by an option, another
+ * comment, or the end of the file. A comment that is not followed by an option, such as a comment
+ * at the end of the file, is lost.
+ *
+ * @see OptionsParser
+ * @since 0.5.0
+ */
@edu.umd.cs.findbugs.annotations.SuppressFBWarnings("EI_EXPOSE_REP2")
public class OptionsBuilder implements OptionsHandler {
private boolean _header;
private String _lastComment;
private Options _options;
+ /**
+ * Creates a builder of this class, or of the class that a provider names, for an {@code Options}.
+ *
+ * The lookup is the same as in {@link IniParser#newInstance()}, with the name {@code
+ * org.ini4j.spi.OptionsBuilder}.
+ *
+ * @param opts the object to fill; it is used directly, not copied
+ * @return a new builder
+ * @throws IllegalArgumentException if the provider cannot be found or created
+ */
public static OptionsBuilder newInstance(Options opts) {
OptionsBuilder instance = newInstance();
@@ -32,19 +58,34 @@ public static OptionsBuilder newInstance(Options opts) {
return instance;
}
+ /**
+ * Sets the object to fill.
+ *
+ * @param value the object to fill; it is used directly, not copied
+ */
public void setOptions(Options value) {
_options = value;
}
+ /**
+ * Ends the file. A comment that is the only content of the file becomes the comment of the {@code
+ * Options}, if {@link org.ini4j.Config#isComment()} and {@link
+ * org.ini4j.Config#isHeaderComment()} are on.
+ */
@Override
public void endOptions() {
- // comment only .opt file ...
+ // a file that has nothing but a comment
if ((_lastComment != null) && _header) {
setHeaderComment();
}
}
+ /**
+ * Receives a comment.
+ *
+ * @param comment the text of the comment
+ */
@Override
public void handleComment(String comment) {
if ((_lastComment != null) && _header) {
@@ -55,6 +96,12 @@ public void handleComment(String comment) {
_lastComment = comment;
}
+ /**
+ * Adds an option.
+ *
+ * @param name the name of the option
+ * @param value the value of the option, or {@code null}
+ */
@Override
public void handleOption(String name, String value) {
if (getConfig().isMultiOption()) {
@@ -76,6 +123,7 @@ public void handleOption(String name, String value) {
_header = false;
}
+ /** Starts the file. */
@Override
public void startOptions() {
if (getConfig().isHeaderComment()) {
@@ -83,6 +131,17 @@ public void startOptions() {
}
}
+ /**
+ * Creates a builder of this class, or of the class that a provider names, without an object to
+ * fill.
+ *
+ * The lookup is the same as in {@link IniParser#newInstance()}, with the name {@code
+ * org.ini4j.spi.OptionsBuilder}. Call {@link #setOptions(Options)} before the builder receives
+ * events.
+ *
+ * @return a new builder
+ * @throws IllegalArgumentException if the provider cannot be found or created
+ */
protected static OptionsBuilder newInstance() {
return ServiceFinder.findService(OptionsBuilder.class);
}
diff --git a/src/main/java/org/ini4j/spi/OptionsFormatter.java b/src/main/java/org/ini4j/spi/OptionsFormatter.java
index 613a2e9..caa0411 100644
--- a/src/main/java/org/ini4j/spi/OptionsFormatter.java
+++ b/src/main/java/org/ini4j/spi/OptionsFormatter.java
@@ -19,7 +19,29 @@
import java.io.Writer;
import org.ini4j.Config;
+/**
+ * Writes the events of a file of options as text.
+ *
+ * Comments and options are written as described in {@link #handleComment(String)} and {@link
+ * #handleOption(String, String)}. The writer is flushed at the end of the file and is never closed.
+ *
+ * @see OptionsHandler
+ * @see OptionsParser
+ * @since 0.5.0
+ */
public class OptionsFormatter extends AbstractFormatter implements OptionsHandler {
+ /**
+ * Creates a formatter of this class, or of the class that a provider names.
+ *
+ * The lookup is the same as in {@link IniParser#newInstance()}, with the name {@code
+ * org.ini4j.spi.OptionsFormatter}.
+ *
+ * @param out the writer for the text; it is used directly if it is a {@link java.io.PrintWriter},
+ * and wrapped in one otherwise
+ * @param config the configuration to use
+ * @return a new formatter
+ * @throws IllegalArgumentException if the provider cannot be found or created
+ */
public static OptionsFormatter newInstance(Writer out, Config config) {
OptionsFormatter instance = newInstance();
@@ -29,10 +51,12 @@ public static OptionsFormatter newInstance(Writer out, Config config) {
return instance;
}
+ /** Flushes the writer. */
public void endOptions() {
getOutput().flush();
}
+ /** Does nothing. */
public void startOptions() {
assert true;
}
diff --git a/src/main/java/org/ini4j/spi/OptionsHandler.java b/src/main/java/org/ini4j/spi/OptionsHandler.java
index 3f44af4..a33175f 100644
--- a/src/main/java/org/ini4j/spi/OptionsHandler.java
+++ b/src/main/java/org/ini4j/spi/OptionsHandler.java
@@ -15,14 +15,55 @@
*/
package org.ini4j.spi;
+/**
+ * Receives the events of a file of options without sections, in the order of the file.
+ *
+ * The same interface is used in both directions. An {@link OptionsParser} calls it while it
+ * reads a file, and an {@link org.ini4j.Options} calls it while it is stored. The calls are {@link
+ * #startOptions()}, then {@link #handleOption(String, String)} for each option, and {@link
+ * #endOptions()}.
+ *
+ * {@link #handleComment(String)} can come at any point between the start and the end. A comment
+ * is reported just before the option it belongs to, and a comment at the end of the file arrives
+ * before {@link #endOptions()}. The order is promised only for a successful parse. If the parser
+ * throws an exception, {@link #endOptions()} may be missing.
+ *
+ * When a file is stored, the calls between {@link #startOptions()} and {@link #endOptions()} are
+ * the header comment, then for each option its comment and one {@link #handleOption(String,
+ * String)} call for each value. In this direction a comment can be {@code null}, which means there
+ * is none. When {@link org.ini4j.Config#isMultiOption()} is off, only one value of each option is
+ * sent, the first one.
+ *
+ * @see OptionsParser
+ * @see OptionsFormatter
+ * @see OptionsBuilder
+ * @since 0.5.0
+ */
public interface OptionsHandler extends HandlerBase {
+ /** Ends the file. The parser calls it after the last option. */
void endOptions();
+ /**
+ * Receives a comment.
+ *
+ * The text is as described for {@link IniHandler#handleComment(String)}, with the comment
+ * characters of this format.
+ *
+ * @param comment the text of the comment
+ */
@Override
void handleComment(String comment);
+ /**
+ * Receives an option.
+ *
+ * @param optionName the name of the option, never {@code null}
+ * @param optionValue the value of the option; it is {@code null} for an option without a value,
+ * which the parser allows only when {@link org.ini4j.Config#isEmptyOption()} is on
+ */
@Override
void handleOption(String optionName, String optionValue);
+ /** Starts the file. It is the first call. */
void startOptions();
}
diff --git a/src/main/java/org/ini4j/spi/OptionsParser.java b/src/main/java/org/ini4j/spi/OptionsParser.java
index a366f60..e308208 100644
--- a/src/main/java/org/ini4j/spi/OptionsParser.java
+++ b/src/main/java/org/ini4j/spi/OptionsParser.java
@@ -22,18 +22,57 @@
import org.ini4j.Config;
import org.ini4j.InvalidFileFormatException;
+/**
+ * Parses files of options without sections and sends the events to an {@link OptionsHandler}.
+ *
+ * Every line is an option, written as {@code name=value} or {@code name:value}. A line that
+ * starts with {@code !} or {@code #} is a comment. Blank lines are skipped and lines are trimmed.
+ * The rules for names, values and the {@link org.ini4j.Config} flags are the same as in {@link
+ * IniParser}, except that there are no sections.
+ *
+ * The events and their order are described in {@link OptionsHandler}. A line that is not valid
+ * throws an {@link org.ini4j.InvalidFileFormatException} whose message has the line number and the
+ * line. The input is closed when it has been read to the end. If an error is found before that, it
+ * is left open.
+ *
+ * @see OptionsHandler
+ * @see OptionsFormatter
+ * @since 0.5.0
+ */
public class OptionsParser extends AbstractParser {
private static final String COMMENTS = "!#";
private static final String OPERATORS = ":=";
+ /**
+ * Creates a parser that uses {@link org.ini4j.Config#getGlobal()}.
+ *
+ * Use {@link #newInstance()} or {@link #newInstance(org.ini4j.Config)} unless you want to
+ * bypass the provider lookup.
+ */
public OptionsParser() {
super(OPERATORS, COMMENTS);
}
+ /**
+ * Creates a parser of this class, or of the class that a provider names.
+ *
+ * The lookup is the same as in {@link IniParser#newInstance()}, with the name {@code
+ * org.ini4j.spi.OptionsParser}.
+ *
+ * @return a new parser
+ * @throws IllegalArgumentException if the provider cannot be found or created
+ */
public static OptionsParser newInstance() {
return ServiceFinder.findService(OptionsParser.class);
}
+ /**
+ * Creates a parser as {@link #newInstance()} does, and gives it a configuration.
+ *
+ * @param config the configuration to use
+ * @return a new parser
+ * @throws IllegalArgumentException if the provider cannot be found or created
+ */
public static OptionsParser newInstance(Config config) {
OptionsParser instance = newInstance();
@@ -42,16 +81,47 @@ public static OptionsParser newInstance(Config config) {
return instance;
}
+ /**
+ * Parses a stream.
+ *
+ * The bytes are decoded with the file encoding of the configuration, unless a byte order mark
+ * at the start of the stream says otherwise.
+ *
+ * @param input the stream to read
+ * @param handler the receiver of the events
+ * @throws IOException if reading fails
+ * @throws org.ini4j.InvalidFileFormatException if the content is not valid
+ */
public void parse(InputStream input, OptionsHandler handler)
throws IOException, InvalidFileFormatException {
parse(newIniSource(input, handler), handler);
}
+ /**
+ * Parses a reader.
+ *
+ * @param input the reader to read; the caller has chosen how it decodes
+ * @param handler the receiver of the events
+ * @throws IOException if reading fails
+ * @throws org.ini4j.InvalidFileFormatException if the content is not valid
+ */
public void parse(Reader input, OptionsHandler handler)
throws IOException, InvalidFileFormatException {
parse(newIniSource(input, handler), handler);
}
+ /**
+ * Parses the content of a URL.
+ *
+ * The bytes are decoded as in {@link #parse(InputStream, OptionsHandler)}. If {@link
+ * org.ini4j.Config#isInclude()} is on, relative locations in include lines are resolved against
+ * this URL.
+ *
+ * @param input the location to read
+ * @param handler the receiver of the events
+ * @throws IOException if the location cannot be opened or read
+ * @throws org.ini4j.InvalidFileFormatException if the content is not valid
+ */
public void parse(URL input, OptionsHandler handler)
throws IOException, InvalidFileFormatException {
parse(newIniSource(input, handler), handler);
diff --git a/src/main/java/org/ini4j/spi/RegBuilder.java b/src/main/java/org/ini4j/spi/RegBuilder.java
index 1200738..43aad27 100644
--- a/src/main/java/org/ini4j/spi/RegBuilder.java
+++ b/src/main/java/org/ini4j/spi/RegBuilder.java
@@ -21,10 +21,34 @@
import org.ini4j.Registry.Key;
import org.ini4j.Registry.Type;
+/**
+ * Fills a {@link org.ini4j.Reg} from the events of an {@link IniParser}.
+ *
+ * Sections, options and comments are handled as described in {@link IniBuilder}. In addition,
+ * each option is a registry value. A name in double quotes is unquoted, and the name {@code @} is
+ * kept as it is. The raw value is decoded by {@link RegEscapeTool}: the value types that are not
+ * {@link org.ini4j.Registry.Type#REG_SZ} are remembered in the key with {@link
+ * org.ini4j.Registry.Key#putType(String, org.ini4j.Registry.Type)}, and a multi-string value gives
+ * one value for each string, or only the last string if {@link org.ini4j.Config#isMultiOption()} is
+ * off. A comment before a value is the comment of its name.
+ *
+ * @see org.ini4j.Reg
+ * @since 0.5.0
+ */
@edu.umd.cs.findbugs.annotations.SuppressFBWarnings("EI_EXPOSE_REP2")
public class RegBuilder extends AbstractProfileBuilder {
private Reg _reg;
+ /**
+ * Creates a builder of this class, or of the class that a provider names, for a {@code Reg}.
+ *
+ * The lookup is the same as in {@link IniParser#newInstance()}, with the name {@code
+ * org.ini4j.spi.RegBuilder}.
+ *
+ * @param reg the object to fill; it is used directly, not copied
+ * @return a new builder
+ * @throws IllegalArgumentException if the provider cannot be found or created
+ */
public static RegBuilder newInstance(Reg reg) {
RegBuilder instance = newInstance();
@@ -33,10 +57,25 @@ public static RegBuilder newInstance(Reg reg) {
return instance;
}
+ /**
+ * Sets the object to fill.
+ *
+ * @param value the object to fill; it is used directly, not copied
+ */
public void setReg(Reg value) {
_reg = value;
}
+ /**
+ * Adds a registry value to the current key.
+ *
+ * @param rawName the name as written in the file, in double quotes unless it is {@code @}
+ * @param rawValue the value as written in the file, with its type prefix if it has one
+ * @throws NullPointerException if there is no current key
+ * @throws StringIndexOutOfBoundsException if {@code rawName} or {@code rawValue} is empty
+ * @throws IllegalArgumentException if the value cannot be decoded, for example a {@code dword}
+ * that is not a hexadecimal number
+ */
@Override
public void handleOption(String rawName, String rawValue) {
String name =
diff --git a/src/main/java/org/ini4j/spi/RegEscapeTool.java b/src/main/java/org/ini4j/spi/RegEscapeTool.java
index 0807f75..d9ed55f 100644
--- a/src/main/java/org/ini4j/spi/RegEscapeTool.java
+++ b/src/main/java/org/ini4j/spi/RegEscapeTool.java
@@ -21,6 +21,23 @@
import org.ini4j.Registry;
import org.ini4j.Registry.Type;
+/**
+ * Converts registry values between the text of a {@code .reg} file and their type and values.
+ *
+ * The text of a value in a {@code .reg} file is either a quoted string, or a type prefix, a
+ * colon and the data (see {@link org.ini4j.Registry.Type}). {@link #decode(String)} and {@link
+ * #encode(TypeValuesPair)} convert between that text and a {@link TypeValuesPair}. Quoting is
+ * inherited from {@link EscapeTool}.
+ *
+ * The instance is created once, when the class is first used, with the provider lookup described
+ * in {@link IniParser#newInstance()}, using the name {@code org.ini4j.spi.RegEscapeTool}. A
+ * provider that cannot be created makes the class initialization fail.
+ *
+ * The class has no state, so it can be used from several threads.
+ *
+ * @see org.ini4j.Reg
+ * @since 0.5.0
+ */
public class RegEscapeTool extends EscapeTool {
private static final RegEscapeTool INSTANCE = ServiceFinder.findService(RegEscapeTool.class);
private static final Charset HEX_CHARSET = StandardCharsets.UTF_16LE;
@@ -28,10 +45,33 @@ public class RegEscapeTool extends EscapeTool {
private static final int UPPER_DIGIT = 0xf0;
private static final int DIGIT_SIZE = 4;
+ /**
+ * Returns the shared instance.
+ *
+ * @return the instance
+ */
public static final RegEscapeTool getInstance() {
return INSTANCE;
}
+ /**
+ * Splits the text of a value into its type and values.
+ *
+ * A text that starts with a double quote is a {@link org.ini4j.Registry.Type#REG_SZ} string,
+ * and a text without a colon is one too. For a string, the first and last character are removed,
+ * whatever they are, and the escapes are resolved. The types {@link
+ * org.ini4j.Registry.Type#REG_EXPAND_SZ} and {@link org.ini4j.Registry.Type#REG_MULTI_SZ} hold
+ * hexadecimal bytes of UTF-16 little endian text, which are decoded; the multi-string gives one
+ * value for each string. A {@link org.ini4j.Registry.Type#REG_DWORD} gives its decimal text. For
+ * any other type, the data after the colon is the only value, as written.
+ *
+ * @param raw the text of the value
+ * @return the type and the values
+ * @throws NullPointerException if the type prefix is not known
+ * @throws NumberFormatException if a {@code dword} is not a hexadecimal number
+ * @throws StringIndexOutOfBoundsException if the text is empty, or the data of a {@code
+ * REG_EXPAND_SZ} value is empty
+ */
public TypeValuesPair decode(String raw) {
Type type = type(raw);
String value =
@@ -65,6 +105,22 @@ public TypeValuesPair decode(String raw) {
return new TypeValuesPair(type, values);
}
+ /**
+ * Writes a type and values as the text of a value.
+ *
+ * A {@link org.ini4j.Registry.Type#REG_SZ} string is quoted, and only its first value is used.
+ * An empty string is written as empty text, without quotes, as {@link #quote(String)} does, and
+ * {@link #decode(String)} cannot read that either. For the other types the text is the prefix of
+ * the type, a colon and the data, written in the form that {@link #decode(String)} reads, except
+ * that an empty {@code REG_EXPAND_SZ} value is written as empty data, which {@link
+ * #decode(String)} cannot read. Only the first value is used except for {@link
+ * org.ini4j.Registry.Type#REG_MULTI_SZ}, which writes all of them.
+ *
+ * @param data the type and values
+ * @return the text, or {@code null} if the first value is {@code null}
+ * @throws NumberFormatException if the type is {@code REG_DWORD} and the value is not a number
+ * @throws ArrayIndexOutOfBoundsException if the array of values is empty
+ */
public String encode(TypeValuesPair data) {
String ret = null;
diff --git a/src/main/java/org/ini4j/spi/ServiceFinder.java b/src/main/java/org/ini4j/spi/ServiceFinder.java
index 3019016..6ea027e 100755
--- a/src/main/java/org/ini4j/spi/ServiceFinder.java
+++ b/src/main/java/org/ini4j/spi/ServiceFinder.java
@@ -22,10 +22,14 @@
import java.nio.charset.StandardCharsets;
/**
- * JDK JAR Services API alap� service keres� oszt�ly.
+ * Finds the provider of a service and creates it.
*
- * @author Szkiba Iv�n
- * @version $Name: $
+ * It follows the JAR Services API of the JDK, with a system property as an extra first source.
+ * Every {@code newInstance()} method of the SPI classes uses it, and so do the shared instances of
+ * {@link EscapeTool}, {@link RegEscapeTool} and {@link BeanTool}. The public description of the
+ * lookup is in {@link IniParser#newInstance()}.
+ *
+ * @since 0.4.1
*/
final class ServiceFinder {
private static final String SERVICES_PATH = "META-INF/services/";
@@ -33,28 +37,27 @@ final class ServiceFinder {
private ServiceFinder() {}
/**
- * Service objektum keres�s �s p�ld�nyos�t�s
- *
- * a JDK JAR specifik�ci�ban defini�lt Services API-nak megfelel�en service oszt�ly
- * keres�s, majd pedig p�ld�ny k�pz�s a context ClassLoader seg�ts�g�vel.
+ * Finds the provider class of a service and creates an instance of it.
*
- * Az implement�l� oszt�ly n�v keres�se a The name of the provider class is looked up in this order: the system property that is named
+ * like the service class, then the first line of the resource {@code META-INF/services/} and the
+ * name of the service class (see {@link #findServiceClassName(String)}). If neither gives a name,
+ * the service class itself is the provider. The class is loaded with the context class loader of
+ * the current thread, and created with its constructor that has no arguments.
*
- * A fenti keres�st k�vet�en t�rt�nik a p�ld�ny k�pz�s. A visszat�r�si �rt�k mindig egy val�di
- * objektum, l�v�n minden hiba exception-t gener�l.
+ * The result is never {@code null}: every failure throws an exception.
*
- * @param The name comes from {@link #findServiceClassName(String)}. If there is no name, the result
+ * is the service class itself. A name is loaded with the context class loader of the current
+ * thread, or with {@link Class#forName(String)} if the thread has none.
+ *
+ * @param The first source that gives a value wins. The sources are the system property that has the
+ * service name as its name, and the first line of the resource {@code META-INF/services/}
+ * followed by the service name. A system property that cannot be read because of a security
+ * manager is skipped. See {@link #loadLine(String)} for the resource.
+ *
+ * @param serviceId the fully qualified name of the service class
+ * @return the name of the provider class, or {@code null} if there is none
+ */
static String findServiceClassName(String serviceId) throws IllegalArgumentException {
String serviceClassName = null;
@@ -108,6 +135,18 @@ static String findServiceClassName(String serviceId) throws IllegalArgumentExcep
return serviceClassName;
}
+ /**
+ * Reads the provider name from a service resource.
+ *
+ * Only the first line of the resource is read, with the UTF-8 character set, using the context
+ * class loader of the current thread (or the system class loader if there is none). The line is
+ * trimmed and cut at the first white space or {@code #}. A blank first line gives {@code null},
+ * and a line that starts with {@code #} gives an empty text. Any failure while reading is ignored
+ * and gives {@code null}.
+ *
+ * @param servicePath the path of the resource
+ * @return the name from the first line, or {@code null}
+ */
@edu.umd.cs.findbugs.annotations.SuppressFBWarnings("REC_CATCH_EXCEPTION")
private static String loadLine(String servicePath) {
String ret = null;
diff --git a/src/main/java/org/ini4j/spi/TypeValuesPair.java b/src/main/java/org/ini4j/spi/TypeValuesPair.java
index bd8abc3..131de99 100644
--- a/src/main/java/org/ini4j/spi/TypeValuesPair.java
+++ b/src/main/java/org/ini4j/spi/TypeValuesPair.java
@@ -17,21 +17,47 @@
import org.ini4j.Registry.Type;
+/**
+ * A registry value type with the values of that type.
+ *
+ * It is the result of {@link RegEscapeTool#decode(String)} and the argument of {@link
+ * RegEscapeTool#encode(TypeValuesPair)}. The array of values is not copied, neither by the
+ * constructor nor by {@link #getValues()}, so a change to the array shows in the pair. The class
+ * has no synchronization.
+ *
+ * @since 0.5.0
+ */
@edu.umd.cs.findbugs.annotations.SuppressFBWarnings("EI_EXPOSE_REP")
public class TypeValuesPair {
private final Type _type;
private final String[] _values;
+ /**
+ * Creates a pair.
+ *
+ * @param type the type of the values
+ * @param values the values; the array is stored, not copied
+ */
@SuppressWarnings("PMD.ArrayIsStoredDirectly")
public TypeValuesPair(Type type, String[] values) {
_type = type;
_values = values;
}
+ /**
+ * Returns the type.
+ *
+ * @return the type
+ */
public Type getType() {
return _type;
}
+ /**
+ * Returns the values.
+ *
+ * @return the array that was given to the constructor, not a copy
+ */
public String[] getValues() {
return _values;
}
diff --git a/src/main/java/org/ini4j/spi/UnicodeInputStreamReader.java b/src/main/java/org/ini4j/spi/UnicodeInputStreamReader.java
index 405f7fb..8a82204 100644
--- a/src/main/java/org/ini4j/spi/UnicodeInputStreamReader.java
+++ b/src/main/java/org/ini4j/spi/UnicodeInputStreamReader.java
@@ -22,6 +22,16 @@
import java.io.Reader;
import java.nio.charset.Charset;
+/**
+ * A reader for a stream whose character set is chosen by its byte order mark.
+ *
+ * If the stream starts with a byte order mark of UTF-8, UTF-16 or UTF-32 (the ones the JVM
+ * supports), the mark is skipped and its character set is used. Otherwise the default character set
+ * that was given to the constructor is used. The check runs when the stream is first read or
+ * closed.
+ *
+ * @since 0.5.2
+ */
class UnicodeInputStreamReader extends Reader {
private static final int BOM_SIZE = 4;
@@ -101,8 +111,15 @@ public int read(char[] cbuf, int off, int len) throws IOException {
}
/**
- * Read-ahead four bytes and check for BOM marks. Extra bytes are unread back to the stream, only
- * BOM bytes are skipped.
+ * Reads the first bytes of the stream and looks for a byte order mark.
+ *
+ * Up to four bytes are read. If they start with a byte order mark, the mark is skipped and the
+ * bytes after it are pushed back to the stream. Otherwise all the bytes that were read are pushed
+ * back. The method does nothing after the first call. The number of bytes to push back after a
+ * byte order mark assumes that four bytes were read. If the input is shorter and starts with a
+ * byte order mark, bytes of the mark can be pushed back and then read as text.
+ *
+ * @throws IOException if reading fails
*/
protected void init() throws IOException {
if (_reader != null) {
diff --git a/src/main/java/org/ini4j/spi/Warnings.java b/src/main/java/org/ini4j/spi/Warnings.java
index a085d10..90a042e 100644
--- a/src/main/java/org/ini4j/spi/Warnings.java
+++ b/src/main/java/org/ini4j/spi/Warnings.java
@@ -15,7 +15,16 @@
*/
package org.ini4j.spi;
+/**
+ * Constants for {@link SuppressWarnings}.
+ *
+ * The class only gives a name to the strings, so the library uses one spelling. It cannot be
+ * instantiated.
+ *
+ * @since 0.4.1
+ */
public final class Warnings {
+ /** The name of the {@code unchecked} warning. */
public static final String UNCHECKED = "unchecked";
private Warnings() {
diff --git a/src/main/java/org/ini4j/spi/WinEscapeTool.java b/src/main/java/org/ini4j/spi/WinEscapeTool.java
index 50bafc2..ac6f7e7 100644
--- a/src/main/java/org/ini4j/spi/WinEscapeTool.java
+++ b/src/main/java/org/ini4j/spi/WinEscapeTool.java
@@ -15,6 +15,20 @@
*/
package org.ini4j.spi;
+/**
+ * The escape form of Windows INI files.
+ *
+ * It is like {@link EscapeTool}, but a character without a short form is written as a backslash,
+ * the letter {@code x} and two hexadecimal digits that hold the low byte of the character, so
+ * characters above {@code U+00FF} lose their upper byte. When reading, a backslash and {@code x}
+ * with two hexadecimal digits, or {@code o} with three octal digits, gives the character with that
+ * code, and a backslash with {@code u} has no special meaning. {@link
+ * org.ini4j.Wini#escape(String)} uses it.
+ *
+ * The class has no state, so it can be used from several threads.
+ *
+ * @since 0.5.0
+ */
public final class WinEscapeTool extends EscapeTool {
private static final int ANSI_HEX_DIGITS = 2;
private static final int ANSI_OCTAL_DIGITS = 3;
@@ -25,6 +39,11 @@ private WinEscapeTool() {
// singleton
}
+ /**
+ * Returns the shared instance. It does not use the provider lookup.
+ *
+ * @return the instance
+ */
public static WinEscapeTool getInstance() {
return INSTANCE;
}
diff --git a/src/main/java/org/ini4j/spi/package-info.java b/src/main/java/org/ini4j/spi/package-info.java
new file mode 100644
index 0000000..45b929e
--- /dev/null
+++ b/src/main/java/org/ini4j/spi/package-info.java
@@ -0,0 +1,42 @@
+/*
+ * Copyright 2005,2009 Ivan SZKIBA
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * The parsers, formatters and handlers that read and write the files, and the tools they use.
+ *
+ * Reading and writing work with events. A parser ({@link org.ini4j.spi.IniParser}, {@link
+ * org.ini4j.spi.OptionsParser}) reads a file and calls the methods of a handler ({@link
+ * org.ini4j.spi.IniHandler}, {@link org.ini4j.spi.OptionsHandler}) for each section, option and
+ * comment. A builder ({@link org.ini4j.spi.IniBuilder}, {@link org.ini4j.spi.OptionsBuilder},
+ * {@link org.ini4j.spi.RegBuilder}) is a handler that fills an {@link org.ini4j.Ini}, an {@link
+ * org.ini4j.Options} or a {@link org.ini4j.Reg} from these events. A formatter ({@link
+ * org.ini4j.spi.IniFormatter}, {@link org.ini4j.spi.OptionsFormatter}) is a handler that writes the
+ * events as text. When an object is stored, it sends its content to a formatter as the same events.
+ * The order of the events is described in {@link org.ini4j.spi.IniHandler} and {@link
+ * org.ini4j.spi.OptionsHandler}.
+ *
+ * The classes that do this work can be replaced. The factory methods, such as {@link
+ * org.ini4j.spi.IniParser#newInstance()}, look for the class to create in the system property that
+ * is named like the class, then in the first line of the file {@code META-INF/services/} and the
+ * name of the class, and use the class itself if there is no such name. The provider is a subclass
+ * with a public constructor without arguments. The full description is in {@link
+ * org.ini4j.spi.IniParser#newInstance()}.
+ *
+ * The package also has the tools for the escape forms ({@link org.ini4j.spi.EscapeTool}, {@link
+ * org.ini4j.spi.WinEscapeTool}, {@link org.ini4j.spi.RegEscapeTool}) and for beans ({@link
+ * org.ini4j.spi.BeanTool}, {@link org.ini4j.spi.BeanAccess}, {@link
+ * org.ini4j.spi.AbstractBeanInvocationHandler}).
+ */
+package org.ini4j.spi;
diff --git a/src/main/java/org/ini4j/spi/package.html b/src/main/java/org/ini4j/spi/package.html
deleted file mode 100644
index ba730a2..0000000
--- a/src/main/java/org/ini4j/spi/package.html
+++ /dev/null
@@ -1,30 +0,0 @@
-
-
-
-
- This package contains [ini4j] service provider API.
-
* [section1]
@@ -30,23 +31,25 @@
* b = ${section1/a}
*
*
- * {@code
+ * Config cfg = Config.getGlobal().clone();
+ * cfg.setMultiSection(true);
+ *
+ * Ini ini = new Ini();
+ * ini.setConfig(cfg);
+ * ini.load(new File("dwarfs.ini"));
+ * }
+ *
+ * {@code
+ * Ini ini = new Ini(new File("dwarfs.ini"));
+ * int age = ini.get("happy", "age", int.class);
+ * String dir = ini.get("happy", "homeDir");
+ *
+ * ini.put("sleepy", "age", 55);
+ * ini.store();
+ * }
+ *
+ * {@code
+ * Ini ini = new Ini(new File("dwarfs.ini"));
+ * Preferences prefs = new IniPreferences(ini);
+ * Preferences bashful = prefs.node("bashful");
+ *
+ * int age = bashful.getInt("age", -1);
+ * bashful.putDouble("weight", 55.6);
+ * ini.store();
+ * }
+ *
+ * @see IniPreferencesFactory
+ * @since 0.3.0
+ */
@edu.umd.cs.findbugs.annotations.SuppressFBWarnings("EI_EXPOSE_REP")
public class IniPreferences extends AbstractPreferences {
- /** frequently used empty String array */
+ /** A shared empty array of strings. */
private static final String[] EMPTY = {};
- /** underlaying Ini implementation */
+ /** The {@code Ini} that holds the data. */
private final Ini _ini;
/**
- * Constructs a new preferences node on top of Ini instance.
+ * Creates the root node on top of an {@link Ini}.
*
- * @param ini underlaying Ini instance
+ * @param ini the {@code Ini} that holds the data; it is used directly, not copied
*/
public IniPreferences(Ini ini) {
super(null, "");
@@ -44,14 +76,11 @@ public IniPreferences(Ini ini) {
}
/**
- * Constructs a new preferences node based on newly loaded Ini instance.
- *
- * IniPreferences
- * directly from Reader.
+ * Creates the root node on top of a new {@link Ini} that is loaded from a reader.
*
- * @param input the Reader containing Ini data
- * @throws IOException if an I/O error occured
- * @throws InvalidFileFormatException if Ini parsing error occured
+ * @param input the reader that provides the INI data
+ * @throws IOException if reading fails
+ * @throws InvalidFileFormatException if the data is not valid
*/
public IniPreferences(Reader input) throws IOException, InvalidFileFormatException {
super(null, "");
@@ -59,14 +88,11 @@ public IniPreferences(Reader input) throws IOException, InvalidFileFormatExcepti
}
/**
- * Constructs a new preferences node based on newly loaded Ini instance.
+ * Creates the root node on top of a new {@link Ini} that is loaded from a stream.
*
- * IniPreferences
- * directly from InputStream.
- *
- * @param input the InputStream containing Ini data
- * @throws IOException if an I/O error occured
- * @throws InvalidFileFormatException if Ini parsing error occured
+ * @param input the stream that provides the INI data
+ * @throws IOException if reading fails
+ * @throws InvalidFileFormatException if the data is not valid
*/
public IniPreferences(InputStream input) throws IOException, InvalidFileFormatException {
super(null, "");
@@ -74,14 +100,11 @@ public IniPreferences(InputStream input) throws IOException, InvalidFileFormatEx
}
/**
- * Constructs a new preferences node based on newly loaded Ini instance.
- *
- * IniPreferences
- * directly from URL.
+ * Creates the root node on top of a new {@link Ini} that is loaded from a URL.
*
- * @param input the URL containing Ini data
- * @throws IOException if an I/O error occured
- * @throws InvalidFileFormatException if Ini parsing error occured
+ * @param input the location of the INI data
+ * @throws IOException if reading fails
+ * @throws InvalidFileFormatException if the data is not valid
*/
public IniPreferences(URL input) throws IOException, InvalidFileFormatException {
super(null, "");
@@ -89,25 +112,23 @@ public IniPreferences(URL input) throws IOException, InvalidFileFormatException
}
/**
- * Provide access to underlaying {@link org.ini4j.Ini} implementation.
+ * Returns the {@link Ini} that holds the data.
*
- * @return Ini implementation
+ * @return the {@code Ini}, not a copy
*/
protected Ini getIni() {
return _ini;
}
/**
- * Implements the getSpi method as per the specification in {@link
- * java.util.prefs.AbstractPreferences#getSpi(String)}.
+ * Not supported. The root node has no keys.
*
- * childrenNamesSpi method as per the specification in {@link
- * java.util.prefs.AbstractPreferences#childrenNamesSpi()}.
+ * Returns the names of the child nodes, which are the sections that are not below another
+ * section.
*
- * @return an array containing the names of the children of this preference node.
- * @throws BackingStoreException if this operation cannot be completed due to a failure in the
- * backing store, or inability to communicate with it.
+ * childSpi method as per the specification in {@link
- * java.util.prefs.AbstractPreferences#childSpi(String)}.
+ * Returns the child node for a section.
+ *
+ * flushSpi method as per the specification in {@link
- * java.util.prefs.AbstractPreferences#flushSpi()}.
- *
- * keysSpi method as per the specification in {@link
- * java.util.prefs.AbstractPreferences#keysSpi()}.
+ * Returns no keys. The root node has no keys.
*
- * putSpi method as per the specification in {@link
- * java.util.prefs.AbstractPreferences#putSpi(String,String)}.
- *
- * removeNodeSpi method as per the specification in {@link
- * java.util.prefs.AbstractPreferences#removeNodeSpi()}.
+ * Not supported. The root node cannot be removed.
*
- * removeSpi method as per the specification in {@link
- * java.util.prefs.AbstractPreferences#removeSpi(String)}.
+ * Not supported. The root node has no keys.
*
- * @param key key to remove
- * @throws UnsupportedOperationException this implementation allways throws this exception
+ * @param key the key
+ * @throws UnsupportedOperationException always
*/
@Override
protected void removeSpi(String key) throws UnsupportedOperationException {
@@ -227,30 +235,37 @@ protected void removeSpi(String key) throws UnsupportedOperationException {
}
/**
- * Implements the syncSpi method as per the specification in {@link
- * java.util.prefs.AbstractPreferences#syncSpi()}.
- *
- * Section implementation */
+ /** The section of this node. */
private final Ini.Section _section;
/**
- * Constructs a new SectionPreferences instance on top of Ini.Section instance.
+ * Creates a node for a section.
*
- * @param parent parent preferences node
- * @parem section underlaying Ini.Section instance
- * @param isNew indicate is this a new node or already existing one
+ * @param parent the parent node
+ * @param section the section of this node
+ * @param isNew whether the node is new, which is the case if the section did not exist before
*/
SectionPreferences(AbstractPreferences parent, Ini.Section section, boolean isNew) {
super(parent, section.getSimpleName());
@@ -259,13 +274,9 @@ protected class SectionPreferences extends AbstractPreferences {
}
/**
- * Implements the flush method as per the specification in {@link
- * java.util.prefs.Preferences#flush()}.
- *
- * flush() method.
+ * Calls {@code flush()} of the parent node, which does nothing.
*
- * @throws BackingStoreException if this operation cannot be completed due to a failure in the
- * backing store, or inability to communicate with it.
+ * @throws BackingStoreException never thrown by this implementation
*/
@Override
public void flush() throws BackingStoreException {
@@ -273,13 +284,9 @@ public void flush() throws BackingStoreException {
}
/**
- * Implements the sync method as per the specification in {@link
- * java.util.prefs.Preferences#sync()}.
- *
- * sync() method.
+ * Calls {@code sync()} of the parent node, which does nothing.
*
- * @throws BackingStoreException if this operation cannot be completed due to a failure in the
- * backing store, or inability to communicate with it.
+ * @throws BackingStoreException never thrown by this implementation
*/
@Override
public void sync() throws BackingStoreException {
@@ -287,13 +294,13 @@ public void sync() throws BackingStoreException {
}
/**
- * Implements the getSpi method as per the specification in {@link
- * java.util.prefs.AbstractPreferences#getSpi(String)}.
+ * Returns the last value of an option, with variables resolved.
*
- * @return if the value associated with the specified key at this preference node, or null if
- * there is no association for this key, or the association cannot be determined at this
- * time.
- * @param key key to getvalue for
+ * @param key the option name
+ * @return the value, or {@code null} if the section has no such option
+ * @throws CircularReferenceException if the variables are nested deeper than {@link
+ * Config#getMaxResolveDepth()}; {@link java.util.prefs.Preferences#get(String, String)}
+ * catches it and returns the default value
*/
@Override
protected String getSpi(String key) {
@@ -301,14 +308,10 @@ protected String getSpi(String key) {
}
/**
- * Implements the childrenNamesSpi method as per the specification in {@link
- * java.util.prefs.AbstractPreferences#childrenNamesSpi()}.
+ * Returns the names of the child nodes, which are the direct sub-sections of the section.
*
- * childSpi method as per the specification in {@link
- * java.util.prefs.AbstractPreferences#childSpi(String)}.
+ * Returns the child node for a sub-section.
*
- * flushSpi method as per the specification in {@link
- * java.util.prefs.AbstractPreferences#flushSpi()}.
- *
- * keysSpi method as per the specification in {@link
- * java.util.prefs.AbstractPreferences#keysSpi()}.
+ * Returns the keys of the node.
*
- * @return an array of the keys that have an associated value in this preference node.
- * @throws BackingStoreException if this operation cannot be completed due to a failure in the
- * backing store, or inability to communicate with it.
+ * @return the option names of the section
+ * @throws BackingStoreException never thrown by this implementation
*/
@Override
protected String[] keysSpi() throws BackingStoreException {
@@ -365,11 +361,10 @@ protected String[] keysSpi() throws BackingStoreException {
}
/**
- * Implements the putSpi method as per the specification in {@link
- * java.util.prefs.AbstractPreferences#putSpi(String,String)}.
+ * Replaces the last value of an option, or adds the option.
*
- * @param key key to set value for
- * @param value new value of key
+ * @param key the option name
+ * @param value the new value
*/
@Override
protected void putSpi(String key, String value) {
@@ -377,11 +372,9 @@ protected void putSpi(String key, String value) {
}
/**
- * Implements the removeNodeSpi method as per the specification in {@link
- * java.util.prefs.AbstractPreferences#removeNodeSpi()}.
+ * Removes the sections that have the name of this node from the {@link Ini}.
*
- * @throws BackingStoreException if this operation cannot be completed due to a failure in the
- * backing store, or inability to communicate with it.
+ * @throws BackingStoreException never thrown by this implementation
*/
@Override
protected void removeNodeSpi() throws BackingStoreException {
@@ -389,10 +382,9 @@ protected void removeNodeSpi() throws BackingStoreException {
}
/**
- * Implements the removeSpi method as per the specification in {@link
- * java.util.prefs.AbstractPreferences#removeSpi(String)}.
+ * Removes all the values of an option.
*
- * @param key key to remove
+ * @param key the option name
*/
@Override
protected void removeSpi(String key) {
@@ -400,13 +392,9 @@ protected void removeSpi(String key) {
}
/**
- * Implements the syncSpi method as per the specification in {@link
- * java.util.prefs.AbstractPreferences#syncSpi()}.
- *
- * {@code
+ * System.setProperty("java.util.prefs.PreferencesFactory", "org.ini4j.IniPreferencesFactory");
+ * System.setProperty("org.ini4j.prefs.user", "file:/home/joe/app.ini");
+ *
+ * Preferences prefs = Preferences.userRoot().node("happy");
+ * }
+ *
+ * {@code
+ * Options opt = new Options(new File("dwarfs.opt"));
+ * String home = opt.get("homeDir");
+ *
+ * opt.put("age", 33);
+ * opt.store();
+ * }
+ *
+ * {@code
+ * Ini ini = new Ini(new File("dwarfs.ini"));
+ * int age = ini.get("happy", "age", int.class);
+ * String dir = ini.get("happy", "homeDir");
+ *
+ * ini.put("sleepy", "age", 55);
+ * ini.store();
+ * }
+ *
+ * @see Ini
+ * @see Registry
+ * @since 0.5.0
+ */
public interface Profile
extends MultiMap
+ *
+ *
+ * @param sectionName the section name
+ * @param optionName the option name
+ * @return the resolved value, or {@code null} if the section or the option is missing
+ * @throws CircularReferenceException if the variables are nested deeper than {@link
+ * Config#getMaxResolveDepth()}
+ */
String fetch(Object sectionName, Object optionName);
+ /**
+ * Returns the last value of an option, with variables resolved, converted to a type.
+ *
+ * @param
+ *
+ *
+ *
+ *
+ *
+ * {@code
+ * Ini ini = new Ini(new File("dwarfs.ini"));
+ * int age = ini.get("happy", "age", int.class);
+ *
+ * ini.put("happy", "age", age + 1);
+ * ini.store();
+ * }
+ *
+ *
+ *
+ */
+package org.ini4j;
diff --git a/src/main/java/org/ini4j/package.html b/src/main/java/org/ini4j/package.html
deleted file mode 100755
index 0b42f7f..0000000
--- a/src/main/java/org/ini4j/package.html
+++ /dev/null
@@ -1,32 +0,0 @@
-
-
-
-
-
- [ini4j] main package
-
+ *
+ *
+ * serviceId nev� system property
- * vizsg�lat�val kezd�dik. Amennyiben nincs ilyen property, �gy a keres�s a
- * /META-INF/services/serviceId nev� file tartalm�val folytat�dik. Amennyiben nincs
- * ilyen nev� file, �gy a param�terk�nt �tadott defaultService lesz az oszt�ly neve.
+ * [ini4j] service provider package
-