Skip to content

Latest commit

 

History

History
117 lines (90 loc) · 4.92 KB

readmesource.asciidoc

File metadata and controls

117 lines (90 loc) · 4.92 KB
Raw

Sofia

Sofia is a typesafe (ish) layer on top of a properties file. Given a properties file, it will generate a java class providing compile time checks that you’re using values that actually exist in your properties file. It supports multiple locales if you provide them.

A simple example looks like this. For this properties file:

link:tests/src/main/resources/sofia.properties[role=include]

a java file will be generated with the following interface:

link:tests/target/sofia.output[role=include]

There are some other details but they’re mostly irrelevant. Feel free to explore the generated file if you’re really interested. What you see here is one method for each property listed in your properties file. Those properties that take parameters result in methods that take parameters as well. Notice that each parameter is typed according to the formatting specified in the properties file. If no formatting is defined, "Object" is used for that parameter type.

Also note that each method takes a Locale…​ parameter. This allows sofia to generate one method per property while supporting an optional Locale to be supplied without having to generate two identical methods or having to pass in a null to a "singleton" parameter. Multiple Locales can be passed in but only one will be used.

So …​ why?

When I worked on [glassfish](http://glassfish.java.net), we’d standardized on a library that did something similar. My biggest complaint about that one is that all the generated methods WERE IN ALL CAPS WHICH MADE READING THE CODE AWKWARD. Also, I’m not really sure where the source for that library is so patching it would be tricky. In any case, it turned out to be a very handy facet to a project which makes use of properties files to manage its messages so I wanted to improve on it where I could.

OK. So what’s next?

There are a handful of things I’d like to add:

  1. Build time validation of properties files: Making sure that all the properties files variants have the same key set.

  2. Optional autogeneration of error code values for those systems that need numeric codes assigned to each message. Oracle had such requirements for its error messages and manually managing that was troublesome. Of course, generating them might prove just as problematic, but we’ll see how it goes.

  3. Play framework support. I’d love for this to work in [play!](http://playframework.org) as well as I’ve been using that more and more lately.

  4. Logging support via slf4j or logback

Great. How do I use it?

Add the following to your pom.xml:

    <plugin>
      <groupId>com.antwerkz.sofia</groupId>
      <artifactId>maven</artifactId>
      <version>0.12</version>
      <executions>
        <execution>
          <goals>
            <goal>generate</goal>
          </goals>
        </execution>
      </executions>
    </plugin>

There are a few configuration options:

Value

Description

Default

packageName

Defines the package for the generated class

com.antwerkz.sofia

inputFile

The base properties file to use

src/main/resources/sofia.properties

outputDirectory

Generated source location

${project.build.directory}/generated-sources/sofia

loggingType

Use a specific logger

playController

Generate code for use in play applications (supported: none, jul, slf4j)

slf4j

For use in Play apps

Add the this line to your Build.scala file in your appDependencies variable

"com.antwerkz.sofia" % "sofia-play" % "0.12"

If you’ve just checked out a new project, you might need to pregenerate your file before the play app will start. The easiest way, for now, is if the project has provided a pom.xml and configured Sofia with something like this:

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>exec-maven-plugin</artifactId>

    <configuration>
        <mainClass>com.antwerkz.sofia.play.SofiaPlugin</mainClass>
    </configuration>
</plugin>

Ideally, Sofia would provide an sbt plugin to make this happen. I don’t know how to write those yet so that will just have to wait until I do or someone provides a patch.</hint> It would be easiest for all to simply commit your generated file to whichever version control system you use.

One last question…​ Why sofia?

Project naming can be tricky. I like my project names to be interesting in one way or another. This project started off as a localization concept: translation. One of my favorite movies is "Lost in Translation" which is direced by Sofia Coppola. So …​ sofia.

The mystique of the unexplained name was better than the truth wasn’t it? Well, you asked…​