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.