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 # Create a new type
10 package RT::Client::REST::MyType;
11 use base qw(RT::Client::REST::Object);
13 sub _attributes {{
15 myattribute => {
16 validation => {
17 type => SCALAR,
18 },
19 },
20 }}
21 sub rt_type { "mytype" }
23 1;
25
27 The RT::Client::REST::Object module is a superclass providing a whole
28 bunch of class and object methods in order to streamline the
29 development of RT's REST client interface.
30
32 Attributes are defined by method "_attributes" that should be defined
33 in your class. This method returns a reference to a hash whose keys
34 are the attributes. The values of the hash are attribute settings,
35 which are as follows:
36 list
38 If set to true, this is a list attribute. See "LIST ATTRIBUTE
39 PROPERTIES" below.
40 validation
42 A hash reference. This is passed to validation routines when
43 associated mutator is called. See Params::Validate for reference.
44 rest_name
46 This specifies this attribute's REST name. For example, attribute
47 "final_priority" corresponds to RT REST's "FinalPriority". This
48 option may be omitted if the two only differ in first letter
49 capitalization.
50 form2value
52 Convert form value (one that comes from the server) into attribute-
53 digestible format.
54 value2form
56 Convert value into REST form format.
57 Example:
59 sub _attributes {{
61 id => {
62 validation => {
63 type => SCALAR,
64 regex => qr/^\d+$/,
65 },
66 form2value => sub {
67 shift =~ m~^ticket/(\d+)$~i;
68 return $1;
69 },
70 value2form => sub {
71 return 'ticket/' . shift;
72 },
73 },
74 admin_cc => {
75 validation => {
76 type => ARRAYREF,
77 },
78 list => 1,
79 rest_name => 'AdminCc',
80 },
81 }}
82
84 List attributes have the following properties:
85 · When called as accessors, return a list of items
87 · When called as mutators, only accept an array reference
89 · Convenience methods "add_attr" and "delete_attr" are available. For
91 example:
92 # Get the list
94 my @requestors = $ticket->requestors;
95 # Replace with a new list
97 $ticket->requestors( [qw(dude@localhost)] );
98 # Add some random guys to the current list
100 $ticket->add_requestors('randomguy@localhost', 'evil@local');
101
103 id and parent_id are special attributes. They are used by various DB-
104 related methods and are especially relied upon by autostore, autosync,
105 and autoget features.
106
108 new
109 Constructor
110 _generate_methods
112 This class method generates accessors and mutators based on
113 _attributes method which your class should provide. For items that
114 are lists, 'add_' and 'delete_' methods are created. For instance,
115 the following two attributes specified in _attributes will generate
116 methods 'creator', 'cc', 'add_cc', and 'delete_cc':
117 creator => {
119 validation => { type => SCALAR },
120 },
121 cc => {
122 list => 1,
123 validation => { type => ARRAYREF },
124 },
125 _mark_dirty($attrname)
127 Mark an attribute as dirty.
128 _dirty
130 Return the list of dirty attributes.
131 _mark_dirty_cf($attrname)
133 Mark an custom flag as dirty.
134 _dirty_cf
136 Return the list of dirty custom flags.
137 to_form($all)
139 Convert the object to 'form' (used by REST protocol). This is done
140 based on _attributes method. If $all is true, create a form from all
141 of the object's attributes and custom flags, otherwise use only dirty
142 (see _dirty method) attributes and custom flags. Defaults to the
143 latter.
144 from_form
146 Set object's attributes from form received from RT server.
147 param($name, $value)
149 Set an arbitrary parameter.
150 cf([$name, [$value]])
152 Given no arguments, returns the list of custom field names. With one
153 argument, returns the value of custom field $name. With two
154 arguments, sets custom field $name to $value. Given a reference to a
155 hash, uses it as a list of custom fields and their values, returning
156 the new list of all custom field names.
157 rt
159 Get or set the 'rt' object, which should be of type RT::Client::REST.
160
162 The following are methods that have to do with reading, creating,
163 updating, and searching objects.
164 count
166 Takes the same arguments as "search()" but returns the actual count
167 of the found items. Throws the same exceptions.
168 retrieve
170 Retrieve object's attributes. Note that 'id' attribute must be set
171 for this to work.
172 search (%opts)
174 This method is used for searching objects. It returns an object of
175 type RT::Client::REST::SearchResult, which can then be used to
176 process results. %opts is a list of key-value pairs, which are as
177 follows:
178 limits
180 This is a reference to array containing hash references with limits
181 to apply to the search (think SQL limits).
182 orderby
184 Specifies attribute to sort the result by (in ascending order).
185 reverseorder
187 If set to a true value, sorts by attribute specified by orderby in
188 descending order.
189 If the client cannot construct the query from the specified
191 arguments, or if the server cannot make it out,
192 "RT::Client::REST::Object::InvalidSearchParametersException" is
193 thrown.
194 store
196 Store the object. If 'id' is set, this is an update; otherwise, a
197 new object is created and the 'id' attribute is set. Note that only
198 changed (dirty) attributes are sent to the server.
199
201 use_single_rt
202 This method takes a single argument -- RT::Client::REST object and
203 makes this class use it for all instantiations. For example:
204 my $rt = RT::Client::REST->new(%args);
206 # Make all tickets use this RT:
208 RT::Client::REST::Ticket->use_single_rt($rt);
209 # Now make all objects use it:
211 RT::Client::REST::Object->use_single_rt($rt);
212 use_autostore
214 Turn autostoring on and off. Autostoring means that you do not have
215 to explicitly call "store()" on an object - it will be called when
216 the object goes out of scope.
217 # Autostore tickets:
219 RT::Client::REST::Ticket->use_autostore(1);
220 my $ticket = RT::Client::REST::Ticket->new(%opts)->retrieve;
221 $ticket->priority(10);
222 # Don't have to call store().
223 use_autoget
225 Turn autoget feature on or off (off by default). When set to on,
226 "retrieve()" will be automatically called from the constructor if it
227 is called with that object's special attributes (see "SPECIAL
228 ATTRIBUTES" above).
229 RT::Client::Ticket->use_autoget(1);
231 my $ticket = RT::Client::Ticket->new(id => 1);
232 # Now all attributes are available:
233 my $subject = $ticket->subject;
234 use_autosync
236 Turn autosync feature on or off (off by default). When set, every
237 time an attribute is changed, "store()" method is invoked. This may
238 be pretty expensive.
239 be_transparent
241 This turns on autosync and autoget. Transparency is a neat idea, but
242 it may be expensive and slow. Depending on your circumstances, you
243 may want a finer control of your objects. Transparency makes
244 "retrieve()" and "store()" calls invisible:
245 RT::Client::REST::Ticket->be_transparent($rt);
247 my $ticket = RT::Client::REST::Ticket->new(id => $id); # retrieved
249 $ticket->add_cc('you@localhost.localdomain'); # stored
250 $ticket->status('stalled'); # stored
251 # etc.
253 Do not forget to pass RT::Client::REST object to this method.
255
257 RT::Client::REST::Ticket, RT::Client::REST::SearchResult.
258
260 Dmitri Tikhonov <dtikhonov@yahoo.com>
261perl v5.12.0 2008-01-25 RT::Client::REST::Object(3)