SOIL C++
C++ Unified Device Interface
SOIL::Function Class Reference

Function Class. More...

#include <Function.h>

Inheritance diagram for SOIL::Function:
SOIL::Element HTTP::Resource

Public Member Functions

DLL Function (std::shared_ptr< Element > parent, std::string uuid, std::string name, std::string description, std::string ontology="")
 Constructor. More...
 
DLL ~Function ()
 Destructor. More...
 
template<typename T , int x = -1, int y = -1>
void add_argument (std::string uuid, std::string name, std::string description, std::string unit, SOIL::Range< T > range=SOIL::Range< T >(), std::string ontology="")
 Add argument. More...
 
template<typename T , int x = -1, int y = -1>
void add_argument (std::string uuid, std::string name, std::string description, std::string unit, SOIL::Range< T > range, const Container< T, x, y > &default_value, std::string ontology="")
 Add argument with default value. More...
 
template<typename T , int x = -1, int y = -1>
void add_return (std::string uuid, std::string name, std::string description, std::string unit, SOIL::Range< T > range=SOIL::Range< T >(), std::string ontology="")
 Add return value. More...
 
template<typename T , int x = -1, int y = -1>
HTTP::Json make_return (std::string uuid, Container< T, x, y > value)
 Make JSON Return. More...
 
template<typename T , int x = -1, int y = -1>
Container< T, x, y > make_argument (std::string uuid, HTTP::Json external_json)
 Make Argument from JSON. More...
 
DLL HTTP::Json wjson (void)
 HTTP JSON. More...
 
virtual DLL HTTP::Response handle_get (HTTP::Request request, std::smatch match=std::smatch())
 Handle HTTP GET request. More...
 
virtual DLL HTTP::Response handle_post (HTTP::Request request, std::smatch match=std::smatch())
 Handle HTTP POST request. More...
 
virtual DLL std::map< std::string, HTTP::Jsoninvoke (std::map< std::string, HTTP::Json > arguments)
 Core Invocation. More...
 
DLL std::shared_ptr< Functionptr (void)
 Get Pointer. More...
 
- Public Member Functions inherited from SOIL::Element
 Element (std::shared_ptr< Element > parent, std::string uuid, std::string name, std::string description, std::string ontology="")
 Constructor. More...
 
virtual ~Element ()
 Destructor. More...
 
std::vector< std::string > fqid (void)
 FQID. More...
 
std::shared_ptr< Elementoperator[] (std::string fqid)
 Access Operator. More...
 
std::shared_ptr< Elementadd (std::string uuid, std::shared_ptr< Element > child)
 Add Child Element. More...
 
std::shared_ptr< Elementadd (std::string uuid, Element *child)
 Add Child Element. More...
 
bool insert (std::string uuid, std::shared_ptr< Element > child)
 Add Child Element. More...
 
bool insert (std::string uuid, Element *child)
 Add Child Element. More...
 
bool remove (std::string uuid)
 Remove Child element. More...
 
template<typename T >
T * cast (void)
 Get dynamically casted pointer. More...
 
bool is_object (void) const
 Is Object? More...
 
bool is_variable (void) const
 Is Variable? More...
 
bool is_function (void) const
 Is Function? More...
 
bool is_parameter (void) const
 Is Parameter? More...
 
virtual HTTP::Json wjson (void)
 HTTP JSON. More...
 
virtual std::string json (void)
 JSON string. More...
 
HTTP::Response handle (HTTP::Request request, std::smatch match=std::smatch())
 HTTP Handler. More...
 
- Public Member Functions inherited from HTTP::Resource
 Resource ()
 Constructor. More...
 
 ~Resource ()
 Default Destructor. More...
 
virtual Response handle (Request message, std::smatch match=std::smatch())
 HTTP Handler. More...
 
virtual Response handle_get (Request message, std::smatch match=std::smatch())
 HTTP GET Handler. More...
 
virtual Response handle_put (Request message, std::smatch match=std::smatch())
 HTTP PUT Handler. More...
 
virtual Response handle_post (Request message, std::smatch match=std::smatch())
 HTTP POST Handler. More...
 
virtual Response handle_delete (Request message, std::smatch match=std::smatch())
 HTTP DELETE Handler. More...
 
virtual Response handle_patch (Request message, std::smatch match=std::smatch())
 HTTP PATCH Handler. More...
 
virtual Response handle_options (Request message, std::smatch match=std::smatch())
 HTTP OPTIONS Handler. More...
 
virtual Response handle_head (Request message, std::smatch match=std::smatch())
 HTTP HEAD Handler. More...
 
virtual Response handle_exception (Request message, std::exception &exception, std::smatch match=std::smatch())
 HTTP Exception handler. More...
 

Static Public Member Functions

static std::shared_ptr< Functioncreate (std::shared_ptr< Element > parent, std::string uuid, std::string name, std::string description, std::string ontology="")
 Create new Function. More...
 
- Static Public Member Functions inherited from HTTP::Resource
static web::json::value request_info (Request message, std::smatch match=std::smatch())
 Request Info. More...
 

