LP#1729610: return new OpenSRF status if backlog queue fills up
[OpenSRF.git] / src / perl / lib / OpenSRF / DomainObject / oilsResponse.pm
1 package OpenSRF::DomainObject::oilsResponse;
2 use vars qw/@EXPORT_OK %EXPORT_TAGS/;
3 use Exporter;
4 use OpenSRF::Utils::JSON;
5 use base qw/Exporter/;
6 use OpenSRF::Utils::Logger qw/:level/;
7
8 OpenSRF::Utils::JSON->register_class_hint( hint => 'osrfResponse', name => 'OpenSRF::DomainObject::oilsResponse', type => 'hash' );
9
10 BEGIN {
11 @EXPORT_OK = qw/STATUS_CONTINUE STATUS_OK STATUS_ACCEPTED
12                                         STATUS_BADREQUEST STATUS_UNAUTHORIZED STATUS_FORBIDDEN
13                                         STATUS_NOTFOUND STATUS_NOTALLOWED STATUS_TIMEOUT
14                                         STATUS_INTERNALSERVERERROR STATUS_NOTIMPLEMENTED
15                                         STATUS_SERVICEUNAVAILABLE
16                                         STATUS_VERSIONNOTSUPPORTED STATUS_REDIRECTED 
17                                         STATUS_EXPFAILED STATUS_COMPLETE STATUS_PARTIAL
18                                         STATUS_NOCONTENT/;
19
20 %EXPORT_TAGS = (
21         status => [ qw/STATUS_CONTINUE STATUS_OK STATUS_ACCEPTED
22                                         STATUS_BADREQUEST STATUS_UNAUTHORIZED STATUS_FORBIDDEN
23                                         STATUS_NOTFOUND STATUS_NOTALLOWED STATUS_TIMEOUT
24                                         STATUS_INTERNALSERVERERROR STATUS_NOTIMPLEMENTED
25                                         STATUS_SERVICEUNAVAILABLE
26                                         STATUS_VERSIONNOTSUPPORTED STATUS_REDIRECTED 
27                                         STATUS_EXPFAILED STATUS_COMPLETE STATUS_PARTIAL
28                                         STATUS_NOCONTENT/ ],
29 );
30
31 }
32
33 =head1 NAME
34
35 OpenSRF::DomainObject::oilsResponse
36
37 =head1 SYNOPSIS
38
39 use OpenSRF::DomainObject::oilsResponse qw/:status/;
40
41 my $resp = OpenSRF::DomainObject::oilsResponse->new;
42
43 $resp->status( 'a status message' );
44
45 $resp->statusCode( STATUS_CONTINUE );
46
47 $client->respond( $resp );
48
49 =head1 ABSTRACT
50
51 OpenSRF::DomainObject::oilsResponse implements the base class for all Application
52 layer messages send between the client and server.
53
54 =cut
55
56 sub STATUS_CONTINUE             { return 100 }
57
58 sub STATUS_OK                   { return 200 }
59 sub STATUS_ACCEPTED             { return 202 }
60 sub STATUS_COMPLETE             { return 205 }
61
62 sub STATUS_PARTIAL              { return 206 }
63 sub STATUS_NOCONTENT    { return 204 }
64
65 sub STATUS_REDIRECTED   { return 307 }
66
67 sub STATUS_BADREQUEST   { return 400 }
68 sub STATUS_UNAUTHORIZED { return 401 }
69 sub STATUS_FORBIDDEN            { return 403 }
70 sub STATUS_NOTFOUND             { return 404 }
71 sub STATUS_NOTALLOWED   { return 405 }
72 sub STATUS_TIMEOUT              { return 408 }
73 sub STATUS_EXPFAILED            { return 417 }
74
75 sub STATUS_INTERNALSERVERERROR  { return 500 }
76 sub STATUS_NOTIMPLEMENTED                       { return 501 }
77 sub STATUS_SERVICEUNAVAILABLE   { return 503 }
78 sub STATUS_VERSIONNOTSUPPORTED  { return 505 }
79
80 my $log = 'OpenSRF::Utils::Logger';
81
82 sub toString {
83         my $self = shift;
84         return OpenSRF::Utils::JSON->perl2JSON($self);
85 }
86
87 sub new {
88         my $class = shift;
89         $class = ref($class) || $class;
90
91         my $default_status = eval "\$${class}::status";
92         my $default_statusCode = eval "\$${class}::statusCode";
93
94         my %args = (    status => $default_status,
95                         statusCode => $default_statusCode,
96                         @_ );
97
98         return bless( \%args => $class );
99 }
100
101 sub status {
102         my $self = shift;
103         my $val = shift;
104         $self->{status} = $val if (defined $val);
105         return $self->{status};
106 }
107
108 sub statusCode {
109         my $self = shift;
110         my $val = shift;
111         $self->{statusCode} = $val if (defined $val);
112         return $self->{statusCode};
113 }
114
115 #-------------------------------------------------------------------------------
116
117 package OpenSRF::DomainObject::oilsStatus;
118 use OpenSRF::DomainObject::oilsResponse qw/:status/;
119 use base 'OpenSRF::DomainObject::oilsResponse';
120 use vars qw/$status $statusCode/;
121 OpenSRF::Utils::JSON->register_class_hint( hint => 'osrfStatus', name => 'OpenSRF::DomainObject::oilsStatus', type => 'hash' );
122
123 =head1 NAME
124
125 OpenSRF::DomainObject::oilsException
126
127 =head1 SYNOPSIS
128
129 use OpenSRF::DomainObject::oilsResponse;
130
131 ...
132
133 # something happens.
134
135 $client->status( OpenSRF::DomainObject::oilsStatus->new );
136
137 =head1 ABSTRACT
138
139 The base class for Status messages sent between client and server.  This
140 is implemented on top of the C<OpenSRF::DomainObject::oilsResponse> class, and 
141 sets the default B<status> to C<Status> and B<statusCode> to C<STATUS_OK>.
142
143 =cut
144
145 $status = 'Status';
146 $statusCode = STATUS_OK;
147
148 #-------------------------------------------------------------------------------
149
150 package OpenSRF::DomainObject::oilsConnectStatus;
151 use OpenSRF::DomainObject::oilsResponse qw/:status/;
152 use base 'OpenSRF::DomainObject::oilsStatus';
153 use vars qw/$status $statusCode/;
154 OpenSRF::Utils::JSON->register_class_hint( hint => 'osrfConnectStatus', name => 'OpenSRF::DomainObject::oilsConnectStatus', type => 'hash' );
155
156 =head1 NAME
157
158 OpenSRF::DomainObject::oilsConnectStatus
159
160 =head1 SYNOPSIS
161
162 use OpenSRF::DomainObject::oilsResponse;
163
164 ...
165
166 # something happens.
167
168 $client->status( new OpenSRF::DomainObject::oilsConnectStatus );
169
170 =head1 ABSTRACT
171
172 The class for Stati relating to the connection status of a session.  This
173 is implemented on top of the C<OpenSRF::DomainObject::oilsStatus> class, and 
174 sets the default B<status> to C<Connection Successful> and B<statusCode> to C<STATUS_OK>.
175
176 =head1 SEE ALSO
177
178 B<OpenSRF::DomainObject::oilsStatus>
179
180 =cut
181
182 $status = 'Connection Successful';
183 $statusCode = STATUS_OK;
184
185 #-------------------------------------------------------------------------------
186
187 package OpenSRF::DomainObject::oilsContinueStatus;
188 use OpenSRF::DomainObject::oilsResponse qw/:status/;
189 use base 'OpenSRF::DomainObject::oilsStatus';
190 use vars qw/$status $statusCode/;
191 OpenSRF::Utils::JSON->register_class_hint( hint => 'osrfContinueStatus', name => 'OpenSRF::DomainObject::oilsContinueStatus', type => 'hash' );
192
193 =head1 NAME
194
195 OpenSRF::DomainObject::oilsContinueStatus
196
197 =head1 SYNOPSIS
198
199 use OpenSRF::DomainObject::oilsResponse;
200
201 ...
202
203 # something happens.
204
205 $client->status( new OpenSRF::DomainObject::oilsContinueStatus );
206
207 =head1 ABSTRACT
208
209 Implements the STATUS_CONTINUE message, informing the client that it should
210 continue to wait for a response to its request.
211
212 =head1 SEE ALSO
213
214 B<OpenSRF::DomainObject::oilsStatus>
215
216 =cut
217
218 $status = 'Please hold.  Creating response...';
219 $statusCode = STATUS_CONTINUE;
220
221 1;
222
223 #-------------------------------------------------------------------------------
224
225 package OpenSRF::DomainObject::oilsResult;
226 use OpenSRF::DomainObject::oilsResponse qw/:status/;
227 use base 'OpenSRF::DomainObject::oilsResponse';
228 use vars qw/$status $statusCode/;
229 OpenSRF::Utils::JSON->register_class_hint( hint => 'osrfResult', name => 'OpenSRF::DomainObject::oilsResult', type => 'hash' );
230
231
232 $status = 'OK';
233 $statusCode = STATUS_OK;
234
235 =head1 NAME
236
237 OpenSRF::DomainObject::oilsResult
238
239 =head1 SYNOPSIS
240
241 use OpenSRF::DomainObject::oilsResponse;
242
243  .... do stuff, create $object ...
244
245 my $res = OpenSRF::DomainObject::oilsResult->new;
246
247 $res->content($object)
248
249 $session->respond( $res );
250
251 =head1 ABSTRACT
252
253 This is the base class for encapuslating RESULT messages send from the server
254 to a client.  It is a subclass of B<OpenSRF::DomainObject::oilsResponse>, and
255 sets B<status> to C<OK> and B<statusCode> to C<STATUS_OK>.
256
257 =head1 METHODS
258
259 =head2 OpenSRF::DomainObject::oilsMessage->content( [$new_content] )
260
261 =over 4
262
263 Sets or gets the content of the response.  This should be exactly one object
264 of (sub)type domainObject or domainObjectCollection.
265
266 =back
267
268 =cut
269
270 sub content {
271         my $self = shift;
272         my $val = shift;
273
274         $self->{content} = $val if (defined $val);
275         return $self->{content};
276 }
277
278 =head1 SEE ALSO
279
280 B<OpenSRF::DomainObject::oilsResponse>
281
282 =cut
283
284 1;
285
286 #-------------------------------------------------------------------------------
287
288 package OpenSRF::DomainObject::oilsResult::Partial;
289 use OpenSRF::DomainObject::oilsResponse qw/:status/;
290 use base 'OpenSRF::DomainObject::oilsResult';
291 use vars qw/$status $statusCode/;
292 OpenSRF::Utils::JSON->register_class_hint(
293     hint => 'osrfResultPartial',
294     name => 'OpenSRF::DomainObject::oilsResult::Partial',
295     type => 'hash');
296
297
298 $status = 'Partial Response';
299 $statusCode = STATUS_PARTIAL;
300
301 =head1 NAME
302
303 OpenSRF::DomainObject::oilsResult::Partial
304
305 =head1 SYNOPSIS
306
307 This class is used internally to break apart large OpenSRF messages into small
308 chunks, to reduce the maximum possible stanza size when sending a message over
309 XMPP.
310
311 =cut
312
313 sub content {
314         my $self = shift;
315         my $val = shift;
316
317         $self->{content} = $val if (defined $val);
318         return $self->{content};
319 }
320
321 =head1 SEE ALSO
322
323 B<OpenSRF::DomainObject::oilsResponse>
324
325 =cut
326
327 1;
328
329 #-------------------------------------------------------------------------------
330
331 package OpenSRF::DomainObject::oilsResult::PartialComplete;
332 use OpenSRF::DomainObject::oilsResponse qw/:status/;
333 use base 'OpenSRF::DomainObject::oilsResult';
334 use vars qw/$status $statusCode/;
335 OpenSRF::Utils::JSON->register_class_hint( 
336     hint => 'osrfResultPartialComplete',
337     name => 'OpenSRF::DomainObject::oilsResult::PartialComplete',
338     type => 'hash');
339
340
341 $status = 'Partial Response Finalized';
342 $statusCode = STATUS_NOCONTENT;
343
344 =head1 NAME
345
346 OpenSRF::DomainObject::oilsResult::PartialComplete
347
348 =head1 SYNOPSIS
349
350 This class is used internally to mark the end of a stream of small partial
351 OpenSRF messages of type OpenSRF::DomainObject::oilsResult::Partial.
352
353 =cut
354
355 sub content {
356         my $self = shift;
357         my $val = shift;
358
359         $self->{content} = $val if (defined $val);
360         return $self->{content};
361 }
362
363 =head1 SEE ALSO
364
365 B<OpenSRF::DomainObject::oilsResponse>
366
367 =cut
368
369 1;
370
371 #-------------------------------------------------------------------------------
372
373 package OpenSRF::DomainObject::oilsException;
374 use OpenSRF::DomainObject::oilsResponse qw/:status/;
375 use OpenSRF::EX;
376 use base qw/OpenSRF::EX OpenSRF::DomainObject::oilsResponse/;
377 use vars qw/$status $statusCode/;
378 use Error;
379 OpenSRF::Utils::JSON->register_class_hint( hint => 'osrfException', name => 'OpenSRF::DomainObject::oilsException', type => 'hash' );
380
381 sub message {
382         my $self = shift;
383         return '<' . $self->statusCode . '>  ' . $self->status;
384 }
385
386 sub new {
387         my $class = shift;
388         return $class->OpenSRF::DomainObject::oilsResponse::new( @_ );
389 }
390
391
392 =head1 NAME
393
394 OpenSRF::DomainObject::oilsException
395
396 =head1 SYNOPSIS
397
398 use OpenSRF::DomainObject::oilsResponse;
399
400 ...
401
402 # something breaks.
403
404 $client->send( 'ERROR', OpenSRF::DomainObject::oilsException->new( status => "ARRRRRRG!" ) );
405
406 =head1 ABSTRACT
407
408 The base class for Exception messages sent between client and server.  This
409 is implemented on top of the C<OpenSRF::DomainObject::oilsResponse> class, and 
410 sets the default B<status> to C<Exception occurred> and B<statusCode> to C<STATUS_BADREQUEST>.
411
412 =cut
413
414 $status = 'Exception occurred';
415 $statusCode = STATUS_INTERNALSERVERERROR;
416
417 #-------------------------------------------------------------------------------
418
419 package OpenSRF::DomainObject::oilsConnectException;
420 use OpenSRF::DomainObject::oilsResponse qw/:status/;
421 use OpenSRF::EX;
422 use base qw/OpenSRF::DomainObject::oilsException OpenSRF::EX::ERROR/;
423 use vars qw/$status $statusCode/;
424 OpenSRF::Utils::JSON->register_class_hint( hint => 'osrfConnectException', name => 'OpenSRF::DomainObject::oilsConnectException', type => 'hash' );
425
426 =head1 NAME
427
428 OpenSRF::DomainObject::oilsConnectException
429
430 =head1 SYNOPSIS
431
432 use OpenSRF::DomainObject::oilsResponse;
433
434 ...
435
436 # something breaks while connecting.
437
438 $client->send( 'ERROR', new OpenSRF::DomainObject::oilsConnectException );
439
440 =head1 ABSTRACT
441
442 The class for Exceptions that occur durring the B<CONNECT> phase of a session.  This
443 is implemented on top of the C<OpenSRF::DomainObject::oilsException> class, and 
444 sets the default B<status> to C<Connect Request Failed> and B<statusCode> to C<STATUS_FORBIDDEN>.
445
446 =head1 SEE ALSO
447
448 B<OpenSRF::DomainObject::oilsException>
449
450 =cut
451
452
453 $status = 'Connect Request Failed';
454 $statusCode = STATUS_FORBIDDEN;
455
456 #-------------------------------------------------------------------------------
457
458 package OpenSRF::DomainObject::oilsMethodException;
459 use OpenSRF::DomainObject::oilsResponse qw/:status/;
460 use base 'OpenSRF::DomainObject::oilsException';
461 use vars qw/$status $statusCode/;
462 OpenSRF::Utils::JSON->register_class_hint( hint => 'osrfMethodException', name => 'OpenSRF::DomainObject::oilsMethodException', type => 'hash' );
463
464 =head1 NAME
465
466 OpenSRF::DomainObject::oilsMethodException
467
468 =head1 SYNOPSIS
469
470 use OpenSRF::DomainObject::oilsResponse;
471
472 ...
473
474 # something breaks while looking up or starting
475 # a method call.
476
477 $client->send( 'ERROR', new OpenSRF::DomainObject::oilsMethodException );
478
479 =head1 ABSTRACT
480
481 The class for Exceptions that occur during the B<CONNECT> phase of a session.  This
482 is implemented on top of the C<OpenSRF::DomainObject::oilsException> class, and 
483 sets the default B<status> to C<Connect Request Failed> and B<statusCode> to C<STATUS_NOTFOUND>.
484
485 =head1 SEE ALSO
486
487 B<OpenSRF::DomainObject::oilsException>
488
489 =cut
490
491
492 $status = 'A server error occurred during method execution';
493 $statusCode = STATUS_INTERNALSERVERERROR;
494
495 # -------------------------------------------
496
497 package OpenSRF::DomainObject::oilsServerError;
498 use OpenSRF::DomainObject::oilsResponse qw/:status/;
499 use base 'OpenSRF::DomainObject::oilsException';
500 use vars qw/$status $statusCode/;
501 OpenSRF::Utils::JSON->register_class_hint( hint => 'osrfServerError', name => 'OpenSRF::DomainObject::oilsServerError', type => 'hash' );
502
503 $status = 'Internal Server Error';
504 $statusCode = STATUS_INTERNALSERVERERROR;
505
506 # -------------------------------------------
507
508 package OpenSRF::DomainObject::oilsBrokenSession;
509 use OpenSRF::DomainObject::oilsResponse qw/:status/;
510 use OpenSRF::EX;
511 use base qw/OpenSRF::DomainObject::oilsException OpenSRF::EX::ERROR/;
512 use vars qw/$status $statusCode/;
513 OpenSRF::Utils::JSON->register_class_hint( hint => 'osrfBrokenSession', name => 'OpenSRF::DomainObject::oilsBrokenSession', type => 'hash' );
514 $status = "Request on Disconnected Session";
515 $statusCode = STATUS_EXPFAILED;
516
517 #-------------------------------------------------------------------------------
518
519 package OpenSRF::DomainObject::oilsXMLParseError;
520 use OpenSRF::DomainObject::oilsResponse qw/:status/;
521 use OpenSRF::EX;
522 use base qw/OpenSRF::DomainObject::oilsException OpenSRF::EX::ERROR/;
523 use vars qw/$status $statusCode/;
524 OpenSRF::Utils::JSON->register_class_hint( hint => 'osrfXMLParseError', name => 'OpenSRF::DomainObject::oilsXMLParseError', type => 'hash' );
525 $status = "XML Parse Error";
526 $statusCode = STATUS_EXPFAILED;
527
528 #-------------------------------------------------------------------------------
529
530 package OpenSRF::DomainObject::oilsAuthException;
531 use OpenSRF::DomainObject::oilsResponse qw/:status/;
532 use OpenSRF::EX;
533 use base qw/OpenSRF::DomainObject::oilsException OpenSRF::EX::ERROR/;
534 OpenSRF::Utils::JSON->register_class_hint( hint => 'osrfAuthException', name => 'OpenSRF::DomainObject::oilsAuthException', type => 'hash' );
535 use vars qw/$status $statusCode/;
536 $status = "Authentication Failure";
537 $statusCode = STATUS_FORBIDDEN;
538
539 1;