s/tomee.xml/tomee.json/

TomEE uses conf/tomee.xml as main configuration but we are at the moment thinking to an alternative configuration based on JSON.

Why JSon?

As a reminder, here is a sample of tomee.xml:

<tomee>
  <Resource id="my datasource" type="DataSource">
    JdbcUrl = ...
    # other configuration
  </Resource>
</tomee>

tomee.xml is great because it uses properties format in an XML document which simplifies a lot the file but it is not that natural for newcomers and it can look old/weird today because of new structured formats like JSon, Yaml…. JSon tends to replace XML in web services but why wouldn’t it replace xml for configuration too?

Proposal

The proposal is quite simple – use a tomee.json instead of a tomee.xml – and a sample will say much more than a long text:

{
    "resources": {
        "my datasource non jta": {
            "type": "DataSource",
            "properties": {
                "JdbcUrl": "jdbc:hsqldb:mem:json",
                "MaxActive": 20,
                "JtaManaged": false
            }
        },
        "my datasource": {
            "type": "DataSource",
            "properties": {
                "JdbcUrl": "jdbc:hsqldb:mem:json",
            }
        }
    }
}

You basically define your resources in “resources” item and use the id as key. What was in properties format in tomee.xml goes in “properties” attribute of the resource and attributes of the <Resource> tag (like class-name, type, …) go as attribute of the resource directly.

You can define your containers the same way too:

{
    "containers": {
        "stateless": {
            "type": "STATELESS",
            "properties": {
                "AccessTimeout": "10 seconds"
            }
        }
    }
}

Another interesting feature is the ability to set system properties directly through this file using “system-properties” attribute:

{
    "system-properties": {
        "a": "b",
        "c": "d",
        "e": {
            "f": "g",
            "h": {
                "i": "j"
            }
        }
    }
}

This sample will set a = b, c = d, e.f = g and e.h.i = j. It is a direct replacement for almost all properties you can find in conf/system.properties.

Another nice point is that daemons (cxf, cxf-rs, ejbd…) can be configured through this file too either using system-properties or to get something more structured using “daemons” item:

{
    "daemons": {
        "cxf": {
            "disabled": false
        }
    }
}

Finally we didn’t forget comments which can be very important in config files and we allowed them through the “__” key (comments are not specified in json specification AFAIK):

{
    "__": [
        "comments are supported through __ key",
        "so don't hesitate to explain what you are configuring"
    ],
    "resources": {
        "__": [
            "here is",
            "the resources configuration"
        ],
        "json-datasource": {
            "__": [
                "properties is the magic attribute",
                "to configure the resource"
            ],
            "properties": {
                "JdbcUrl": "jdbc:hsqldb:mem:json",
                "MaxActive": 123,
                "JtaManaged": false
            }
        }
    }
}

Feel free to join the discussion on the tomee dev mailing list if you want to share your opinion before the release. It will be greatly appreciated.

Advertisement