Best-practice for documenting available/required Java properties file contents

Question

Is there a well-established approach for documenting Java "properties" file contents, including:

• specifying the data type/contents expected for a given key
• specifying whether a key is required for the application to function
• providing a description of the key's meaning

Currently, I maintain (by hand) a .properties file that is the default, and I write a prose description of the data type and description of each key in a comment before. This does not lead to a programmatically accessible properties file.

I guess what I'm looking for is a "getopt" equivalent for properties files...

[EDIT: Related]

• Java Configuration Frameworks

Answer 1

You could use some of the features in the Apache Commons Configuration package. It at least provides type access to your properties.

There are only conventions in the traditional java properties file. Some I've seen include providing, like you said, an example properties file. Another is to provide the default configuration with all the properties, but commented out.

If you really want to require something, maybe you're not looking for a properties file. You could use an XML configuration file and specify a schema with datatypes and requirements. You can use jaxb to compile the schema into java and read it i that way. With validation you can make sure the required properties are there.

The best you could hope for is when you execute your application, it reads, parses, and validates the properties in the file. If you absolutely had to stay properties based and didn't want to go xml, but needed this parsing. You could have a secondary properties file that listed each property that could be included, its type, and whether it was required. You'd then have to write a properties file validator that would take in a file to validate as well as a validation schema-like properties file. Something like

#list of required properties
required=prop1,prop2,prop3

#all properties and their types
prop1.type=Integer
prop2.type=String

I haven't looked through all of the Apache Configuration package, but they often have useful utilities like this. I wouldn't be surprised if you could find something in there that would simplify this.

Answer 2

Another option to check out is the project called OWNER. There, you define the interface that serves as the configuration object in your application, using types and annotations. Then, OWNER does the finding and parsing of the correct Properties file. Thus, you could write a javadoc for your interface and use that as the documentation.