RT::Client::REST::ObjeUser)Contributed Perl DocumenRT::Client::REST::Object(3)NAMERT::Client::REST::Object-- base class for RT objects.
SYNOPSIS
# Create a new type
package RT::Client::REST::MyType;
use base qw(RT::Client::REST::Object);
sub _attributes {{
myattribute => {
validation => {
type => SCALAR,
},
},
}}
sub rt_type { "mytype" }
1;
DESCRIPTION
The RT::Client::REST::Object module is a superclass providing a whole
bunch of class and object methods in order to streamline the
development of RT's REST client interface.
ATTRIBUTES
Attributes are defined by method "_attributes" that should be defined
in your class. This method returns a reference to a hash whose keys
are the attributes. The values of the hash are attribute settings,
which are as follows:
list
If set to true, this is a list attribute. See "LIST ATTRIBUTE
PROPERTIES" below.
validation
A hash reference. This is passed to validation routines when
associated mutator is called. See Params::Validate for reference.
rest_name
This specifies this attribute's REST name. For example, attribute
"final_priority" corresponds to RT REST's "FinalPriority". This
option may be omitted if the two only differ in first letter
capitalization.
form2value
Convert form value (one that comes from the server) into attribute-
digestible format.
value2form
Convert value into REST form format.
Example:
sub _attributes {{
id => {
validation => {
type => SCALAR,
regex => qr/^\d+$/,
},
form2value => sub {
shift =~ m~^ticket/(\d+)$~i;
return $1;
},
value2form => sub {
return 'ticket/' . shift;
},
},
admin_cc => {
validation => {
type => ARRAYREF,
},
list => 1,
rest_name => 'AdminCc',
},
}}
LIST ATTRIBUTE PROPERTIES
List attributes have the following properties:
· When called as accessors, return a list of items
· When called as mutators, only accept an array reference
· Convenience methods "add_attr" and "delete_attr" are available. For
example:
# Get the list
my @requestors = $ticket->requestors;
# Replace with a new list
$ticket->requestors( [qw(dude@localhost)] );
# Add some random guys to the current list
$ticket->add_requestors('randomguy@localhost', 'evil@local');
SPECIAL ATTRIBUTES
id and parent_id are special attributes. They are used by various DB-
related methods and are especially relied upon by autostore, autosync,
and autoget features.
METHODS
new
Constructor
_generate_methods
This class method generates accessors and mutators based on
_attributes method which your class should provide. For items that
are lists, 'add_' and 'delete_' methods are created. For instance,
the following two attributes specified in _attributes will generate
methods 'creator', 'cc', 'add_cc', and 'delete_cc':
creator => {
validation => { type => SCALAR },
},
cc => {
list => 1,
validation => { type => ARRAYREF },
},
_mark_dirty($attrname)
Mark an attribute as dirty.
_dirty
Return the list of dirty attributes.
_mark_dirty_cf($attrname)
Mark an custom flag as dirty.
_dirty_cf
Return the list of dirty custom flags.
to_form($all)
Convert the object to 'form' (used by REST protocol). This is done
based on _attributes method. If $all is true, create a form from all
of the object's attributes and custom flags, otherwise use only dirty
(see _dirty method) attributes and custom flags. Defaults to the
latter.
from_form
Set object's attributes from form received from RT server.
param($name, $value)
Set an arbitrary parameter.
cf([$name, [$value]])
Given no arguments, returns the list of custom field names. With one
argument, returns the value of custom field $name. With two
arguments, sets custom field $name to $value. Given a reference to a
hash, uses it as a list of custom fields and their values, returning
the new list of all custom field names.
rt
Get or set the 'rt' object, which should be of type RT::Client::REST.
DB METHODS
The following are methods that have to do with reading, creating,
updating, and searching objects.
count
Takes the same arguments as "search()" but returns the actual count
of the found items. Throws the same exceptions.
retrieve
Retrieve object's attributes. Note that 'id' attribute must be set
for this to work.
search (%opts)
This method is used for searching objects. It returns an object of
type RT::Client::REST::SearchResult, which can then be used to
process results. %opts is a list of key-value pairs, which are as
follows:
limits
This is a reference to array containing hash references with limits
to apply to the search (think SQL limits).
orderby
Specifies attribute to sort the result by (in ascending order).
reverseorder
If set to a true value, sorts by attribute specified by orderby in
descending order.
If the client cannot construct the query from the specified
arguments, or if the server cannot make it out,
"RT::Client::REST::Object::InvalidSearchParametersException" is
thrown.
store
Store the object. If 'id' is set, this is an update; otherwise, a
new object is created and the 'id' attribute is set. Note that only
changed (dirty) attributes are sent to the server.
CLASS METHODS
use_single_rt
This method takes a single argument -- RT::Client::REST object and
makes this class use it for all instantiations. For example:
my $rt = RT::Client::REST->new(%args);
# Make all tickets use this RT:
RT::Client::REST::Ticket->use_single_rt($rt);
# Now make all objects use it:
RT::Client::REST::Object->use_single_rt($rt);
use_autostore
Turn autostoring on and off. Autostoring means that you do not have
to explicitly call "store()" on an object - it will be called when
the object goes out of scope.
# Autostore tickets:
RT::Client::REST::Ticket->use_autostore(1);
my $ticket = RT::Client::REST::Ticket->new(%opts)->retrieve;
$ticket->priority(10);
# Don't have to call store().
use_autoget
Turn autoget feature on or off (off by default). When set to on,
"retrieve()" will be automatically called from the constructor if it
is called with that object's special attributes (see "SPECIAL
ATTRIBUTES" above).
RT::Client::Ticket->use_autoget(1);
my $ticket = RT::Client::Ticket->new(id => 1);
# Now all attributes are available:
my $subject = $ticket->subject;
use_autosync
Turn autosync feature on or off (off by default). When set, every
time an attribute is changed, "store()" method is invoked. This may
be pretty expensive.
be_transparent
This turns on autosync and autoget. Transparency is a neat idea, but
it may be expensive and slow. Depending on your circumstances, you
may want a finer control of your objects. Transparency makes
"retrieve()" and "store()" calls invisible:
RT::Client::REST::Ticket->be_transparent($rt);
my $ticket = RT::Client::REST::Ticket->new(id => $id); # retrieved
$ticket->add_cc('you@localhost.localdomain'); # stored
$ticket->status('stalled'); # stored
# etc.
Do not forget to pass RT::Client::REST object to this method.
SEE ALSO
RT::Client::REST::Ticket, RT::Client::REST::SearchResult.
AUTHOR
Dmitri Tikhonov <dtikhonov@yahoo.com>
perl v5.14.1 2008-01-25 RT::Client::REST::Object(3)
