Fork me on GitHub
Built by Maven

Overview

The Plexus Component Configurator API allows to configure components from a tree data structure (PlexusConfiguration objects) of String values. It is in most cases created from XML. The most popular use case of this API is Configuration of Maven Mojos.

For each configuration element the class/type is being determined (from the object to be configured) and then the String value converted accordingly. For each class/type the rules for conversions are outlined below.

Basic (Value) Objects

For conversion to primitive types their according wrapper classes are used and automatically unboxed.

Class Conversion from String Since
Boolean Boolean.valueOf(String)
Byte Byte.decode(String)
Character Character.valueOf(char) of the first character in the given string
Class Class.forName(String). This conversion is not enabled by default.
java.util.Date SimpleDateFormat.parse(String) for the following patterns: yyyy-MM-dd hh:mm:ss.S a, yyyy-MM-dd hh:mm:ssa, yyyy-MM-dd HH:mm:ss.S or yyyy-MM-dd HH:mm:ss
Double Double.valueOf(String)
Enum Enum.valueOf(String)
java.io.File new File(String) with the file separators normalized to File.separatorChar. In case the file is relative, it is made absolute by calling the given ExpressionEvaluator's alignToBaseDirectory(File) method.
Float Float.valueOf(String)
Integer Integer.decode(String)
Long Long.decode(String)
Short Short.decode(String)
String n/a
StringBuffer new StringBuffer(String)
StringBuilder new StringBuilder(String)
java.net.URI new URI(String)
java.net.URL new URL(String)
org.codehaus.plexus.configuration.PlexusConfiguration the given PlexusConfiguration is passed as is (no conversion)
java.nio.file.Path same as java.io.File converted via toPath() 0.0.9.M3
java.time.temporal.Temporal created from via DateTimeFormatter.parse(String) supporting same patterns as java.util.Date. Supports the following Temporal classes: LocalDate, LocalDateTime, LocalTime, Instant, OffsetDateTime, OffsetTime and ZonedDateTime 0.0.9.M3
* only used as last resort, try class's constructor taking a single String value 0.0.9.M3

Composite Objects

Collection Objects

The collection's implementation class is in most cases determined automatically according to the following table

Default Collection Class Used for
TreeSet all types assignable to SortedSet
HashSet all types assignable to Set
ArrayList every other Collection type which is not a Map
Properties all types assignable to Properties
TreeMap all types assignable to Map but not Properties
?[] all array types

In order to use a different class, one can leverage the attribute implementation which is supposed to contain the fully qualified class name.

The item type of the collection is in most cases determined automatically (from the parameterized type) but it can be overwritten:

  1. If the first item element contains an implementation attribute, try to load the class with the given fully qualified class name from the attribute value
  2. If the first item element name contains a ., try to load the class with the fully qualified class name given in the element name
  3. Try the first item element name (with capitalized first letter) as a class in the same package as the mojo/object being configured

The value is either given in child leaf element values (the name does not matter) or for arrays and non-Map collection types as String value in the collection element itself (where comma is used as separator between the individual item values). For Maps the the configuration element's name is used as key, while the configuration element's value is used as value.

Complex Objects

All other classes try to inject each leaf element individually. For that the following lookup order is used

  1. method set<name>
  2. method add<name>
  3. field name

The first found method/field is used to set the value via reflection (via method call or field setter).