feat(settings): add simple String vararg lookups in JvmSettings IQSS#…

…7000

To ease lookup when target variable is a String, the convenient lookup()
and lookupOptional() have been added for placeholder-type settings,
too.

Adds JavaDocs for all the varargs lookup functions, too, easing usage in code.

src/main/java/edu/harvard/iq/dataverse/settings/JvmSettings.java

@@ -224,10 +224,13 @@ public Optional<String> lookupOptional() {
 
  /**
  * Lookup this setting via MicroProfile Config as a required option (it will fail if not present).
- * @throws java.util.NoSuchElementException - if the property is not defined or is defined as an empty string
+ *
  * @param klass The target type class to convert the setting to if found and not null
  * @return The setting as an instance of {@link T}
  * @param <T> Target type to convert the setting to (you can create custom converters)
+ *
+ * @throws java.util.NoSuchElementException When the property is not defined or is defined as an empty string.
+ * @throws IllegalArgumentException When the settings value could not be converted to target type.
  */
  public <T> T lookup(Class<T> klass) {
  if (needsVarArgs()) {
@@ -242,9 +245,12 @@ public <T> T lookup(Class<T> klass) {
 
  /**
  * Lookup this setting via MicroProfile Config as an optional setting.
+ *
  * @param klass The target type class to convert the setting to if found and not null
- * @return The setting as an instance of {@link Optional<T>} or an empty Optional
  * @param <T> Target type to convert the setting to (you can create custom converters)
+ * @return The setting as an instance of {@link Optional<T>} or an empty Optional
+ *
+ * @throws IllegalArgumentException When the settings value could not be converted to target type.
  */
  public <T> Optional<T> lookupOptional(Class<T> klass) {
  if (needsVarArgs()) {
@@ -257,6 +263,49 @@ public <T> Optional<T> lookupOptional(Class<T> klass) {
  return ConfigProvider.getConfig().getOptionalValue(this.getScopedKey(), klass);
  }
 
+ /**
+ * Lookup a required setting containing placeholders for arguments like a name and return as plain String.
+ * To use type conversion, use {@link #lookup(Class, String...)}.
+ *
+ * @param arguments The var args to replace the placeholders of this setting.
+ * @return The value of the setting.
+ *
+ * @throws java.util.NoSuchElementException When the setting has not been set in any MPCONFIG source or is an empty string.
+ * @throws IllegalArgumentException When using it on a setting without placeholders.
+ * @throws IllegalArgumentException When not providing as many arguments as there are placeholders.
+ */
+ public String lookup(String... arguments) {
+ return lookup(String.class, arguments);
+ }
+
+ /**
+ * Lookup an optional setting containing placeholders for arguments like a name and return as plain String.
+ * To use type conversion, use {@link #lookupOptional(Class, String...)}.
+ *
+ * @param arguments The var args to replace the placeholders of this setting.
+ * @return The value as an instance of {@link Optional<String>} or an empty Optional
+ *
+ * @throws IllegalArgumentException When using it on a setting without placeholders.
+ * @throws IllegalArgumentException When not providing as many arguments as there are placeholders.
+ */
+ public Optional<String> lookupOptional(String... arguments) {
+ return lookupOptional(String.class, arguments);
+ }
+
+ /**
+ * Lookup a required setting containing placeholders for arguments like a name and return as converted type.
+ * To avoid type conversion, use {@link #lookup(String...)}.
+ *
+ * @param klass The target type class.
+ * @param arguments The var args to replace the placeholders of this setting.
+ * @param <T> Target type to convert the setting to (you can create custom converters)
+ * @return The value of the setting, converted to the given type.
+ *
+ * @throws java.util.NoSuchElementException When the setting has not been set in any MPCONFIG source or is an empty string.
+ * @throws IllegalArgumentException When using it on a setting without placeholders.
+ * @throws IllegalArgumentException When not providing as many arguments as there are placeholders.
+ * @throws IllegalArgumentException When the settings value could not be converted to the target type.
+ */
  public <T> T lookup(Class<T> klass, String... arguments) {
  if (needsVarArgs()) {
  if (arguments == null || arguments.length != placeholders) {
@@ -267,6 +316,19 @@ public <T> T lookup(Class<T> klass, String... arguments) {
  throw new IllegalArgumentException("Cannot lookup a setting without variable arguments with this method.");
  }
 
+ /**
+ * Lookup an optional setting containing placeholders for arguments like a name and return as converted type.
+ * To avoid type conversion, use {@link #lookupOptional(String...)}.
+ *
+ * @param klass The target type class.
+ * @param arguments The var args to replace the placeholders of this setting.
+ * @param <T> Target type to convert the setting to (you can create custom converters)
+ * @return The value as an instance of {@link Optional<T>} or an empty Optional
+ *
+ * @throws IllegalArgumentException When using it on a setting without placeholders.
+ * @throws IllegalArgumentException When not providing as many arguments as there are placeholders.
+ * @throws IllegalArgumentException When the settings value could not be converted to the target type.
+ */
  public <T> Optional<T> lookupOptional(Class<T> klass, String... arguments) {
  if (needsVarArgs()) {
  if (arguments == null || arguments.length != placeholders) {
@@ -277,6 +339,12 @@ public <T> Optional<T> lookupOptional(Class<T> klass, String... arguments) {
  throw new IllegalArgumentException("Cannot lookup a setting without variable arguments with this method.");
  }
 
+ /**
+ * Inject arguments into the placeholders of this setting. Will not do anything when no placeholders present.
+ *
+ * @param arguments The variable arguments to be inserted for the placeholders.
+ * @return The formatted setting name.
+ */
  public String insert(String... arguments) {
  return String.format(this.getScopedKey(), (Object[]) arguments);
  }