1RT::Client::REST::ObjecUts(e3r)Contributed Perl DocumentRaTt:i:oCnlient::REST::Object(3)
2
6 RT::Client::REST::Object - base class for RT objects
7
9 version 0.60
10
12 # Create a new type
13 package RT::Client::REST::MyType;
14 use base qw(RT::Client::REST::Object);
16 sub _attributes {{
18 myattribute => {
19 validation => {
20 type => SCALAR,
21 },
22 },
23 }}
24 sub rt_type { "mytype" }
26 1;
28
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
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 list
41 If set to true, this is a list attribute. See "LIST ATTRIBUTE
42 PROPERTIES" below.
43 validation
45 A hash reference. This is passed to validation routines when
46 associated mutator is called. See Params::Validate for reference.
47 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 form2value
55 Convert form value (one that comes from the server) into attribute-
56 digestible format.
57 value2form
59 Convert value into REST form format.
60 Example:
62 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
87 List attributes have the following properties:
88 · When called as accessors, return a list of items
90 · When called as mutators, only accept an array reference
92 · Convenience methods "add_attr" and "delete_attr" are available. For
94 example:
95 # Get the list
97 my @requestors = $ticket->requestors;
98 # Replace with a new list
100 $ticket->requestors( [qw(dude@localhost)] );
101 # Add some random guys to the current list
103 $ticket->add_requestors('randomguy@localhost', 'evil@local');
104
106 id and parent_id are special attributes. They are used by various DB-
107 related methods and are especially relied upon by:
108 autostore
110 autosync
111 autoget
112
114 new
115 Constructor
116 _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 creator => {
125 validation => { type => SCALAR },
126 },
127 cc => {
128 list => 1,
129 validation => { type => ARRAYREF },
130 },
131 _mark_dirty($attrname)
133 Mark an attribute as dirty.
134 _dirty
136 Return the list of dirty attributes.
137 _mark_dirty_cf($attrname)
139 Mark an custom flag as dirty.
140 _dirty_cf
142 Return the list of dirty custom flags.
143 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 from_form
152 Set object's attributes from form received from RT server.
153 param($name, $value)
155 Set an arbitrary parameter.
156 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 rt
165 Get or set the 'rt' object, which should be of type RT::Client::REST.
166
168 The following are methods that have to do with reading, creating,
169 updating, and searching objects.
170 count
172 Takes the same arguments as "search()" but returns the actual count
173 of the found items. Throws the same exceptions.
174 retrieve
176 Retrieve object's attributes. Note that 'id' attribute must be set
177 for this to work.
178 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 limits
186 This is a reference to array containing hash references with limits
187 to apply to the search (think SQL limits).
188 orderby
190 Specifies attribute to sort the result by (in ascending order).
191 reverseorder
193 If set to a true value, sorts by attribute specified by orderby in
194 descending order.
195 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 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
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 my $rt = RT::Client::REST->new(%args);
212 # Make all tickets use this RT:
214 RT::Client::REST::Ticket->use_single_rt($rt);
215 # Now make all objects use it:
217 RT::Client::REST::Object->use_single_rt($rt);
218 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
222 the object goes out of scope.
223 # 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 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
233 is called with that object's special attributes (see "SPECIAL
234 ATTRIBUTES" above).
235 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 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
244 be pretty expensive.
245 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 RT::Client::REST::Ticket->be_transparent($rt);
253 my $ticket = RT::Client::REST::Ticket->new(id => $id); # retrieved
255 $ticket->add_cc('you@localhost.localdomain'); # stored
256 $ticket->status('stalled'); # stored
257 # etc.
259 Do not forget to pass RT::Client::REST object to this method.
261
263 RT::Client::REST::Ticket, RT::Client::REST::SearchResult.
264
266 Dmitri Tikhonov
267
269 This software is copyright (c) 2020, 2018 by Dmitri Tikhonov.
270 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.
273perl v5.32.0 2020-07-28 RT::Client::REST::Object(3)