NAME¶
RT::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>