Qore RestHandler Module Reference  1.2.1
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 
344 namespace RestHandler {
347 
355 
356 public:
357 private:
358 
359 public:
360 
361  private :
364 
367 
370 
373 
376 
377 public:
378 
380 
394  constructor(hash n_cx, *hash n_ah);
395 
396 
398 
407  hash<HttpServer::HttpHandlerResponseInfo> getResponseHeaderMessage();
408 
409 
411 
421  nothing recv(hash v);
422 
423 
425 
428  auto send();
429 
430 
433 
434 
436  bool isPersistent();
437 
438 
440  setTimeout(timeout n_timeout_ms);
441 
442 
444  *int getTimeout();
445 
446 
448  streamError(hash n_ex);
449 
450 
452 
462 
464 
474  abstract nothing recvImpl(hash v);
475 
477 
480  abstract auto sendImpl();
481  };
482 
485 
486 public:
487  private :
489  bool deserialized;
490 
491 public:
492 
495 
496 
498  destructor();
499 
500 
501  // callback method for the response header; this calls @ref RestHandler::AbstractRestStreamRequestHandler::getResponseHeaderMessage() and returns the result
512 private:
513  hash<HttpServer::HttpHandlerResponseInfo> getResponseHeaderMessageImpl();
514 public:
515 
516 
518 
529 private:
530  nothing recvImpl(hash v);
531 public:
532 
533 
535 
539 private:
540  auto sendImpl();
541 public:
542 
543  };
544 
547 
548 public:
549 private:
550 
551 public:
552 
553  constructor();
554 
555 
557  abstract string name();
558 
560 
576  *AbstractRestClass subClass(string name, hash cx, *hash args);
577 
578 
580  hash<HttpServer::HttpHandlerResponseInfo> handleRequest(HttpListenerInterface listener, RestHandler rh, Socket s, *list cl, string mn, hash cx, *hash args);
581 
582 
584 
585 private:
586  hash<HttpServer::HttpHandlerResponseInfo> dispatchStream(HttpListenerInterface listener, RestHandler rh, Socket s, string mn, *hash ah, hash cx);
587 public:
588 
589 
591 
606 private:
607  hash<HttpServer::HttpHandlerResponseInfo> dispatch(RestHandler rh, string mn, *hash ah, hash cx);
608 public:
609 
610 
612 
613 private:
614  hash<HttpServer::HttpHandlerResponseInfo> unknownSubClassError(string n_name);
615 public:
616 
617  };
618 
620 
631 
632 public:
633  public :
635  const Err501 = new hash<HttpResponseInfo>((
636  "code": 501,
637  "body": "not implemented",
638  ));
639 
641  const Methods = (
642  "GET": "get",
643  "POST": "post",
644  "PUT": "put",
645  "DELETE": "del",
646  "OPTIONS": "options",
647  "PATCH": "patch",
648  );
649 
651  const MimeDataTypes = (
652  MimeTypeJsonRpc: (
653  "serialize": \make_json(),
654  "deserialize": \parse_json(),
655  ),
656  MimeTypeYaml: (
657  "serialize": \make_yaml(),
658  "deserialize": \parse_yaml(),
659  ),
660 
661  MimeTypeYamlRpc: (
662  "serialize": \make_yaml(),
663  "deserialize": \parse_yaml(),
664  ),
665  MimeTypeXml: (
666  "serialize": \make_xmlrpc_value(),
667  "deserialize": \parse_xmlrpc_value(),
668  ),
669  MimeTypeXmlApp: (
670  "serialize": string (auto v) {
671  switch (v.typeCode());
672 
673  return make_xml(("value": v));
674  },
675  "deserialize": hash (string xml) {
676  try {
677  return parse_xmlrpc_value(xml);
678  }
679  catch (hash<ExceptionInfo> ex);
680 
681  },
682  ),
684  "serialize": \mime_get_form_urlencoded_string(),
685  "deserialize": \mime_parse_form_urlencoded_string(),
686  ),
687  MimeTypeHtml: (
688  "serialize": string (auto body) { return sprintf("<pre>%N</pre>", body); },
689  ),
690  );
691 
692 public:
693 
694  private :
697 
699  Mutex mx();
700 
703 
704 public:
705 
707 
711 
712 
714  string name();
715 
716 
718 
739  auto handleExternalRequest(string method, string path, *hash body, hash cx = {});
740 
741 
743 
767  hash<HttpResponseInfo> handleRequest(HttpListenerInterface listener, Socket s, hash cx, hash hdr, *data b);
768 
769 
771  removeRootPath(reference<string> path);
772 
773 
775  requestDeserializationError(hash hdr, hash cx, string body);
776 
777 
779  responseSerializationError(hash cx, *hash aih, hash rv);
780 
781 
783  logInfo(string fmt);
784 
785 
787  logError(string fmt);
788 
789 
791  logDebug(string fmt);
792 
793 
795  addClass(AbstractRestClass cls);
796 
797 
799  hash get(hash cx, *hash ah);
800 
801 
803  static hash makeResponse(int code, auto body, *hash hdr);
804  };
805 };
806 
807 // private, unexported namespace
808 namespace Priv {
809  // dumHttpListenerInterface class
810 class DummyListenerInterface : public HttpListenerInterface {
811 
812 public:
813  addUserThreadContext(hash uctx);
814 
815 
816  auto removeUserThreadContext(*string k);
817 
818 
819  log(string fmt);
820 
821 
822  logError(string fmt);
823 
824  };
825 };
string sprintf(string fmt,...)
hash ch
class hash: name -> AbstractRestClass
Definition: RestHandler.qm.dox.h:696
*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:363
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:345
const MimeTypeJsonRpc
list list(...)
const MimeTypeFormUrlEncoded
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:369
the base abstract class for REST stream request handlers
Definition: RestHandler.qm.dox.h:354
the base abstract class for REST handler classes
Definition: RestHandler.qm.dox.h:546
the base class for handling HTTP chunked requests and responses within the RestHandler infrastructure...
Definition: RestHandler.qm.dox.h:484
RestSchemaValidator::AbstractRestSchemaValidator validator
REST schema validator.
Definition: RestHandler.qm.dox.h:702
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:375
*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:808
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:366
const MimeTypeHtml
hash hash(object obj)
hash rhdr
headers to add in the response
Definition: RestHandler.qm.dox.h:372
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
hash< auto > mime_parse_form_urlencoded_string(string str)
setTimeout(timeout n_timeout_ms)
sets the internal socket I/O timeout value in ms