bhanditz / sofia

A typesafe generated API on top of l10n/i18n resource bundles

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:

test.property=I'm the first test property
parameterized.property.long.name=I need parameters {0} and {1}
new.property=New Property

@error.date.property=Today''s date {0,date,full} and now a number {1,number}

@error.another=I'm an error
@warn.me=I'm just a warning, though.

lonely=I'm only in the default bundle.

a java file will be generated with the following interface:

public class com.antwerkz.sofia.Sofia {
  public static java.lang.String another(java.util.Locale...);
  public static void logAnother(java.util.Locale...);
  public static java.lang.String dateProperty(java.util.Date, java.lang.Number, java.util.Locale...);
  public static void logDateProperty(java.util.Date, java.lang.Number, java.util.Locale...);
  public static java.lang.String me(java.util.Locale...);
  public static void logMe(java.util.Locale...);
  public static java.lang.String lonely(java.util.Locale...);
  public static java.lang.String newProperty(java.util.Locale...);
  public static java.lang.String parameterizedPropertyLongName(java.lang.Object, java.lang.Object, java.util.Locale...);
  public static java.lang.String testProperty(java.util.Locale...);
}

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, 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.

Great. How do I use it?

Add the following to your pom.xml:

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

There are a few configuration options:

Value	Description	Default
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 (supported: none, jul, slf4j)	slf4j
packageName	Defines the package for the generated class	com.antwerkz.sofia
charset	Change the character coding used when reading property files	ISO-8859-1

If you’d like continuous monitoring and regeneration of your files, there’s also "sofia:watch." Using this target, sofia will watch for changes to your input file and regenerate as needed.