Additional Inherited Members

- Public Attributes inherited from SOIL::Element
std::map< std::string, std::shared_ptr< Element > > children
 Children Map. More...
 
std::shared_ptr< Elementparent
 Parent Pointer. More...
 
std::shared_ptr< Elementself
 Self Pointer. More...
 
std::string uuid
 Local UUID. More...
 
std::string name
 Name. More...
 
std::string description
 Description. More...
 
std::string ontology
 Ontology identifier. More...
 
std::recursive_mutex mutex
 Element Mutex. More...
 
- Protected Member Functions inherited from HTTP::Resource
void apply_headers (Response &response)
 Apply headers. More...
 
- Protected Attributes inherited from HTTP::Resource
std::vector< web::http::method > allowed_methods
 Allowed methods. More...
 
std::string content_type
 Content type. More...
 
std::string allowed_origins
 Allowed Origins. More...
 

Detailed Description

Class encapsulating a function represented in SOIL. The class directly inherits from Element. The recommended development pattern is to subclass this class and instantitate a use-case specific version. In this case, the invoke() method should be overriden to implement the function's business logic.

Arguments are represented using the Parameter class. A Function supports the HTTP GET (to introspect the signature) and HTTP POST (to execute the function) verbs.

Definition at line 21 of file Function.h.

Constructor & Destructor Documentation

◆ Function()

SOIL::Function::Function ( std::shared_ptr< Element parent,
std::string  uuid,
std::string  name,
std::string  description,
std::string  ontology = "" 
)

Constructor that shall be used to instantiate a Function. If the class is subclassed, it shoule be called from the respective constructor. Most parameters are passed on to the constructor of Element.

Parameters
[in]parentShared pointer to parent object. Can be set to NULL for the creation of a root object
[in]uuidLocally Unique identifier
[in]nameHuman-readable name
[in]descriptionHuman-readable description
[in]ontologyOntology reference, is set to null if an empty string is passed

Definition at line 4 of file Function.cpp.

◆ ~Function()

SOIL::Function::~Function ( )

Standard dsestructor

Definition at line 14 of file Function.cpp.

Member Function Documentation

◆ add_argument() [1/2]

template<typename T , int x, int y>
void SOIL::Function::add_argument ( std::string  uuid,
std::string  name,
std::string  description,
std::string  unit,
SOIL::Range< T >  range,
const Container< T, x, y > &  default_value,
std::string  ontology = "" 
)

Add an argument when building the function with a default value. This method shoukd typically be called fron the subclass constructor. It uses the same templating system than Container does to handle multidimensional data.

Template Parameters
TType of the data.
xFirst dimension of the data. -1 means unused, 0 means arbitray size. Cannot be -1 if y is not -1.
ySecond dimension of the data. -1 means unused, 0 means arbitray size. Must be -1 for x to be -1.
Parameters
[in]uuidLocally Unique identifier
[in]nameHuman-readable name
[in]descriptionHuman-readable description
[in]unitUNECE unit code, e.g. MTR
[in]rangeAllowed range for this argument, which is checked prior to execution. Defaults to no range restriction.
[in]defaultDefault value provided as Container
[in]ontologyOntology reference, is set to null if an empty string is passed (default)

Definition at line 234 of file Function.h.

◆ add_argument() [2/2]

template<typename T , int x, int y>
void SOIL::Function::add_argument ( std::string  uuid,
std::string  name,
std::string  description,
std::string  unit,
SOIL::Range< T >  range = SOIL::Range<T>(),
std::string  ontology = "" 
)

Add an argument when building the function. This method shoukd typically be called fron the subclass constructor. It uses the same templating system than Container does to handle multidimensional data.

Template Parameters
TType of the data.
xFirst dimension of the data. -1 means unused, 0 means arbitray size. Cannot be -1 if y is not -1.
ySecond dimension of the data. -1 means unused, 0 means arbitray size. Must be -1 for x to be -1.
Parameters
[in]uuidLocally Unique identifier
[in]nameHuman-readable name
[in]descriptionHuman-readable description
[in]unitUNECE unit code, e.g. MTR
[in]rangeAllowed range for this argument, which is checked prior to execution. Defaults to no range restriction.
[in]ontologyOntology reference, is set to null if an empty string is passed (default)

Definition at line 229 of file Function.h.

◆ add_return()

template<typename T , int x, int y>
void SOIL::Function::add_return ( std::string  uuid,
std::string  name,
std::string  description,
std::string  unit,
SOIL::Range< T >  range = SOIL::Range<T>(),
std::string  ontology = "" 
)

Add areturn value when building the function. This method shoukd typically be called fron the subclass constructor. It uses the same templating system than Container does to handle multidimensional data.

Template Parameters
TType of the data.
xFirst dimension of the data. -1 means unused, 0 means arbitray size. Cannot be -1 if y is not -1.
ySecond dimension of the data. -1 means unused, 0 means arbitray size. Must be -1 for x to be -1.
Parameters
[in]uuidLocally Unique identifier
[in]nameHuman-readable name
[in]descriptionHuman-readable description
[in]unitUNECE unit code, e.g. MTR
[in]rangeAllowed range for this argument. Defaults to no range restriction.
[in]ontologyOntology reference, is set to null if an empty string is passed (default)

