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>