Qore RestHandler Module Reference  1.2
RestHandler.qm.dox.h
1 // -*- mode: c++; indent-tabs-mode: nil -*-
3 
4 /* RestHandler.qm Copyright (C) 2013 - 2017 Qore Technologies, s.r.o.
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 
337 namespace RestHandler {
340 
348 
349 public:
350 private:
351 
352 public:
353 
354  private :
357 
360 
363 
366 
369 
370 public:
371 
373 
387  constructor(hash n_cx, *hash n_ah);
388 
389 
391 
400  hash<HttpServer::HttpHandlerResponseInfo> getResponseHeaderMessage();
401 
402 
404 
414  nothing recv(hash v);
415 
416 
418 
421  auto send();
422 
423 
426 
427 
429  bool isPersistent();
430 
431 
433  setTimeout(timeout n_timeout_ms);
434 
435 
437  *int getTimeout();
438 
439 
441  streamError(hash n_ex);
442 
443 
445 
455 
457 
467  abstract nothing recvImpl(hash v);
468 
470 
473  abstract auto sendImpl();
474  };
475 
478 
479 public:
480  private :
482  bool deserialized;
483 
484 public:
485 
488 
489 
491  destructor();
492 
493 
494  // callback method for the response header; this calls @ref RestHandler::AbstractRestStreamRequestHandler::getResponseHeaderMessage() and returns the result
505 private:
506  hash<HttpServer::HttpHandlerResponseInfo> getResponseHeaderMessageImpl();
507 public:
508 
509 
511 
522 private:
523  nothing recvImpl(hash v);
524 public:
525 
526 
528 
532 private:
533  auto sendImpl();
534 public:
535 
536  };
537 
540 
541 public:
542 private:
543 
544 public:
545 
546  constructor();
547 
548 
550  abstract string name();
551 
553 
569  *AbstractRestClass subClass(string name, hash cx, *hash args);
570 
571 
573  hash<HttpServer::HttpHandlerResponseInfo> handleRequest(HttpListenerInterface listener, RestHandler rh, Socket s, *list cl, string mn, hash cx, *hash args);
574 
575 
577 
578 private:
579  hash<HttpServer::HttpHandlerResponseInfo> dispatchStream(HttpListenerInterface listener, RestHandler rh, Socket s, string mn, *hash ah, hash cx);
580 public:
581 
582 
584 
599 private:
600  hash<HttpServer::HttpHandlerResponseInfo> dispatch(RestHandler rh, string mn, *hash ah, hash cx);
601 public:
602 
603 
605 
606 private:
607  hash<HttpServer::HttpHandlerResponseInfo> unknownSubClassError(string n_name);
608 public:
609 
610  };
611 
613 
624 
625 public:
626  public :
628  const Err501 = new hash<HttpResponseInfo>((
629  "code": 501,
630  "body": "not implemented",
631  ));
632 
634  const Methods = (
635  "GET": "get",
636  "POST": "post",
637  "PUT": "put",
638  "DELETE": "del",
639  "OPTIONS": "options",
640  "PATCH": "patch",
641  );
642 
644  const MimeDataTypes = (
645  MimeTypeJsonRpc: (
646  "serialize": \make_json(),
647  "deserialize": \parse_json(),
648  ),
649  MimeTypeYaml: (
650  "serialize": \make_yaml(),
651  "deserialize": \parse_yaml(),
652  ),
653 
654  MimeTypeYamlRpc: (
655  "serialize": \make_yaml(),
656  "deserialize": \parse_yaml(),
657  ),
658  MimeTypeXml: (
659  "serialize": \make_xmlrpc_value(),
660  "deserialize": \parse_xmlrpc_value(),
661  ),
662  MimeTypeXmlApp: (
663  "serialize": string (auto v) {
664  switch (v.typeCode());
665 
666  return make_xml(("value": v));
667  },
668  "deserialize": hash (string xml) {
669  try {
670  return parse_xmlrpc_value(xml);
671  }
672  catch (hash<ExceptionInfo> ex);
673 
674  },
675  ),
677  "serialize": \mime_get_form_urlencoded_string(),
678  "deserialize": \mime_parse_form_urlencoded_string(),
679  ),
680  MimeTypeHtml: (
681  "serialize": string (auto body) { return sprintf("<pre>%N</pre>", body); },
682  ),
683  );
684 
685 public:
686 
687  private :
690 
692  Mutex mx();
693 
696 
697 public:
698 
700 
704 
705 
707  string name();
708 
709 
711 
732  auto handleExternalRequest(string method, string path, *hash body, hash cx = {});
733 
734 
736 
760  hash<HttpResponseInfo> handleRequest(HttpListenerInterface listener, Socket s, hash cx, hash hdr, *data b);
761 
762 
764  removeRootPath(reference<string> path);
765 
766 
768  requestDeserializationError(hash hdr, hash cx, string body);
769 
770 
772  responseSerializationError(hash cx, *hash aih, hash rv);
773 
774 
776  logInfo(string fmt);
777 
778 
780  logError(string fmt);
781 
782 
784  logDebug(string fmt);
785 
786 
788  addClass(AbstractRestClass cls);
789 
790 
792  hash get(hash cx, *hash ah);
793 
794 
796  static hash makeResponse(int code, auto body, *hash hdr);
797  };
798 };
799 
800 // private, unexported namespace
801 namespace Priv {
802  // dumHttpListenerInterface class
803 class DummyListenerInterface : public HttpListenerInterface {
804 
805 public:
806  addUserThreadContext(hash uctx);
807 
808 
809  auto removeUserThreadContext(*string k);
810 
811 
812  log(string fmt);
813 
814 
815  logError(string fmt);
816 
817  };
818 };
string sprintf(string fmt,...)
hash ch
class hash: name -> AbstractRestClass
Definition: RestHandler.qm.dox.h:689
*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:356
string mime_get_form_urlencoded_string(hash h)
hash< HttpServer::HttpHandlerResponseInfo > getResponseHeaderMessage()
this method returns the response message description hash by calling getResponseHeaderMessageImpl() ...
the RestHandler namespace contains all the objects in the RestHandler module
Definition: RestHandler.qm.dox.h:338
const MimeTypeJsonRpc
list list(...)
const MimeTypeFormUrlEncoded
hash mime_parse_form_urlencoded_string(string str)
const MimeTypeYamlRpc
nothing recv(hash v)
this method provides the callback method for receiving chunked data by calling recvImpl() ...
abstract auto sendImpl()
abstract callback method for sending chunked data
*hash ah
call argument hash
Definition: RestHandler.qm.dox.h:362
the base abstract class for REST stream request handlers
Definition: RestHandler.qm.dox.h:347
the base abstract class for REST handler classes
Definition: RestHandler.qm.dox.h:539
the base class for handling HTTP chunked requests and responses within the RestHandler infrastructure...
Definition: RestHandler.qm.dox.h:477
RestSchemaValidator::AbstractRestSchemaValidator validator
REST schema validator.
Definition: RestHandler.qm.dox.h:695
auto send()
this method provides the callback method for sending chunked data by calling sendImpl() ...
*int timeout_ms
socket I/O timeout in milliseconds
Definition: RestHandler.qm.dox.h:368
*code getPersistentClosedNotification()
returns a callable value in case a persistent connection is in progress; NOTHING if not; this method ...
bool isPersistent()
returns True if the connection is persistent; this method in the base class returns False by default ...
Definition: RestHandler.qm.dox.h:801
abstract hash getResponseHeaderMessageImpl()
this method should return the response message description hash
*hash ex
if an exception is raised in a callback then the exception hash is saved here
Definition: RestHandler.qm.dox.h:359
const MimeTypeHtml
hash hash(object obj)
hash rhdr
headers to add in the response
Definition: RestHandler.qm.dox.h:365
abstract nothing recvImpl(hash v)
abstract callback method for receiving chunked data
const MimeTypeXmlApp
constructor(hash n_cx, *hash n_ah)
creates the object with the given arguments
setTimeout(timeout n_timeout_ms)
sets the internal socket I/O timeout value in ms