NAME

JavaBin - Apache Solr JavaBin (de)serializer

SYNOPSIS

 use JavaBin;

 my $javabin = to_javabin { foo => 'bar' };

 my $href = from_javabin $javabin;

DESCRIPTION

JavaBin is a compact binary format used by Apache Solr.

For more information on this format see the Solr Wiki.

This package provides a serializer and deserializer for this format.

WARNING: The API of this module is unstable and may change without warning (any change will be appropriately documented in the changelog).

FUNCTIONS

from_javabin

 my $result = from_javabin $javabin;

Accepts one argument, a binary string containing the JavaBin.

Returns a scalar representation of the data, be that undef, number, string, or reference.

This function does no error checking, hand it invalid JavaBin and it will probably die.

to_javabin

 my $javabin = to_javabin $data;

Accepts one argument, a Perl scalar, be that undef, number, string, or reference.

Returns a Perl string containing the binary JavaBin.

This function does no error checking, hand it invalid JavaBin and it will probably die.

MAPPING

This section describes how JavaBin maps Perl values to JavaBin values and vice versa. These mappings are designed to "do the right thing" in most circumstances automatically, preserving round-tripping characteristics (what you put in comes out as something equivalent).

Runtime errors are avoided with a preference to encoding more exoctic Perl values (think regular expressions, tied values, etc.) to a JavaBin null.

JavaBin -> Perl

null

A JavaBin null becomes undef in Perl.

true, false

JavaBin booleans become JavaBin::Bool objects in Perl which overload to behave like literal 1 and 0 respectively.

byte, short, int, long

JavaBin integers are returned as scalars (with IV set), with the requirement of a 64bit Perl for longs.

float, double

JavaBin floating point values are returned as scalars (with NV set).

String

JavaBin Strings are returned as Perl strings with the UTF-8 flag on.

Date

A JavaBin Date is returned as a string in ISO 8601 format. This will likely change to be a JavaBin::Date object in future to facilitate round-tripping.

Enum

A JavaBin enum is returned as a JavaBin::Enum object.

array

A JavaBin array is returned as a Perl array.

Iterator

A JavaBin Iterator is flattened into a Perl array. This will likely change to be a JavaBin::Iterator object in future to facilitate round-tripping.

Map, NamedList, SimpleOrderedMap

A JavaBin Map, NamedList, or SimpleOrderedMap is returned as a Perl hash. This is technically wrong all three allow repeating keys but Perl does not, and SimpleOrderedMap, as the name implies, has an order but Perl does not.

This will need to change in the future.

Perl -> JavaBin

TODO

INSPIRATION

This package was inspired by the Ruby JavaBin library. Both that library and the Java JavaBin library proved very helpful in understanding JavaBin.

COPYRIGHT AND LICENSE

Copyright © 2013–2014 by James Raspass

This is free software; you can redistribute it and/or modify it under the same terms as Perl itself.