1RT::Client::REST::ObjecUts(e3r)Contributed Perl DocumentRaTt:i:oCnlient::REST::Object(3)
2
3
4

NAME

6       RT::Client::REST::Object - base class for RT objects
7

VERSION

9       version 0.72
10

SYNOPSIS

12         # Create a new type
13         package RT::Client::REST::MyType;
14
15         use parent qw(RT::Client::REST::Object);
16
17         sub _attributes {{
18           myattribute => {
19             validation => {
20               type => SCALAR,
21             },
22           },
23         }}
24
25         sub rt_type { "mytype" }
26
27         1;
28

DESCRIPTION

30       The RT::Client::REST::Object module is a superclass providing a whole
31       bunch of class and object methods in order to streamline the
32       development of RT's REST client interface.
33

ATTRIBUTES

35       Attributes are defined by method "_attributes" that should be defined
36       in your class.  This method returns a reference to a hash whose keys
37       are the attributes.  The values of the hash are attribute settings,
38       which are as follows:
39
40       list
41         If set to true, this is a list attribute.  See "LIST ATTRIBUTE
42         PROPERTIES" below.
43
44       validation
45         A hash reference.  This is passed to validation routines when
46         associated mutator is called.  See Params::Validate for reference.
47
48       rest_name
49         This specifies this attribute's REST name.  For example, attribute
50         "final_priority" corresponds to RT REST's "FinalPriority".  This
51         option may be omitted if the two only differ in first letter
52         capitalization.
53
54       form2value
55         Convert form value (one that comes from the server) into attribute-
56         digestible format.
57
58       value2form
59         Convert value into REST form format.
60
61       Example:
62
63         sub _attributes {{
64           id  => {
65               validation  => {
66                   type    => SCALAR,
67                   regex   => qr/^\d+$/,
68               },
69               form2value  => sub {
70                   shift =~ m~^ticket/(\d+)$~i;
71                   return $1;
72               },
73               value2form  => sub {
74                   return 'ticket/' . shift;
75               },
76           },
77           admin_cc        => {
78               validation  => {
79                   type    => ARRAYREF,
80               },
81               list        => 1,
82               rest_name   => 'AdminCc',
83           },
84         }}
85

LIST ATTRIBUTE PROPERTIES

87       List attributes have the following properties:
88
89       • When called as accessors, return a list of items
90
91       • When called as mutators, only accept an array reference
92
93       • Convenience methods "add_attr" and "delete_attr" are available.  For
94         example:
95
96           # Get the list
97           my @requestors = $ticket->requestors;
98
99           # Replace with a new list
100           $ticket->requestors( [qw(dude@localhost)] );
101
102           # Add some random guys to the current list
103           $ticket->add_requestors('randomguy@localhost', 'evil@local');
104

SPECIAL ATTRIBUTES

106       id and parent_id are special attributes.  They are used by various DB-
107       related methods and are especially relied upon by:
108
109       autostore
110       autosync
111       autoget
112

METHODS

114       new
115         Constructor
116
117       _generate_methods
118         This class method generates accessors and mutators based on
119         _attributes method which your class should provide.  For items that
120         are lists, 'add_' and 'delete_' methods are created.  For instance,
121         the following two attributes specified in _attributes will generate
122         methods 'creator', 'cc', 'add_cc', and 'delete_cc':
123
124           creator => {
125             validation => { type => SCALAR },
126           },
127           cc => {
128             list => 1,
129             validation => { type => ARRAYREF },
130           },
131
132       _mark_dirty($attrname)
133         Mark an attribute as dirty.
134
135       _dirty
136         Return the list of dirty attributes.
137
138       _mark_dirty_cf($attrname)
139         Mark an custom flag as dirty.
140
141       _dirty_cf
142         Return the list of dirty custom flags.
143
144       to_form($all)
145         Convert the object to 'form' (used by REST protocol). This is done
146         based on _attributes method. If $all is true, create a form from all
147         of the object's attributes and custom flags, otherwise use only dirty
148         (see _dirty method) attributes and custom flags. Defaults to the
149         latter.
150
151       from_form
152         Set object's attributes from form received from RT server.
153
154       param($name, $value)
155         Set an arbitrary parameter.
156
157       cf([$name, [$value]])
158         Given no arguments, returns the list of custom field names.  With one
159         argument, returns the value of custom field $name.  With two
160         arguments, sets custom field $name to $value.  Given a reference to a
161         hash, uses it as a list of custom fields and their values, returning
162         the new list of all custom field names.
163
164       rt
165         Get or set the 'rt' object, which should be of type RT::Client::REST.
166

