PojoSwaps

{@link oaj.transform.PojoSwap PojoSwaps} are a critical component of Juneau. They allow the serializers and parsers to handle Java objects that wouldn't normally be serializable.

Swaps are, simply put, 'object swappers' that swap in serializable objects for non-serializable ones during serialization, and vis-versa during parsing.

Some examples of non-serializable POJOs are `File`, `Reader`, `Iterable`, etc... These are classes that aren't beans and cannot be represented as simple maps, collections, or primitives.

In the following example, we introduce a `PojoSwap` that will swap in ISO8601 strings for `Date` objects:

// Sample swap for converting Dates to ISO8601 strings. public class MyDateSwap extends PojoSwap<Date,String> { // ISO8601 formatter. private DateFormat format = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ssZ"); // Converts a Date object to an ISO8601 string. @Override /* PojoSwap */ public String swap(BeanSession session, Date o) { return format.format(o); } // Converts an ISO8601 string to a Date object. @Override /* PojoSwap */ public Date unswap(BeanSession session, String o, ClassMeta hint) throws Exception { return format.parse(o); } }

The swap can then be associated with serializers and parsers like so:

// Sample bean with a Date field. public class MyBean { public Date date = new Date(112, 2, 3, 4, 5, 6); } // Create a new JSON serializer, associate our date swap with it, and serialize a sample bean. WriterSerializer s = JsonSerializer.create().simple().pojoSwaps(MyDateSwap.class).build(); String json = s.serialize(new MyBean()); // == "{date:'2012-03-03T04:05:06-0500'}" // Create a JSON parser, associate our date swap with it, and reconstruct our bean (including the date). ReaderParser p = JsonParser.create().pojoSwaps(MyDateSwap.class).build(); MyBean bean = p.parse(json, MyBean.class); int day = bean.date.getDay(); // == 3

The {@link oaj.BeanMap#get(Object)} and {@link oaj.BeanMap#put(String,Object)} methods will automatically convert to swapped values as the following example shows:

// Create a new bean context and add our swap. BeanContext bc = BeanContext.create().pojoSwaps(MyDateSwap.class).build(); // Create a new bean. MyBean myBean = new MyBean(); // Wrap it in a bean map. BeanMap<Bean> beanMap = bc.forBean(myBean); // Use the get() method to get the date field as an ISO8601 string. String date = (String)beanMap.get("date"); // == "2012-03-03T04:05:06-0500" // Use the put() method to set the date field to an ISO8601 string. beanMap.put("date", "2013-01-01T12:30:00-0500"); // Set it to a new value. // Verify that the date changed on the original bean. int year = myBean.date.getYear(); // == 113

Another example of a `PojoSwap` is one that converts `byte[]` arrays to BASE64-encoded strings:

public class ByteArrayBase64Swap extends StringSwap<byte[]> { @Override /* StringSwap */ public String swap(byte[] b) throws Exception { ByteArrayOutputStream baos = new ByteArrayOutputStream(); OutputStream b64os = MimeUtility.encode(baos, "base64"); b64os.write(b); b64os.close(); return new String(baos.toByteArray()); } @Override /* StringSwap */ public byte[] unswap(String s, ClassMeta<?> hint) throws Exception { byte[] b = s.getBytes(); ByteArrayInputStream bais = new ByteArrayInputStream(b); InputStream b64is = MimeUtility.decode(bais, "base64"); byte[] tmp = new byte[b.length]; int n = b64is.read(tmp); byte[] res = new byte[n]; System.arraycopy(tmp, 0, res, 0, n); return res; } }

The following example shows the BASE64 swap in use:

// Create a JSON serializer and register the BASE64 encoding swap with it. WriterSerializer s = JsonSerializer.create().simple().pojoSwaps(ByteArrayBase64Swap.class).build(); ReaderParser p = JsonParser.create().pojoSwaps(ByteArrayBase64Swap.class).build(); byte[] bytes = {1,2,3}; String json = s.serialize(bytes); // Produces "'AQID'" bytes = p.parse(json, byte[].class); // Reproduces {1,2,3} byte[][] bytes2d = {{1,2,3},{4,5,6},null}; json = s.serialize(bytes2d); // Produces "['AQID','BAUG',null]" bytes2d = p.parse(json, byte[][].class); // Reproduces {{1,2,3},{4,5,6},null}

Several `PojoSwaps` are already provided for common Java objects:

- org.apache.juneau.transforms
  - {@link oaj.transforms.ByteArrayBase64Swap}
  - {@link oaj.transforms.CalendarSwap}
  - {@link oaj.transforms.DateSwap}
  - {@link oaj.transforms.EnumerationSwap}
  - {@link oaj.transforms.IteratorSwap}
  - {@link oaj.transforms.ReaderSwap}
  - {@link oaj.transforms.XMLGregorianCalendarSwap}

In particular, the {@link oaj.transforms.CalendarSwap} and {@link oaj.transforms.DateSwap} transforms provide a large number of customized swaps to ISO, RFC, or localized strings.

Swaps have access to the session locale and timezone through the {@link oaj.BeanSession#getLocale()} and {@link oaj.BeanSession#getTimeZone()} methods.
This allows you to specify localized swap values when needed.

If using the REST server API, the locale and timezone are set based on the `Accept-Language` and `Time-Zone` headers on the request.

- The 'swapped' class type must be a serializable type.
  See the definition for Category 4 objects in {@doc PojoCategories}.