deephacks

Tools4j-config 0.0.1 was released in Maven Central Repository about a week ago, a framework that aims to support creating configurable applications in a productive and consistent way.

This is a quick introduction on the possibilities for defining configuration and constraints, and how to administrate it for applications.

Prerequisites
Tools4j-config is fully functional in any Java SE 6+ compatible environment and is distributed as a set of Maven 3+ projects.

Quickstart
First we’ll define configuration used by our application. Create a maven project with the following dependencies.

<dependency>
   <groupId>org.deephacks.tools4j</groupId>
   <artifactId>config-api-runtime</artifactId>
   <version>0.0.1</version>
   <scope>compile</scope>
</dependency>
<dependency>
   <groupId>org.deephacks.tools4j</groupId>
   <artifactId>config-core</artifactId>
   <version>0.0.1</version>
   <scope>runtime</scope>
</dependency>

Let’s assume we need access to a database, so we create a class that will represent the configuration needed to connect to it.

@Config(desc = "User database.")
public class Database {
    @Id(desc = "Identification of database.")
    private String id;
    @Config(desc = "Address for connecting to database.")
    private URL url;
    // username with default value 'test'
    @Config(desc = "Username for connecting to database.")
    private String username = "test";
    // password with default value 'test'
    @Config(desc = "Password for connecting to database.")
    private String password = "test";
    @Config(desc = "Database connections in pool.")
    private Integer poolSize;
}

Now register this class with the framework and read its configuration.

RuntimeContext runtime = Lookup.get().lookup(RuntimeContext.class);
runtime.register(Database.class);
List<Database> tests = runtime.all(Database.class);

Done! Our application is now configurable. Pretty quick and simple.

But what did we read? Nothing actually. The list is empty since there is no configuration available yet. We need the administrator to provision configuration first. So let’s take the administrator perspective for a second.

Create a new maven project with the following dependencies.

<dependency>
   <groupId>org.deephacks.tools4j</groupId>
   <artifactId>config-api-admin</artifactId>
   <version>0.0.1</version>
   <scope>compile</scope>
</dependency>
<dependency>
   <groupId>org.deephacks.tools4j</groupId>
   <artifactId>config-core</artifactId>
   <version>0.0.1</version>
   <scope>runtime</scope>
</dependency>

Configuration is managed programmatically and this is how our imaginary administrator creates a database named user and sets values for it.

AdminContext admin = Lookup.get().lookup(AdminContext.class);
Bean bean = Bean.create(BeanId.create("user", Database.class.getName()));
bean.addProperty("url", "/dev/null");
bean.addProperty("username", "admin");
bean.addProperty("password", "admin123");
bean.addProperty("poolSize", "nonsense");
admin.create(bean);

Bean Database@user have a property java.net.URL@url with value /dev/null not matching its type.
Bean Database@user have a property java.lang.Integer@poolSize with value nonsense not matching its type.

These failures should be obvious. The administrator provisioned values that did not conform to the types of the configurable class, which brings up an important point: type safety. Administrators should not be able to (accidentally nor intentionally) break constraints of applications.

Assuming values are corrected, we can switch back to the application’s perspective and read the user instance.

Database user = runtime.get("user", Database.class);

The user instance is now initialized with values provisioned by the administrator and the application can read it without having to redeploy itself or restart the JVM.

At this very basic level it is important to notice a couple of things. Neither developer nor administrator made any assumptions on the runtime environment, nor did they know/care from where or how configuration was read/written.

Our quickstart use-case is complete but let’s dive a little deeper in order to understand the modelling capabilities of tools4j-config.

Built-in types
Configurable fields can have any of the following types.

• java.lang.String
• java.lang.Number and derived types
• java.lang.Boolean
• java.lang.Enum and derived types, including user-defined ones
• java.util.Date
• java.util.Currency
• java.util.Locale
• java.io.File
• java.net.InetAddress
• java.net.URL
• java.net.URI
• javax.xml.datatype.Duration

Fields can also be declared as a java.util.Collection implementation, generified with any of the above types. Fields initialized at declaration are considered default values (provisioned values take precedence). It is possible to declare user-defined types, but it requires some extra effort and will be covered in a future post.

All of these declarations are valid (annotations omitted for brevity).

// 1, 2, 3 is easy
List<Integer> counting = Arrays.asList(1, 2, 3);
// mathematical variable
Double x;
// measuring performance
TimeUnit precision = TimeUnit.NANOSECONDS;
// 5:01 developers
Set<Day> working = new HashSet<Day>(Arrays.asList(MON, TUE, WED, THU, FRI));
// content tags
List<String> labels;
// forever young
Date young = new Date(Long.MAX_VALUE);

References
Configurable classes can have references to other configurable classes, including themselves (recursive relationships). Circular references are allowed as well (person ‘a’ is person ‘b’:s best friend and usually vice versa).

Declaring references is identical to regular Java types.

@Config(desc = "An individual (or application program) identity")
public class User {
  @Id(desc = "username")
  private String username;
 
  @Config(desc = "password")
  private String password;
 
  @Config(desc = "Roles assigned to this user")
  private Set<Role> roles = new HashSet<Role>();
}
 
@Config(desc = "Role for the permission to access a set of resources")
public class Role {
  @Config(desc = "Permissions to access a set of resources")
  private EnumSet<Privilege> privileges = EnumSet.noneOf(Privilege.class);
 
  @Config(desc = "Roles assigned to this role")
  private Set<Role> roles = new HashSet<Role>();
}

Referential integrity is enforced in order to keep relationships consistent. It is not possible create references to instances that does not exist; or remove instances that other instances already have references to.

Administrating references is almost to identical to provisioning regular Java type values.

