The Seedling configuration language is based on two pieces of standard Java technology, properties files and JavaBeans. We should have a quick overview here, but that's yet to be written, so you might want to check out these resources.

Seedling configuration files use the .properties format as specified by the documentation for java.util.Properties. The expression language inherits a few rough edges from that format:

Seedling leverages "bean properties" as defined by the JavaBeans specification. The most relevant part is the way property getter and setter methods are defined. The Tapestry documentation has a decent overview of how that works.

The expression language provides literals for these Java features:

Due to brain-damage in the standard Properties-file syntax, the escape-sequence for the double-quote is Pascal-style, not Java-style: two adjacent double-quote characters.

prop = "Here is a double-quote: ""\nGotta love Pascal."

The keyword null means the usual thing:

prop = null

Note that setting a property to null is different from not setting it at all. While the configuration above will cause invocation of setProp(null), one can explicitly avoid calling setProp() altogether by declaring an empty expression:

prop =
# There's no text in the property value above

Such empty configuration is interpreted to mean “there’s no configuration for this property”. That can be useful to override config from another module.

Identifiers follow Java syntax. In most cases, an identifier will reference a sibling node of the node being configured, as opposed to referencing a property of the current node.

# file: config/branch/Node1

otherNode = Node2
# Configures branch/Node1.otherNode to refer to branch/Node2

When two or more identifiers are connected by a slash character, they form a path to another node in the Seedling hierarchy. These paths are interpreted relative to the branch containing the current node.

# file: config/branch/Node1

otherNode = childBranch/Node2
# Configures branch/Node1.otherNode to refer to branch/childBranch/Node2

Instances of java.util.ArrayList can be created by using square brackets around a comma-separated sequence of expressions. The evaluator will automatically convert between lists and arrays when necessary and possible.

prop = [ 1, 2, 3 ]

Such configuration will work with any of the following setters:

Strings, arrays, and Lists can be concatenated using the + operator:

url = "http://" + this.host + "/"
statusCodes = /some/Node.errorCodes + [ 2234 ] + OtherNode.codes

If the left side is a string (any CharSequence will do), then the right side is converted toString() before concatenation.

Similarly, integers can be added:

port = 80 + this.portOffset
portOffset = 2

In either case, if one side of the operator is null, the result is the other side. If both sides are null, the result is null.

The expression language can denote method invocation using Java-like syntax. Methods can be invoked on a specific class, in which case the named method must be static, or on another node, in which case the method may be either static or dynamic. Here are some examples.

# Invoke a static method on a fully-qualified class.
prop = some.package.Class.staticMethod(12)

# Invoke a static or dynamic method on a node.
prop = some/branch/Node.method("hello")

# Ambiguous case resolved by looking for node first, then class.
prop = NodeOrUnpackagedClass.method()

	Note
	Static method invocation currently requires fully-qualified class names.

Method calls can be nested and chained:

prop = Node1.method1(Node2.method2()).method3(siblingNode)

Methods declared to “return” void can be called as expected, with the effective result of null.

As a special case of method invocation, sparkly new Java objects can be constructed using the keyword new and a fully-qualified class name.

prop = new com.eg.Something(12, "hi")

In all cases, Seedling will respect declared access restrictions by only invoking public methods.

So far we've talked about writing expressions that configure individual properties of a node, but we've not shown how to create the node itself! The value of the current node is declared using the metaproperty .this along with an arbitrary expression.

In most cases the .this expression will be a normal constructor call:

.this = new com.eg.Bean(12, true)

.this = new java.lang.String("A node can be any object.")

More advanced cases leverage method invocation; such methods we herein call factory methods. Factory methods can be static or dynamic, just like any method call.

# Invoke a static factory method on a fully-qualified class.
.this = some.user.Class.staticFactoryMethod(...)

# Invoke a static or dynamic factory method on a node.
.this = some/branch/Factory.makeInstance(...)

# Ambiguous case resolved by looking for class first, then node.
.this = NodeOrUnpackagedClass.factoryMethod(...)

We mentioned before that an empty property expression means “there’s no configuration”, and that goes for .this too:

.this =
# There's no expression, so the node won't be created.

That means you can override a creation expression to completely disable node provisioning. Such configuration is almost equivalent to there being no configuration at all! This can be handy when you're using a module that declares a particular node, but you want to ensure that the node won't be created. (Of course, your empty creation expression could itself be overriden by another configuration layer...)

Another way to end up with a nonexistent node is to have a .this expression that evaluates to null, either literally or as the result of a method invocation.

Important

The container will assume that the value of the .this expression is not installed elsewhere in the tree, and will perform all of the usual lifecycle operations on it. Violation of this expectation could result in strange behavior, especially if the object uses a callback interface like ServiceNode. If you need the same object to appear in more than one location, be sure to use an alias instead of a creation expression that returns the same object.

An expression can reference properties on the current node by using Java's “this dot” member reference notation:

prop1 = "hello"
prop2 = this.prop1
prop3 = node.method(this.prop2)

When such notation is used within a .this = new constructor expression, the named property will not undergo property injection. The evaluator assumes that the property utilizes constructor injection and won't inject it a second time. For nodes with many constructor parameters, this idiom can increase the readability of the configuration file by making the parameter/property association explicit.

.this = new com.eg.MyList(this.initialSize, this.expandable)
initialSize = 12
expandable = true

Despite the fact that no setters will be invoked for property injection, Seedling still needs to be able to discover the type of the properties. This implies that MyList exposes a property called initialSize, meaning it has a getter getInitialSize() and/or a setter setInitialSize(...). (And the same goes for expandable.)

Factory method invocations cannot use this-property names as parameters. That's because the concrete type of such node is not known until after the factory method returns, so the evaluator can't determine what properties are on the node until its too late to reference them.

# This will cause an error:
.this = path/to/MyFactory.makeNode(this.prop)

Property assignments fully replace any expressions declared in super-configuration. This is normal overriding of inherited configuration. But there are times when the subconfiguration needs to extend or otherwise modify the inherited value rather than replacing it. In the Seedling expression language, the super keyword means something like “the value of the current property were it not being overridden here”. It's much like the meaning of the keyword in Java itself when invoking a method as implemented in a superclass.

For example, consider a node that has a property ports of type int[] and a base configuration file declaring:

# superconfig
ports = [ 80 ]

A subconfig file (usually found in a higher-priority module) can extend the array as follows:

# subconfig
ports = super + [8080, 8081]
# The resulting configured value is [80, 8080, 8081]

The super keyword is not yet supported in all contexts in which it could be useful, for example:

# Not supported!
prop = node.method(super)

Classes are mostly first-class in the config language: for most expressions where Java requires a class literal, Seedling can handle an arbitrary expression evaluating to a Class instance.

Values can be coerced to a specific type via the usual Java notation. This can be particularly useful for disambiguating among overridden methods. Here's a ridiculous example:

# Disambiguate between Exception(String) and Exception(Thowable)
.this = new java.lang.Exception( (java.lang.String) null )

Note that Seedling currently requires all class names to be fully-qualified.