DB METHODS

168       The following are methods that have to do with reading, creating,
169       updating, and searching objects.
170
171       count
172         Takes the same arguments as search() but returns the actual count of
173         the found items.  Throws the same exceptions.
174
175       retrieve
176         Retrieve object's attributes.  Note that 'id' attribute must be set
177         for this to work.
178
179       search (%opts)
180         This method is used for searching objects.  It returns an object of
181         type RT::Client::REST::SearchResult, which can then be used to
182         process results.  %opts is a list of key-value pairs, which are as
183         follows:
184
185         limits
186           This is a reference to array containing hash references with limits
187           to apply to the search (think SQL limits).
188
189         orderby
190           Specifies attribute to sort the result by (in ascending order).
191
192         reverseorder
193           If set to a true value, sorts by attribute specified by orderby in
194           descending order.
195
196         If the client cannot construct the query from the specified
197         arguments, or if the server cannot make it out,
198         "RT::Client::REST::Object::InvalidSearchParametersException" is
199         thrown.
200
201       store
202         Store the object.  If 'id' is set, this is an update; otherwise, a
203         new object is created and the 'id' attribute is set.  Note that only
204         changed (dirty) attributes are sent to the server.
205

CLASS METHODS

207       use_single_rt
208         This method takes a single argument -- RT::Client::REST object and
209         makes this class use it for all instantiations.  For example:
210
211           my $rt = RT::Client::REST->new(%args);
212
213           # Make all tickets use this RT:
214           RT::Client::REST::Ticket->use_single_rt($rt);
215
216           # Now make all objects use it:
217           RT::Client::REST::Object->use_single_rt($rt);
218
219       use_autostore
220         Turn autostoring on and off.  Autostoring means that you do not have
221         to explicitly call store() on an object - it will be called when the
222         object goes out of scope.
223
224           # Autostore tickets:
225           RT::Client::REST::Ticket->use_autostore(1);
226           my $ticket = RT::Client::REST::Ticket->new(%opts)->retrieve;
227           $ticket->priority(10);
228           # Don't have to call store().
229
230       use_autoget
231         Turn autoget feature on or off (off by default). When set to on,
232         retrieve() will be automatically called from the constructor if it is
233         called with that object's special attributes (see "SPECIAL
234         ATTRIBUTES" above).
235
236           RT::Client::Ticket->use_autoget(1);
237           my $ticket = RT::Client::Ticket->new(id => 1);
238           # Now all attributes are available:
239           my $subject = $ticket->subject;
240
241       use_autosync
242         Turn autosync feature on or off (off by default).  When set, every
243         time an attribute is changed, store() method is invoked.  This may be
244         pretty expensive.
245
246       be_transparent
247         This turns on autosync and autoget.  Transparency is a neat idea, but
248         it may be expensive and slow.  Depending on your circumstances, you
249         may want a finer control of your objects.  Transparency makes
250         retrieve() and store() calls invisible:
251
252           RT::Client::REST::Ticket->be_transparent($rt);
253
254           my $ticket = RT::Client::REST::Ticket->new(id => $id); # retrieved
255           $ticket->add_cc('you@localhost.localdomain'); # stored
256           $ticket->status('stalled'); # stored
257
258           # etc.
259
260         Do not forget to pass RT::Client::REST object to this method.
261

SEE ALSO

263       RT::Client::REST::Ticket, RT::Client::REST::SearchResult.
264

AUTHOR

266       Dean Hamstead <dean@fragfest.com.au>
267
269       This software is copyright (c) 2023, 2020 by Dmitri Tikhonov.
270
271       This is free software; you can redistribute it and/or modify it under
272       the same terms as the Perl 5 programming language system itself.
273
274
275
276perl v5.36.0                      2023-02-28       RT::Client::REST::Object(3)
Impressum