BeanId deployerRoleId = BeanId.create("deployer", Role.class.getName());
Bean deployer = Bean.create(deployerRoleId);
 
BeanId assemblerRoleId = BeanId.create("assembler", Role.class.getName());
Bean assembler = Bean.create(assemblerRoleId);
 
BeanId adminRoleId = BeanId.create("administrator", Role.class.getName());
Bean adminRole = Bean.create(adminRoleId);
adminRole.addReference("roles", deployerRoleId);
adminRole.addReference("roles", assemblerRoleId);
 
BeanId adminId = BeanId.create("admin", Role.class.getName());
Bean administrator = Bean.create(adminId);
administrator.addReference("roles", adminRoleId);
administrator.setProperty("password", "xxxxx");

Inheritance
Configurable classes support inheritance and configurable fields will be inherited from their parent class, enabling reuse of configurable fields and methods.

Validation
Tools4j-config integrates with JSR-303 Bean Validation to help developers to further constrain the premises under which configuration may be provisioned.

To enable Bean Validation we need to add the following dependencies to both maven projects mentioned earlier.

<dependency>
  <groupId>javax.validation</groupId>
  <artifactId>validation-api</artifactId>
  <version>1.0.0.GA</version>
  <scope>compile</scope>
</dependency>
<dependency>
  <groupId>org.hibernate</groupId>
  <artifactId>hibernate-validator</artifactId>
  <version>4.1.0.Final</version>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.deephacks.tools4j</groupId>
  <artifactId>config-provider-jsr303</artifactId>
  <version>0.0.1</version>
  <scope>runtime</scope>
</dependency>

Next follows a hypothetical example where Bean Validation constraints are used to make sure that three properties of binary search trees are satisfied.

• The left subtree of a node contains only nodes with keys less than the node’s key.
• The right subtree of a node contains only nodes with keys greater than the node’s key.
• Both the left and right subtrees must also be binary search trees.

@Config(desc = "A binary tree")
@BinaryTreeConstraint
public class BinaryTree {
    @Id(desc = "id of current node")
    private String id;
 
    @Config(desc = "value of current node")
    @NotNull @Min(1)
    private Integer value;
 
    @Config(desc = "left child")
    private BinaryTree left;
 
    @Config(desc = "right child")
    private BinaryTree right;
 
    public Integer getValue() { return value; }
    public BinaryTree getLeft() { return left; }
    public BinaryTree getRight() { return right; }
    public String toString() { return id + "=" + value; }
}
 
public class BinaryTreeValidator implements 
    ConstraintValidator<BinaryTreeConstraint, BinaryTree> {
 
    public boolean isValid(BinaryTree n, ConstraintValidatorContext c) {
        if (n.getLeft() != null && n.getValue() < n.getLeft().getValue()) {
            String msg = n.getLeft() + " must be to right of " + n;
            c.buildConstraintViolationWithTemplate(msg).addConstraintViolation();
            return false;
        }
        if (n.getRight() != null && n.getValue() > n.getRight().getValue()) {
            String msg = n.getRight() + " must be to left of " + n;
            c.buildConstraintViolationWithTemplate(msg).addConstraintViolation();
            return false;
        }
        return true;
    }
 
    public void initialize(BinaryTreeConstraint constraintAnnotation) { }
}
 
@Target({ TYPE })
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = BinaryTreeValidator.class)
public @interface BinaryTreeConstraint {
    String message() default "";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

Tools4j-config is fully compatible with JSR-303 and support any combination of constraints on behalf on Bean Validation.

import javax.validation.constraints.Max;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Past;
import javax.validation.constraints.Pattern;
import javax.validation.constraints.Size;
 
@Config @NotNull @Size(min=1, max=5)
List<Person> persons;
 
@Config @NotNull @Size(min=8, max=25)
String password;
 
@Config @Max(200, message="Area too large")
Integer area() { return length * width; }
 
@Config @Past
Date time;
 
@Config @Pattern(regexp="^[\\w\\-]([\\.\\w])+[\\w]+@([\\w\\-]+\\.)+[a-zA-Z]{2,4}$" , message="Bad email")
String email;

We will not explore validation possibilities further but please do so on your own. JSR303 provide a great way for reusing constraint-related efforts.

What’s next?
Tools4j-config encourage developers to be very precise about defining configurable parts, strengthening guarantees that applications will operate on correct and meaningful data. Tools4-config also enable productivity, leaving room to focus on domain concerns and not forcing a lot of boiler-plate code around administration, persistence and many other unrelated concerns.

Tools4j-config has a lot more functionality than this post could hold – so this is the end. But the following topics will be explored in the future.

• Persistence and data distribution

  How to choose between different ways of storing configuration such as XML files, SQL, NoSQL and more.

• Compile-time checks

  How to catch schema faults at compile-time.

• Administration interfaces

  How to provisioning configuration using interface such as JAX-WS, JAX-RS, auto-generated GUI, CLI and more.

• Administration users and roles

  How to define users and enforce roles for administration.

• Sessions and atomic commits

  How to make several changes in the scope of a session and commit changes atomically.

• Schema discovery

  How to explore the configuration schema at runtime.

• Change notifications

  How applications can subscribe for configuration changes.

• Automatic documentation generation

  How to generate operational documentation from code.

• Performance, scalability and consistency

  How to support low-latency high-performance centralized management in environments of scale with hundreds of thousands configuration instances.

• Java EE and OSGi integration and portability

  How to integrate tools4j-config in Java EE, OSGi, Spring, CDI and other programming models and frameworks.

• Extendability

  How to provide tailor-made implementations using the SPI mechanism and verify them against the TCK.

Please visit the website if you think tools4j-config seems interesting.