NAME
Class::STAF - OO approche to Marshalling and UnMarshalling STAF data
SYNOPSIS
Readying regular data to be sent:
use Class::STAF;
my $x = [ { a1=>5, a2=>6 }, "bbbb", [1, 2, 3] ];
my $out_string = Marshall($x);Readying class data to be sent:
package STAF::Service::Var::VarInfo;
use base qw/Class::STAF::Marshalled/;
__PACKAGE__->field("X", "X");
__PACKAGE__->field("Y", "Y", default=>5);
__PACKAGE__->field("serial", "SerialNumber", short=>"ser#");
... elsewhere in your program
$ref = STAF::Service::Var::VarInfo->new("X"=>3, "serial"=> 37);
# ... and Y is 5, by default.
$out_string = Marshall($ref);Receiving and manipulating data:
my $ref = UnMarshall($incoming_string);
my $info = $ref->[0]->{info};
$ref->[2]->{Number} = 3;
$out_string = Marshall($ref);DESCRIPTION
This module is an OO interface to the STAF Marshalling API, inspired by Class::DBI.
This API covers handling scalars, arrays and hashs. Also it is possible to create classes (not mapped to Perl objects/classes) and send them. further more, it is possible to accept data that includes classes from the other side, manipulate it, and marshall it back with the original classes defenitions. and all this is completely transparant to the developer.
Functions
Marshall
Stringify a data structure.
$out_string1 = Marshall($single_ref);
$out_string2 = Marshall($ref1, $ref2, ...);Can handle any array, hash or scalar that it gets by reference. If an list/array is passed, it is handled as if a reference to that array was passed.
UnMarshall
Un-Stringify a data structure.
my $ref = UnMarshall($stringify_data);accept a single string containing marshalled data, and return a single reference to the opened data.
get_staf_class_name
Not exported by default.
Accept a hash reference, and return the name of the staf-class that it instatae. return undef if is not a staf-class.
get_staf_fields
Not exported by default.
Accept a hash reference, and return the list of fields. each of the fields contain at least the map-key ('key') and the display-name ('display-name'). may contain a default ('default') and short name ('short') if defined.
Building staf-class
Defining
For building a staf-class, define a package, and base it on Class::STAF::Marshalled, as exampled:
package STAF::Service::My::FileRecord;
use base qw/Class::STAF::Marshalled/;Will defined a staf-class named 'STAF/Service/My/FileRecord'. (names of classes in staf are with slashes instead of '::') then defined the members of the class:
__PACKAGE__->field("name", "LongFileName");
__PACKAGE__->field("size", "SizeInBytes", default=>0);
__PACKAGE__->field("owner", "FileOwner", short=>"owner");The syntex of the command is:
__PACKAGE__->field(name, description [, default=>5] [, short=>"ser#"]);The first and the second parameters are the name and description of the field. There are two more optional named parameters default and short that is short for short name. (when displaying the class in formated text, it is sometimes needed)
Instancing
Simple.
$filerec1 = STAF::Service::My::FileRecord->new();The fields with default defined will get their default values. all other will left undefined.
$filerec2 = STAF::Service::My::FileRecord->new(name=>"system.ini", owner=>"me");Fields specified will get that value. Fields that were not specified but have a default value, will get the default value. Fields that naither specified nor have default, will left undefined.
$filerec2 = STAF::Service::My::FileRecord->new(name=>"system.ini", size=>70);...The same.
BUGS
Non known.
This is a first release - your feedback will be appriciated.
SEE ALSO
STAF homepage: http://staf.sourceforge.net/
The STAFService CPAN module.
AUTHOR
Fomberg Shmuel, <owner@semuel.co.il>
COPYRIGHT AND LICENSE
Copyright 2007 by Shmuel Fomberg.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.