Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
4 changes: 2 additions & 2 deletions pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -150,8 +150,8 @@
<goal>jar</goal>
</goals>
<configuration>
<failOnError>false</failOnError>
<doclint>none</doclint>
<failOnError>true</failOnError>
<doclint>all,-missing</doclint>
</configuration>
</execution>
</executions>
Expand Down
96 changes: 96 additions & 0 deletions src/main/java/org/ini4j/BasicMultiMap.java
Original file line number Diff line number Diff line change
Expand Up @@ -25,14 +25,49 @@
import java.util.Set;
import org.ini4j.spi.Warnings;

/**
* A {@link MultiMap} that keeps the values of each key in a list.
*
* <p>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}.
*
* <p>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.
*
* <p><strong>Thread safety.</strong> 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 <K> the type of the keys
* @param <V> the type of the values
* @see CommonMultiMap
* @since 0.5.0
*/
public class BasicMultiMap<K, V> implements MultiMap<K, V>, Serializable {
private static final long serialVersionUID = 4716749660560043989L;
private final Map<K, List<V>> _impl;

/** Creates an empty map that keeps its keys in insertion order. */
public BasicMultiMap() {
this(new LinkedHashMap<K, List<V>>());
}

/**
* Creates a map on top of an underlying map.
*
* <p>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<K, List<V>> impl) {
_impl = impl;
Expand Down Expand Up @@ -83,6 +118,15 @@ public boolean containsValue(Object value) {
return ret;
}

/**
* Returns the entries of this map, one for each key.
*
* <p>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<Entry<K, V>> entrySet() {
Set<Entry<K, V>> ret = new HashSet<Entry<K, V>>();
Expand All @@ -108,6 +152,14 @@ public V get(Object key, int index) {
return (values == null) ? null : values.get(index);
}

/**
* Returns the keys of the underlying map.
*
* <p>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<K> keySet() {
return _impl.keySet();
Expand Down Expand Up @@ -139,6 +191,15 @@ public V put(K key, V value, int index) {
return getList(key, false).set(index, value);
}

/**
* Copies the entries of another map.
*
* <p>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) {
Expand All @@ -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.
*
* <p>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<V> putAll(K key, List<V> values) {
List<V> ret = _impl.get(key);
Expand All @@ -164,6 +236,12 @@ public List<V> putAll(K key, List<V> values) {
return ret;
}

/**
* Removes all the values of a key.
*
* @param key the key
* @return the first value the key had, or {@code null} if the key was not in the map
*/
@Override
public V remove(Object key) {
List<V> prev = _impl.remove(key);
Expand All @@ -186,16 +264,34 @@ public V remove(Object key, int index) {
return ret;
}

/**
* Returns the number of keys.
*
* @return the number of keys, not the number of values
*/
@Override
public int size() {
return _impl.size();
}

/**
* Returns the text form of the underlying map, for example {@code {a=[1, 2], b=[3]}}.
*
* @return the text form
*/
@Override
public String toString() {
return _impl.toString();
}

/**
* Returns all the values of all the keys.
*
* <p>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<V> values() {
List<V> all = new ArrayList<V>(_impl.size());
Expand Down
65 changes: 64 additions & 1 deletion src/main/java/org/ini4j/BasicOptionMap.java
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,25 @@
import org.ini4j.spi.BeanTool;
import org.ini4j.spi.Warnings;

/**
* The default implementation of {@link OptionMap}.
*
* <p>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.
*
* <p>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.
*
* <p>The thread safety of {@link BasicMultiMap} applies.
*
* @see Options
* @see Profile.Section
* @since 0.5.0
*/
public class BasicOptionMap extends CommonMultiMap<String, String> implements OptionMap {
private static final char SUBST_CHAR = '$';
private static final String SYSTEM_PROPERTY_PREFIX = "@prop/";
Expand All @@ -36,10 +55,21 @@ public class BasicOptionMap extends CommonMultiMap<String, String> implements Op
private transient BeanAccess _defaultBeanAccess;
private final boolean _propertyFirstUpper;

/**
* Creates an empty option map.
*
* <p>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;
}
Expand Down Expand Up @@ -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.
*
* <p>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);

Expand Down Expand Up @@ -253,6 +303,19 @@ void resolve(StringBuilder buffer) {
resolve(buffer, 0);
}

/**
* Replaces the variables in a buffer with their values.
*
* <p>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());
Expand All @@ -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 {
Expand Down
47 changes: 46 additions & 1 deletion src/main/java/org/ini4j/BasicProfile.java
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,27 @@
import org.ini4j.spi.BeanTool;
import org.ini4j.spi.IniHandler;

/**
* The default implementation of {@link Profile}.
*
* <p>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)}).
*
* <p>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.
*
* <p>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.
*
* <p>The thread safety of {@link BasicMultiMap} applies.
*
* @see Ini
* @see BasicRegistry
* @since 0.5.0
*/
public class BasicProfile extends CommonMultiMap<String, Profile.Section> implements Profile {
private static final String SECTION_SYSTEM_PROPERTIES = "@prop";
private static final String SECTION_ENVIRONMENT = "@env";
Expand All @@ -38,10 +59,19 @@ public class BasicProfile extends CommonMultiMap<String, Profile.Section> implem
private final boolean _propertyFirstUpper;
private final boolean _treeMode;

/** Creates an empty profile that is not in tree mode and uses bean property names as they are. */
public BasicProfile() {
this(false, false);
}

/**
* Creates an empty profile.
*
* @param treeMode if {@code true}, {@link #add(String)} also adds the missing parent sections of
* a new section
* @param propertyFirstUpper if {@code true}, the first letter of a bean property name is changed
* to upper case to get the section name (see {@link #as(Class)})
*/
public BasicProfile(boolean treeMode, boolean propertyFirstUpper) {
_treeMode = treeMode;
_propertyFirstUpper = propertyFirstUpper;
Expand Down Expand Up @@ -166,6 +196,21 @@ void resolve(StringBuilder buffer, Section owner) {
resolve(buffer, owner, 0);
}

/**
* Replaces the variables in a buffer with their values.
*
* <p>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());
Expand All @@ -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 {
Expand Down
10 changes: 10 additions & 0 deletions src/main/java/org/ini4j/BasicRegistry.java
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,20 @@
import org.ini4j.spi.RegEscapeTool;
import org.ini4j.spi.TypeValuesPair;

/**
* The default implementation of {@link Registry}.
*
* <p>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;
}
Expand Down
Loading
Loading