Merge branch 'develop'

Author: Craigacp

.github/workflows/maven.yml

@@ -16,7 +16,7 @@ jobs:
     strategy:
       matrix:
         # test against supported LTS versions and latest
-        java: [ 8, 11, 15 ]
+        java: [ 8, 11, 16 ]
     name: OLCUT - OpenJDK ${{ matrix.java }}
     steps:
       - uses: actions/checkout@v2

README.md

@@ -23,12 +23,12 @@ Maven:
 <dependency>
     <groupId>com.oracle.labs.olcut</groupId>
     <artifactId>olcut-core</artifactId>
-    <version>5.1.5</version>
+    <version>5.1.6</version>
 </dependency>
 ```
 or from Gradle:
 ```groovy
-implementation 'com.oracle.labs.olcut:olcut-core:5.1.5'
+implementation 'com.oracle.labs.olcut:olcut-core:5.1.6'
 ```
 
 The `olcut-extras` artifact is designed as a small tool for developers, as such you should compile the appropriate 

THIRD_PARTY_LICENSES.txt

@@ -1,4 +1,4 @@
-jline 3.16.0
+jline 3.19.0
 
 Copyright (c) 2002-2018, the original author or authors.
 All rights reserved.
@@ -35,7 +35,7 @@ LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
 IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 OF THE POSSIBILITY OF SUCH DAMAGE.
 
-jackson-core, jackson-databind 2.11.3
+jackson-core, jackson-databind 2.12.2
 
 
                                  Apache License
@@ -240,7 +240,7 @@ jackson-core, jackson-databind 2.11.3
    See the License for the specific language governing permissions and
    limitations under the License.
 
-junit 5.7.0
+junit 5.7.1
 
 Copyright 2015-2020 the original author or authors.
 

olcut-config-edn/pom.xml

@@ -35,7 +35,7 @@
         <groupId>com.oracle.labs.olcut</groupId>
         <artifactId>olcut</artifactId>
         <version>${revision}</version>
-        <relativePath>..</relativePath>
+        <relativePath>../pom.xml</relativePath>
     </parent>
 
     <name>olcut-config-edn</name>

olcut-config-json/pom.xml

@@ -33,7 +33,7 @@
         <groupId>com.oracle.labs.olcut</groupId>
         <artifactId>olcut</artifactId>
         <version>${revision}</version>
-        <relativePath>..</relativePath>
+        <relativePath>../pom.xml</relativePath>
     </parent>
     <name>olcut-config-json</name>
     <artifactId>olcut-config-json</artifactId>

olcut-core/pom.xml

@@ -33,7 +33,7 @@
         <groupId>com.oracle.labs.olcut</groupId>
         <artifactId>olcut</artifactId>
         <version>${revision}</version>
-        <relativePath>..</relativePath>
+        <relativePath>../pom.xml</relativePath>
     </parent>
     <name>olcut-core</name>
     <artifactId>olcut-core</artifactId>

olcut-core/src/main/java/com/oracle/labs/mlrg/olcut/config/ConfigurationManager.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2004-2020, Oracle and/or its affiliates.
+ * Copyright (c) 2004-2021, Oracle and/or its affiliates.
  *
  * Licensed under the 2-clause BSD license.
  *
@@ -83,6 +83,7 @@
 import java.util.logging.Logger;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
+import java.util.stream.Collectors;
 
 import static com.oracle.labs.mlrg.olcut.config.PropertySheet.StoredFieldType;
 
@@ -1421,6 +1422,50 @@ public <T extends Configurable> T lookup(Class<T> c, ComponentListener<T> cl) {
         return comps.get(0);
     }
 
+    /**
+     * Looks up all the components of a given type, returning a map of them.
+     * <p>
+     * If the class is an interface, it returns all the configurables which implement that interface,
+     * if it's a concrete class then it returns only those configurables which are exactly that class.
+     * @param c The class of component to lookup.
+     * @param <T> The type of the component.
+     * @return A map containing all instances of the desired class this configuration manager knows about.
+     */
+    @SuppressWarnings("unchecked") // Casts to T are implicitly checked as we use Class<T> to find the names.
+    public <T extends Configurable> Map<String, T> lookupAllMap(Class<T> c) {
+        Map<String, T> ret = new HashMap<>();
+
+        //
+        // If the class isn't an interface, then lookup each of the names
+        // in the raw property data with the given class
+        // name, ignoring those things marked as importable.
+        if(!c.isInterface()) {
+            String className = c.getName();
+            for (Map.Entry<String, ConfigurationData> e : configurationDataMap.entrySet()) {
+                if (e.getValue().getClassName().equals(className) &&
+                        !e.getValue().isImportable()) {
+                    ret.put(e.getKey(),(T)lookup(e.getKey()));
+                }
+            }
+        } else {
+            //
+            // If we have an interface and no registry, lookup all the
+            // implementing classes and return them.
+            for (Map.Entry<String, ConfigurationData> e : configurationDataMap.entrySet()) {
+                try {
+                    Class clazz = Class.forName(e.getValue().getClassName());
+                    if (!e.getValue().isImportable() && c.isAssignableFrom(clazz) && !clazz.isInterface()) {
+                        ret.put(e.getKey(),(T)innerLookup(e.getKey(),null,true));
+                    }
+                } catch (ClassNotFoundException ex) {
+                    throw new PropertyException(ex,e.getKey(),"Class not found for component " + e.getKey());
+                }
+            }
+        }
+
+        return ret;
+    }
+
     /**
      * Looks up all the components of a given type, returning a list of them.
      * @param c The class of component to lookup.
@@ -1474,6 +1519,66 @@ public <T extends Configurable> List<T> lookupAll(Class<T> c, ComponentListener<
         return lookupAll(c);
     }
 
+    /**
+     * Looks for a single instance of a specified Configurable in the configuration. If there is
+     * no such instance, this method returns null. If there is more than one instance, an
+     * exception is thrown. lookupSingleton can optionally include any class that may be
+     * assignable (a subclass or implementation) to the provided type. Note that this
+     * could potentially allow a user to load their own class. If the security of the
+     * class you're looking up is important, declare it final to prevent code insertion.
+     *
+     * @param c The Class of component to lookup.
+     * @param allowAssignable allow types that are assignable to the given class to match
+     * @param <T> The type of the component.
+     * @return the one instance of the desired class this configuration manager knows about or null if
+     *         no such instance is present
+     * @throws PropertyException if there is more than one instance
+     */
+    @SuppressWarnings("unchecked") // Casts to T are implicitly checked as we use Class<T> to find the names.
+    public <T extends Configurable> T lookupSingleton(Class<T> c, boolean allowAssignable) throws PropertyException {
+
+        List<String> instanceNames = new ArrayList<>();
+        for(Map.Entry<String, ConfigurationData> e : configurationDataMap.entrySet()) {
+            ConfigurationData rpd = e.getValue();
+            try {
+                Class pclass = Class.forName(rpd.getClassName());
+                if (!rpd.isImportable() &&
+                        ((allowAssignable && c.isAssignableFrom(pclass)) ||
+                         (!allowAssignable && rpd.getClassName().equals(c.getName())))) {
+                    instanceNames.add(e.getKey());
+                }
+            } catch(ClassNotFoundException ex) {
+                logger.warning(String.format("No class %s found in ConfigurationManager",
+                        rpd.getClassName()));
+            }
+        }
+
+        //
+        // Check that we got only one instance and that it is not an interface.
+        if (instanceNames.isEmpty()) {
+            return null;
+        }
+        if (instanceNames.size() > 1) {
+            String names = instanceNames.stream().collect(Collectors.joining(", "));
+            throw new PropertyException("", "Multiple instances of " + c.getName() + " found in configuration: " + names);
+        }
+
+        String matchedName = instanceNames.get(0);
+        ConfigurationData cd = configurationDataMap.get(matchedName);
+        try {
+            Class matchedClass = Class.forName(cd.getClassName());
+            if (!matchedClass.isInterface()) {
+                return (T)lookup(matchedName);
+            } else {
+                throw new PropertyException("matchedName", "Cannot instantiate component with type "
+                        + matchedClass + " since it is an interface");
+            }
+        } catch (ClassNotFoundException e) {
+            throw new PropertyException(e,matchedName,"Class not found for component " + matchedName);
+        }
+    }
+
+
     /**
      * Gets a list of all of the component names of the components that have 
      * a given type.  This will not instantiate the components.

olcut-core/src/main/java/com/oracle/labs/mlrg/olcut/config/DescribeConfigurable.java

@@ -203,7 +203,7 @@ public static TreeMap<String,FieldInfo> generateFieldInfo(Class<? extends Config
                                 Object[] constants = listType.getEnumConstants();
                                 List<String> enumConstants = new ArrayList<>();
                                 for (Object o : constants) {
-                                    enumConstants.add(((Enum)o).name());
+                                    enumConstants.add(((Enum<?>)o).name());
                                 }
                                 fi = new FieldInfo(f.getName(),f.getType().getName(),f,configAnnotation,defaultVal,listType.getCanonicalName(),enumConstants);
                             } else {

olcut-core/src/main/java/com/oracle/labs/mlrg/olcut/config/Options.java

@@ -34,12 +34,15 @@
 import java.lang.reflect.Field;
 import java.lang.reflect.InvocationTargetException;
 import java.lang.reflect.Modifier;
+import java.lang.reflect.ParameterizedType;
+import java.lang.reflect.Type;
 import java.security.AccessController;
 import java.security.PrivilegedAction;
 import java.util.ArrayDeque;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Collections;
+import java.util.EnumSet;
 import java.util.HashMap;
 import java.util.HashSet;
 import java.util.LinkedHashMap;
@@ -77,6 +80,11 @@ default public String getOptionsDescription() {
         return "";
     }
 
+    /**
+     * Constructs a formatted usage string from a table of fields.
+     * @param usageList The fields.
+     * @return A usage string.
+     */
     public static String formatUsage(List<List<String>> usageList) {
         int[] maxWidth = new int[5];
 
@@ -118,6 +126,11 @@ public static String formatUsage(List<List<String>> usageList) {
         return builder.toString();
     }
 
+    /**
+     * Constructs the usage string from the supplied Options subclass.
+     * @param options The options to construct a usage for.
+     * @return The usage string.
+     */
     public static List<List<String>> getUsage(Class<? extends Options> options) {
         ArrayList<List<String>> list = new ArrayList<>();
         ArrayList<List<String>> optionsList = new ArrayList<>();
@@ -175,28 +188,70 @@ public static List<List<String>> getUsage(Class<? extends Options> options) {
         }
     }
 
+    /**
+     * Returns a String representing the Enum constants from this class surrounded by '{', '}'
+     * and separated by a comma and a space.
+     * @param enumClazz The enum class to represent.
+     * @return A String containing all the enum constants.
+     */
+    public static String getEnumConstantString(Class<? extends Enum<?>> enumClazz) {
+        Enum<?>[] constants = enumClazz.getEnumConstants();
+        StringBuilder sb = new StringBuilder();
+        sb.append('{');
+        for (Enum<?> o : constants) {
+            sb.append(o.name());
+            sb.append(", ");
+        }
+        sb.replace(sb.length() - 2, sb.length(), "}");
+        return sb.toString();
+    }
+
     public static String generateTypeDescription(Field f) {
         Class<?> clazz = f.getType();
         if (clazz.isEnum()) {
-            Object[] constants = clazz.getEnumConstants();
-            StringBuilder sb = new StringBuilder();
-            sb.append("enum - {");
-            for (Object o : constants) {
-                sb.append(((Enum)o).name());
-                sb.append(", ");
+            @SuppressWarnings("unchecked") //guarded by isEnum check
+            Class<? extends Enum<?>> enumClazz = (Class<? extends Enum<?>>) clazz;
+            return "enum - " + getEnumConstantString(enumClazz);
+        } else if (clazz == EnumSet.class) {
+            Type type = f.getGenericType();
+            if (type instanceof ParameterizedType) {
+                ParameterizedType typeName = (ParameterizedType) type;
+                // Should only have a single type parameter
+                Type enumType = typeName.getActualTypeArguments()[0];
+                try {
+                    @SuppressWarnings("unchecked") // type parameter to an enumset must be an enum
+                    Class<? extends Enum<?>> enumClazz = (Class<? extends Enum<?>>) Class.forName(enumType.getTypeName());
+                    return "EnumSet - " + getEnumConstantString(enumClazz);
+                } catch (ClassNotFoundException e) {
+                    Logger.getLogger(Options.class.getName()).warning("Failed to load enum class '" + enumType.getTypeName() + "'");
+                    return typeName.getTypeName();
+                }
+            } else {
+                return f.getGenericType().getTypeName();
             }
-            sb.replace(sb.length()-2,sb.length(),"}");
-            return sb.toString();
         } else {
             return f.getGenericType().getTypeName();
         }
     }
 
+    /**
+     * Gets the fields for this option's usage string.
+     * @param option The option annotation.
+     * @param f The annotated field.
+     * @param obj The parent options object, used to access the default value for this field.
+     * @return The fields for the usage string.
+     */
     public static ArrayList<String> getOptionUsage(Option option, Field f, Options obj) {
         String typeString = generateTypeDescription(f);
         return getOptionUsage(option,f,obj,typeString);
     }
 
+    /**
+     * Gets the usage for one of the default options (which don't have a parent options object).
+     * @param option The option annotation.
+     * @param type The type of the option.
+     * @return The fields for the usage string.
+     */
     public static ArrayList<String> getOptionUsage(Option option, String type) {
         ArrayList<String> output = new ArrayList<>();
         if (option.charName() != Option.EMPTY_CHAR) {
@@ -211,6 +266,14 @@ public static ArrayList<String> getOptionUsage(Option option, String type) {
         return output;
     }
 
+    /**
+     * Gets the usage fields for the supplied option.
+     * @param option The option annotation.
+     * @param f The field the annotation is attached to.
+     * @param obj The parent options object, used to access the default value for this field.
+     * @param type The type string used in the usage (may be the enum constants, or a short type descriptor).
+     * @return The fields for the usage string.
+     */
     public static ArrayList<String> getOptionUsage(Option option, Field f, Options obj, String type) {
         ArrayList<String> output = new ArrayList<>();
         if (option.charName() != Option.EMPTY_CHAR) {