Recon - What is recon?

Swim developer logo developer.

Overview


Recon is a simple, expressive, structural data model with the simplicity of JSON and the expressiveness of XML. Due to its powerful capabilities and its ease of use, Recon shows up throughout the full stack of every SWIM application. Among many other things, it is

  • The format for loading ServerDefs and other configuration properties
  • The underlying storage and communication format of Lanes, even when the Lane is parametrized
  • With some work, a workaround to Java's lack of Tuples if you properly use Records
Developers will almost certainly encounter the first two usages when building any SWIM application. Because of this, we have made it so any goals pertaining to them can be accomplished without fully understanding Recon. The last requires a deeper understanding of Recon that will not be discussed in this page but can deduced upon learning about the Recon model.

Serialization


No matter how complicated your Recon structures get, serialization and deserialization always follow two rules.

  • To deserialize a Recon String s to a structured Recon Value v, invoke Value v = Value.parseRecon(s);
  • To serialize a structured Value v, invoke String s = v.toRecon();

Marshalling


Unfortunately, the rules for transforming between Recon Values and typed Java objects are not nearly as concise or universal.

Basic Java Types

The table below outlines the process for some basic Java types. The last column shows how to specify a default value when getting an object from Recon. While you are free to put whatever values you want in the argument, the ones given here are used invisibly in certain parts of the SWIM stack, such as calling get() on an empty parametrized Lane.

Java Type To Recon (Marshall) From Recon (Unmarshall) From Recon with Default
boolean Value.of(o); v.booleanValue(); v.booleanValue(false);
char Value.of(o); v.charValue(); v.charValue('\0');
int Value.of(o); v.intValue(); v.intValue(0);
long Value.of(o); v.longValue(); v.longValue(0L);
double Value.of(o); v.doubleValue(); v.doubleValue(0.0);
float Value.of(o); v.floatValue(); v.floatValue(0.0F);
String Value.of(o); v.stringValue(); v.stringValue("");

Custom Java Objects

If you require transformations between a custom Java object and a Recon Value, you must create a Recon Form for that object. At a high level, such a transformation involves iterating over the individual fields in the object and identifying marshalling/unmarshalling rules for each one.

A Form<T> is simply a cache for these rules for a given class T. Marshalling to a Recon Value is accomplished through form.mold((T) obj);. Unmarshalling to a T is accomplished through form.cast((Value) v);. In fact, even the invocations in the last two columns of the above table utilize form.cast(); invisibly.

This diagram summarizes the various transformations possible in Recon.

There are three ways to utilize a Form, depending on what you're working with.

  • If you have full control over the class's source code, SWIM comes with the @ReconHeader and the @ReconName annotations to automate Form creation. Please refer to an example of how to do this here.
  • Otherwise, because several static Forms exist in recon.Form.class, you should check to see if one corresponding to your class already exists here.
  • If not, you'll have to create your own Form, as outlined here.