Qore RestHandler Module Reference  1.1
RestHandler.qm.dox.h
1 // -*- mode: c++; indent-tabs-mode: nil -*-
3 
4 /* RestHandler.qm Copyright (C) 2013 - 2016 Qore Technologies, sro
5 
6  Permission is hereby granted, free of charge, to any person obtaining a
7  copy of this software and associated documentation files (the "Software"),
8  to deal in the Software without restriction, including without limitation
9  the rights to use, copy, modify, merge, publish, distribute, sublicense,
10  and/or sell copies of the Software, and to permit persons to whom the
11  Software is furnished to do so, subject to the following conditions:
12 
13  The above copyright notice and this permission notice shall be included in
14  all copies or substantial portions of the Software.
15 
16  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
22  DEALINGS IN THE SOFTWARE.
23 */
24 
25 // minimum qore version
26 
27 // use new-style
28 
29 // require type definitions everywhere
30 
31 // enable all warnings
32 
33 
34 
35 
36 
37 
316 namespace RestHandler {
319 
327 
328 public:
329 private:
330 
331 public:
332 
333  private :
336 
339 
342 
345 
348 
349 public:
350 
352 
365  constructor(hash n_cx, *hash n_ah);
366 
367 
369 
379 
380 
382 
392  nothing recv(hash v);
393 
394 
396 
399  any send();
400 
401 
404 
405 
407  bool isPersistent();
408 
409 
411  setTimeout(timeout n_timeout_ms);
412 
413 
415  *int getTimeout();
416 
417 
419  streamError(hash n_ex);
420 
421 
423 
433 
435 
445  abstract nothing recvImpl(hash v);
446 
448 
451  abstract any sendImpl();
452  };
453 
456 
457 public:
458  private :
460  bool deserialized;
461 
462 public:
463 
466 
467 
469  destructor();
470 
471 
472  // callback method for the response header; this calls @ref RestHandler::AbstractRestStreamRequestHandler::getResponseHeaderMessage() and returns the result
483 
484 
486 
496  private nothing recvImpl(hash v);
497 
498 
500 
503  private any sendImpl();
504 
505  };
506 
509 
510 public:
511 private:
512 
513 public:
514 
515  constructor();
516 
517 
519  abstract string name();
520 
522 
538  *AbstractRestClass subClass(string name, hash cx, *hash args);
539 
540 
542  hash handleRequest(HttpListenerInterface listener, RestHandler rh, Socket s, *list cl, string mn, hash cx, *hash args);
543 
544 
546  private hash dispatchStream(HttpListenerInterface listener, RestHandler rh, Socket s, string mn, *hash ah, hash cx);
547 
548 
550  private hash dispatch(RestHandler rh, string mn, *hash ah, hash cx);
551 
552 
554  private hash unknownSubClassError(string n_name);
555 
556  };
557 
559 
570 
571 public:
572  public :
574  const Err501 = (
575  "code": 501,
576  "body": "not implemented",
577  );
578 
580  const Methods = (
581  "GET": "get",
582  "POST": "post",
583  "PUT": "put",
584  "DELETE": "del",
585  "OPTIONS": "options",
586  );
587 
589  const MimeDataTypes = (
590  MimeTypeJsonRpc: (
591  "serialize": \make_json(),
592  "deserialize": \parse_json(),
593  ),
594  MimeTypeYaml: (
595  "serialize": \make_yaml(),
596  "deserialize": \parse_yaml(),
597  ),
598 
599  MimeTypeYamlRpc: (
600  "serialize": \make_yaml(),
601  "deserialize": \parse_yaml(),
602  ),
603  MimeTypeXml: (
604  "serialize": \make_xmlrpc_value(),
605  "deserialize": \parse_xmlrpc_value(),
606  ),
607  MimeTypeHtml: (
608  "serialize": string (any body) { return sprintf("<pre>%N</pre>", body); },
609  ),
610  );
611 
612 public:
613 
614  private :
617 
619  Mutex mx();
620 
621 public:
622 
624 
626  constructor(*HttpServer::AbstractAuthenticator auth) ;
627 
628 
630  string name();
631 
632 
634 
656  hash handleRequest(HttpListenerInterface listener, Socket s, hash cx, hash hdr, *data b);
657 
658 
660  removeRootPath(reference path);
661 
662 
664  requestDeserializationError(hash hdr, hash cx, string body);
665 
666 
668  responseSerializationError(hash cx, *hash aih, hash rv);
669 
670 
672  logInfo(string fmt);
673 
674 
676  logError(string fmt);
677 
678 
680  logDebug(string fmt);
681 
682 
684  addClass(AbstractRestClass cls);
685 
686 
688  hash get(hash cx, *hash ah);
689 
690 
692  static hash makeResponse(int code, any body, *hash hdr);
693  };
694 };
string sprintf(string fmt,...)
hash ch
class hash: name -> AbstractRestClass
Definition: RestHandler.qm.dox.h:616
*int getTimeout()
returns the timeout in milliseconds or NOTHING if no timeout is set
const MimeTypeYaml
streamError(hash n_ex)
registers stream errors in the send operation with the stream handler if no error is already present ...
const MimeTypeXml
hash cx
call context hash
Definition: RestHandler.qm.dox.h:335
the RestHandler namespace contains all the objects in the RestHandler module
Definition: RestHandler.qm.dox.h:317
AbstractHttpRequestHandler handler
const MimeTypeJsonRpc
destructor()
destroys the object and updates the request handler about the status of the persistent connection ...
abstract any sendImpl()
abstract callback method for sending chunked data
list list(...)
const MimeTypeYamlRpc
private nothing recvImpl(hash v)
callback method for receiving chunked data; this calls RestHandler::AbstractRestStreamRequestHandler:...
nothing recv(hash v)
this method provides the callback method for receiving chunked data by calling recvImpl() ...
*AbstractRestClass subClass(string name, hash cx, *hash args)
this method will be called to find a sub-class (ie with GET /invoices/1 - if this class represents "i...
*hash ah
call argument hash
Definition: RestHandler.qm.dox.h:341
the base abstract class for REST stream request handlers
Definition: RestHandler.qm.dox.h:326
HttpListenerInterface listener
constructor(RestHandler::AbstractRestStreamRequestHandler n_stream, HttpServer::HttpListenerInterface listener, HttpServer::AbstractHttpRequestHandler handler, Socket s, hash cx, hash hdr, any body)
creates the object with the given attributes
the base abstract class for REST handler classes
Definition: RestHandler.qm.dox.h:508
private hash getResponseHeaderMessageImpl()
the base class for handling HTTP chunked requests and responses within the RestHandler infrastructure...
Definition: RestHandler.qm.dox.h:455
*int timeout_ms
socket I/O timeout in milliseconds
Definition: RestHandler.qm.dox.h:347
hash getResponseHeaderMessage()
this method returns the response message description hash by calling getResponseHeaderMessageImpl() ...
*code getPersistentClosedNotification()
returns a callable value in case a persistent connection is in progress; NOTHING if not; this method ...
private any sendImpl()
callback method for sending chunked data; this calls RestHandler::AbstractRestStreamRequestHandler::s...
private hash dispatchStream(HttpListenerInterface listener, RestHandler rh, Socket s, string mn, *hash ah, hash cx)
this method is called to dispatch streamed requests on the given object
bool isPersistent()
returns True if the connection is persistent; this method in the base class returns False by default ...
private hash unknownSubClassError(string n_name)
throws a "REST-CLASS-ERROR" exception when a request tries to access an unknown subclass ...
abstract string name()
this provides the name of the REST class
abstract hash getResponseHeaderMessageImpl()
this method should return the response message description hash
private hash dispatch(RestHandler rh, string mn, *hash ah, hash cx)
this method is called to dispatch requests on the given object
*hash ex
if an exception is raised in a callback then the exception hash is saved here
Definition: RestHandler.qm.dox.h:338
const MimeTypeHtml
hash hash(object obj)
hash rhdr
headers to add in the response
Definition: RestHandler.qm.dox.h:344
abstract nothing recvImpl(hash v)
abstract callback method for receiving chunked data
any send()
this method provides the callback method for sending chunked data by calling sendImpl() ...
constructor(hash n_cx, *hash n_ah)
creates the object with the given arguments
hash handleRequest(HttpListenerInterface listener, RestHandler rh, Socket s, *list cl, string mn, hash cx, *hash args)
this method is called by the RestHandler class to match the right object with incoming requests ...
setTimeout(timeout n_timeout_ms)
sets the internal socket I/O timeout value in ms