NAME

Class::STAF::Marshalled - an OO approach to Marshalling and UnMarshalling STAF data (http://staf.sourceforge.net/)

SYNOPSIS

Preparing regular data to be sent:

    use Class::STAF;
    
    my $x = [ { a1=>5, a2=>6 }, "bbbb", [1, 2, 3] ];
    my $out_string = Marshall($x);

Preparing 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.

Marshalling is serializing. The same job done by Storable and such, only compatible with the standard serializing API the the STAF framework create and understand.

For more info about STAF: http://staf.sourceforge.net/

This API covers handling scalars, arrays, and hashes. Use this API to create classes and send them; accept data that includes classes from a different origin, 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 is received by reference. If a 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 instantiate. Return undef if the reference is not to a STAF-class.

get_staf_fields

Not exported by default.

Accept a hash reference, and return the list of fields. Each of the fields contains 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, for example:

    package STAF::Service::My::FileRecord;
    use base qw/Class::STAF::Marshalled/;

Will define a STAF-class named 'STAF/Service/My/FileRecord', (names of classes in STAF are delimited with slashes instead of '::') then define the members of the class:

    __PACKAGE__->field("name", "LongFileName");
    __PACKAGE__->field("size", "SizeInBytes", default=>0);
    __PACKAGE__->field("owner", "FileOwner", short=>"owner");

The syntax of the command is:

    __PACKAGE__->field(name, description [, default=>5] [, short=>"ser#"]);

The first and second parameters are the name and description of the field. Two more optional parameters are named default and short (when displaying the class in formatted text, it is sometimes needed).

Instancing

Simple.

    $filerec1 = STAF::Service::My::FileRecord->new();

The fields defined as default will be assigned their default values, all other will be left undefined.

    $filerec2 = STAF::Service::My::FileRecord->new(name=>"system.ini", owner=>"me");

Fields specified will be assigned that value. Fields that were not specified but have a default value, will be assigned the default value. Fields that neither specified nor have a default, will left undefined.

    $filerec2 = STAF::Service::My::FileRecord->new(name=>"system.ini", size=>70);

Perl and STAF classes

When instancing a class, it will be blessed to that Perl class. So it is possible to define subrotines inside these classes.

However, when a class data is being unmarshalled, it is blessed to Class::STAF::Marshalled, and not to its true name, (that can be anything that the sender want) for oblious security reasons.

So, if it is needed to find out the name of a locally created class, it is possible to use the ref keyword. If it is an unmarshalled class, use the get_staf_class_name function.

BUGS

None known.

This is a first release - your feedback will be appreciated.

SEE ALSO

STAF homepage: http://staf.sourceforge.net/ Main package: Class::STAF

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.

cpanm Class::STAF

perl -MCPAN -e shell
install Class::STAF