Home | Examples | Supported Classes | Collections | What about MyClass | Documentation | Download Latest Release | SourceForge Project Page | SVN code

Additional Classes▲ Top

Joperties allows you to create custom Interpreters that you can register so that Joperties will handle additional classes, other than the supported classes. To do that you subclass the abstract class AbstractInterpreter and you simply register it with Joperties using the methods registerInterpreter(AbstractInterpreter) or the method registerInterpreter(AbstractInterpreter,boolean). The first method will register the Interpreter regardless of whether a previous Interpreter was registered for that specific class, while the second allows you to only register the Interpreter if none is already present.

We will demonstrate with an example. Instead of creating an Interpreter for a new class, we will create a new Interpreter for the class Color which is already handled by Joperties. As the description says, the color is encoded as 0xXXXXXX where XX is the reg,green and blue channels as hex.

We will create a new Interpreter to encode the Color as such: #H;S;B with the HSB values as floats ranging from 0.0-1.0.

▲ Top

HSBColorInterpreter▲ Top

We will name our class HSBColorInterpreter and it will subclass the AbstractInterpreter<Color> (since it will deal with the Color class). This is the first draft without any implementation:

import java.awt.Color;

import joperties.exceptions.EncodingException;
import joperties.exceptions.InterpretationException;
import joperties.exceptions.NoApropriateInterpeterFoundException;
import joperties.interpreters.AbstractInterpreter;

/**
* @author Savvas Dalkitsis
*/
public class HSBColorInterpreter extends AbstractInterpreter<Color> {

  @Override
  public String encode(Color obj) throws EncodingException,
      NoApropriateInterpeterFoundException {
    return null;
  }

  @Override
  public Class<Color> getClassType() {
    return null;
  }

  @Override
  public String getDescription() {
    return null;
  }

  @Override
  public Color interpret(String string) throws InterpretationException,
      NoApropriateInterpeterFoundException {
    return null;
  }

}

We will explain every method starting with the easiest. The method getClassType() must return the Color.class. This is used internally when registering the interpreter. So the implementation will be:

  @Override
  public Class<Color> getClassType() {
    return Color.class;
  }

The next method we will implement is getDescription(). As you may have guessed this is not a vital method but it can be useful when you iterate though all the available Interpreters and you need a description of how they encode and decode the Objects. Plus it's a handy way of documenting the Interpreter behavior. So:

  @Override
  public String getDescription() {
    return "Encodes and decodes a Color using the following format '#H;S;B' where H,S "
    + "and B are the hue, saturation and brightness chanels expressed in float ranging "
    + "from 0.0 to 1.0";
  }

Next comes the encode() method. This method will receive the Color to encode and it must return a String representation of it. Also it must throw an EncodingException if something goes wrong with the encoding process (in such a trivial example, if the Color passed is null) and also a NoApropriateInterpeterFoundException in case the method needs other existing Interpreters for the process but none were found (in our example we will try and get the Interpreter for floats, so if that is not present, we will throw that exception). So:

  @Override
  public String encode(Color obj) throws EncodingException,
      NoApropriateInterpeterFoundException {
    if (obj == null) {
      throw new EncodingException(this, obj);
    }
    AbstractInterpreter<Float> floatInt = Interpreters
        .getInterpreter(Float.class);
    float[] hsb = Color.RGBtoHSB(obj.getRed(), obj.getGreen(), obj
        .getBlue(), null);
    if (hsb.length != 3) {
      throw new EncodingException(this, obj);
    }
    String h = floatInt.encode(hsb[0]);
    String s = floatInt.encode(hsb[1]);
    String b = floatInt.encode(hsb[2]);
    return "#" + h + ";" + s + ";" + b;
  }

As you see we did not explicitly throw a NoApropriateInterpeterFoundException since the Interpreters.getInterpreter() method will throw one automatically if it didn't find an appropriate Interpreter. This demonstrates another practice that you must follow when writing your own interpreters. Even in trivial cases such as writing a float, you must rely on finding an existing Interpreter and letting it encode your value for you instead of simply writing it, because this is where the extensibility of Joperties comes in. All existing interpreters use this practice so if you decide for any reason to register a custom interpreter for the Float class, all existing interpreters that deal with floats will use your new encoding and not simply write out the float as a String. This will be demonstrated with this example when, after we register out new interpreter, we will encode a GradientPaint which uses the registered interpreter for Color to encode the object. More on this, later.

Lastly we need to implement the interpret() method. This method will receive a String and it must return a Color object. It must throw an InterpretationException if there was an error with the format of the incoming String or a NoApropriateInterpeterFoundException if an interpreter is needed that is not found (same as above). So:

  @Override
  public Color interpret(String string) throws InterpretationException,
      NoApropriateInterpeterFoundException {
    if (!string.startsWith("#")) {
      throw new InterpretationException(this, string);
    }
    String[] parts = string.substring(1).split(";");
    if (parts.length != 3) {
      throw new InterpretationException(this, string);
    }
    AbstractInterpreter<Float> floatInt = Interpreters
        .getInterpreter(Float.class);
    Float h = floatInt.interpret(parts[0]);
    Float s = floatInt.interpret(parts[1]);
    Float b = floatInt.interpret(parts[2]);
    if (h < 0 || h > 1 || s < 0 || s > 1 || b < 0 || b > 1) {
      throw new InterpretationException(this, string);
    }
    return Color.getHSBColor(h, s, b);
  }

Now we will try the new Interpreter. We will write a small program that first encodes a Color and a GradientPaint, then registers our new Interpreter and does the same:

import java.awt.Color;
import java.awt.GradientPaint;

import joperties.Joperties;
import joperties.exceptions.EncodingException;
import joperties.exceptions.NoApropriateInterpeterFoundException;
import joperties.interpreters.Interpreters;

/**
* @author Savvas Dalkitsis
*/
public class Test {
  public static void main(String[] args) {
    try {
      Joperties p = new Joperties();
      Color color = Color.MAGENTA;
      GradientPaint gradient = new GradientPaint(0, 0, color, 100, 100,
          Color.WHITE, true);
      p.setJoperty("color", color);
      p.setJoperty("gradient", gradient);
      System.out.println(p.getProperty("color"));
      System.out.println(p.getProperty("gradient"));
      Interpreters.registerInterpreter(new HSBColorInterpreter());
      p.setJoperty("color", color);
      p.setJoperty("gradient", gradient);
      System.out.println(p.getProperty("color"));
      System.out.println(p.getProperty("gradient"));
    } catch (EncodingException e) {
      e.printStackTrace();
    } catch (NoApropriateInterpeterFoundException e) {
      e.printStackTrace();
    }
  }
}

The output is:

0xff00ff
0.0;0.0|0xff00ff|100.0;100.0|0xffffff|true
#0.8333333;1.0;1.0
0.0;0.0|#0.8333333;1.0;1.0|100.0;100.0|#0.0;0.0;1.0|true

As you can see, the first time around, the objects were encoded using the default Interpreters. After we registered our own interpreter, both the color and the gradient (which uses the registered color interpreter internally) used our new encoding. In the same manner if we were to write a new Interpreter for Float objects, then our HSBColorInterpreter would encode a color differently since it looked up the registered Float Interpreter and used that in order to encode the floats of the HSB channels.

▲ Top