Name

Object::Relation::Format - The Object::Relation serialization class

Synopsis

  use Object::Relation::Format;
  my $formatter = Object::Relation::Format->new( { format => 'json' } );
  my $json      = $formatter->serialize($obj_rel_object);
  my $object    = $formatter->deserialize($json);

Description

This class is used for serializing and deserializing Object::Relation objects to and from a specified format. New objects may be created or existing objects may be updated using this class.

Constructors

new

  my $xml = Object::Relation::Format->new({ format => 'json' });

Creates and returns a new format object. Requires a hashref as an argument. The key format in the hashref must be a valid format with the Object::Relation Platform supports. Currently supported formats are:

• json

• xml

format

  my $format = $formatter->format;

Returns the format for the class.

serialize

  my $format = $formatter->serialize($object);

Render the Object::Relation::Base object in the desired format.

deserialize

   my $object = $formatter->deserialize($format);

Restore the object from the desired format.

content_type

  my $content_type = $formatter->content_type;

This method must be overridden in a subclass.

This method returns the MIME content type of the format.

ref_to_format

  my $format = $formatter->ref_to_format($reference);

This method must be overridden in a subclass.

Given an array or hash reference, this method must render it in the correct format.

format_to_ref

  my $ref = $formatter->format_to_ref($format);

This method must be overridden in a subclass.

Given a format, this method must render it in the correct array or hash format.

_obj_to_hashref

  my $hashref = $formatter->_obj_to_hashref($object);

Protected method to be used by subclasses, this method should take a Object::Relation::Base object and render it as a hashref. Only publicly exposed data will be returned in the hash ref. Each key will be an attribute name and the value should be the value of the key, if any.

One special key, Key, will be the class key for the Object::Relation::Base object.

_hashref_to_obj

  my $object = $formatter->_hashref_to_obj($hashref);

Protected method to be used by subclasses. Given an hash reference in the format returned by _obj_to_hashref, this method will return a Object::Relation::Base object for it.

expand_ref

  my $ref = $formatter->expand_ref($reference);

Given an arbitrary data structure, this method will walk the structure and expand the Object::Relation object founds into hash references.

Current understands array refs, hashrefs, Object::Relation objects and Iterators.

IMPLEMENTING A NEW FORMAT

Adding a new format is as simple as implementing the format with the format name as the class name upper case, appended to Object::Relation::Format:

 package Object::Relation::Format::JSON;
 package Object::Relation::Format::XML;
 package Object::Relation::Format::YAML;

Factory classes must meet the following conditions:

• Inherit from Object::Relation::Format.

  The factory class should inherit from Object::Relation::Format.

• new is optional.

  A constructor should not be supplied, but if it is, it should be named new and should call the super class constructor.

• Implement _init method.

  It should have an _init method which sets up special properties, if any, of the class. If an init method is present, it should accept an optional hash reference of properties necessary for the class and return a single argument.

• Implement format_to_ref and ref_to_format methods.

  The input and output is described in this document. Implementation behavior is up to the implementor.

Copyright and License

Copyright (c) 2004-2006 Kineticode, Inc. <info@obj_relode.com>

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

cpanm Object::Relation

perl -MCPAN -e shell
install Object::Relation