Definition at line 243 of file Function.h.

◆ create()

std::shared_ptr< SOIL::Function > SOIL::Function::create ( std::shared_ptr< Element parent,
std::string  uuid,
std::string  name,
std::string  description,
std::string  ontology = "" 
)
static

Create a new Function using the default constructor and return a shared pointer reference. This is the preferred method for manual creation with consistent lifecycle handling.

Parameters
[in]parentShared pointer to parent object. Can be set to NULL for the creation of a root object
[in]uuidLocally Unique identifier
[in]nameHuman-readable name
[in]descriptionHuman-readable description
[in]ontologyOntology reference, is set to null if an empty string is passed

Definition at line 18 of file Function.cpp.

◆ handle_get()

HTTP::Response SOIL::Function::handle_get ( HTTP::Request  request,
std::smatch  match = std::smatch() 
)
virtual

On HTTP GET, the function returns information about itself and its signature. It is not invoked and this call should not lead to side effects.

Parameters
[in]requestIncoming HTTP request as preprocessed by cpprestsdk
[in]matchMatch result of the request path that led to this resource
Returns
Outgoing HTTP response to be processed by cpprestdsk

Reimplemented from HTTP::Resource.

Definition at line 46 of file Function.cpp.

◆ handle_post()

HTTP::Response SOIL::Function::handle_post ( HTTP::Request  request,
std::smatch  match = std::smatch() 
)
virtual

On HTTP POST, the function is invoked. With the POST request, a list of arguments must be passed in the request's body as list under the keyword "arguments". This method calls invoke(). If you do not implement this function, nothing will happen.

Parameters
[in]requestIncoming HTTP request as preprocessed by cpprestsdk
[in]matchMatch result of the request path that led to this resource
Returns
Outgoing HTTP response to be processed by cpprestdsk

Reimplemented from HTTP::Resource.

Definition at line 54 of file Function.cpp.

◆ invoke()

std::map< std::string, HTTP::Json > SOIL::Function::invoke ( std::map< std::string, HTTP::Json arguments)
virtual

This is the main function that MUST be implemented in a derived class to meaningful act as a function. The arguments are passed as raw HTTP::Json objects mapped to their UUIDs. A map of HTTP::Json objects is expected as returns. It is recommend to use make_arguments and make_returns in this function. Arguments and returns are not further decomposed to Containers to support multi-typed values.

Postcondition
This function will be called from the HTTP POST handler. Any exception thrown will be caught there again and lead to an HTTP Internal Error (500) return code.
Exceptions
std::logic_errorIf not implemented in the derived class, the implementation here throws an exception.
Parameters
[in]argumentsMap of arguments as HTTP Json objects indexrd by their UUID
Returns
Map of return values as HTTP Json objects indexrd by their UUID

Definition at line 95 of file Function.cpp.

◆ make_argument()

template<typename T , int x, int y>
Container< T, x, y > SOIL::Function::make_argument ( std::string  uuid,
HTTP::Json  external_json 
)

Helper function that converts a HTTP Json object to a container of the passed value This function is usually useful in the custom implementation of invoke().

Template Parameters
TType of the data.
xFirst dimension of the data. -1 means unused, 0 means arbitray size. Cannot be -1 if y is not -1.
ySecond dimension of the data. -1 means unused, 0 means arbitray size. Must be -1 for x to be -1.
Parameters
[in]uuidLocally Unique identifier of return value
[in]external_jsonJSON object from which to convert
Returns
Value as Container

Definition at line 256 of file Function.h.

◆ make_return()

template<typename T , int x, int y>
HTTP::Json SOIL::Function::make_return ( std::string  uuid,
Container< T, x, y >  value 
)

Helper function that converts a return value provided as Container to a correpsonding JSON object. This function is usually useful in the custom implementation of invoke().

Template Parameters
TType of the data.
xFirst dimension of the data. -1 means unused, 0 means arbitray size. Cannot be -1 if y is not -1.
ySecond dimension of the data. -1 means unused, 0 means arbitray size. Must be -1 for x to be -1.
Parameters
[in]uuidLocally Unique identifier of return value
[in]valueValue of the return value
Returns
JSON object corresponding to SOIL representation

Definition at line 248 of file Function.h.

◆ ptr()

DLL std::shared_ptr< Function > SOIL::Function::ptr ( void  )
inline

Return a shared pointer casted to the Function type to element itself.

Returns
Casted pointer

Definition at line 223 of file Function.h.

◆ wjson()

HTTP::Json SOIL::Function::wjson ( void  )
virtual

Get a HTTP JSON object corresponding to the function including arguments and returns

Returns
JSON object

Reimplemented from SOIL::Element.

Definition at line 24 of file Function.cpp.


The documentation for this class was generated from the following files: