Remoting NG

Remoting NG Attribute Reference

Attribute Syntax

Attributes can be defined either at class or at member function, variable or event level. Attributes must be placed before the respective class or member definition they apply to. Attributes are placed within special C++ line comments. A comment defining attributes must start with //@. Multiple attributes can be specified, either using multiple lines (each starting with //@, or within a single comment line, separated by comma.

Example: a single attribute:

//@ remote
void myMethod(int i);

Example: multiple attributes on a single line:

//@ remote, synchronized
void myMethod(int i);

Example: multiple attributes on multiple lines:

//@ remote
//@ synchronized
void myMethod(int i);

Attributes can have values. If no value is specified for an attribute, the attribute's default value is true.

Example:

//@ remote, synchronized
void myMethod(int i);

is equivalent to:

//@ remote = true, synchronized = true

An attribute specified at class level is inherited by all member functions of the class. If an attribute is specified both at class and member function level, the latter takes precedence. Attribute names and values are case sensitive.

Attributes can be specified for parameters, as well. In this case, the syntax is slightly different. The attribute name must be the same as the parameter name, prepended with a dollar sign, and the actual attributes are defined as subattributes of the parameter attribute, placed in curly brackets.

Example:

//@ remote
//@ $i = {name = "value-i", type = "attr"}
void myMethod(int i);

Attribute values must be quoted if they contain characters like -,.?/ or begin with an integer value.

Attribute Reference

action

Assigns an SOAP action to a method. Used by the SOAP transport only.

  • level: method
  • type: string

authenticated

Enforces authentication for a method or all methods of a class (unless overridden with a method-level attribute). If set to true, a transport-specific authentication mechanism must be used to provide credentials (e.g., a username and password) with the request. Before the actual method is invoked, the Poco::RemotingNG::Authenticator instance registered with the Listener is used to validate the supplied credentials.

  • level: class/method
  • type: boolean
  • default: true

cacheExpire

Sets the time how long return values are cached. A cacheExpire value consists of a single positive integer number and a single appended unit. Valid units are: ms, s(ec), m(in), h(our) If no unit is specified milliseconds are assumed. The entire value must be written within quotes. If the value "infinite" is set, data will be cached infinitely. Note that setting this parameter is not enough to enable caching. The @cacheResult attribute must be specified as well.

  • level: class, method
  • type: "infinite" or an unsigned integer, followed by an optional unit

Examples: "2h", "4min", "2000ms", "infinite"

cacheResult

Enables caching of return values. Will reduce the number of method calls if a remote method always returns the same value (for a certain time). See also the @cacheExpire attribute.

  • level: method
  • type: boolean
  • default: true

consumes

For the REST transport, specifies the MIME content type of the request body.

  • level: method
  • type: string
  • default: "application/json" or "application/x-www-form-urlencoded"

direction

Specifies whether a parameter is input, output or input/output. Whether a parameter is input or input/output is normally determined automatically, depending on how the parameter is passed (by value or by const or non-const reference). However, a C++ function signature provides no way to designate a parameter as output only. The @direction attribute allows to rectify that.

  • level: parameter
  • type: ["in"|"out"|"inout"]
  • default: "in" for parameters passed by value or const reference, "inout" for parameters passed by non-const reference

Example:

//@ $image = {direction = "out"}
void retrieveImage(const std::string& id, std::vector<char>& image);

Without the @direction attribute, the image parameter would be first passed to the server, which in this case is unnecessary, and then passed back to the client, containing the desired result.

header

Serialize a parameter in the SOAP header instead of the SOAP body. Only useful with the SOAP Transport. Can be set at method parameters only. Can only be specified for parameters that have a complex data, user-defined data type (class or struct). Note that the @soapHeader attribute splits method parameters into two groups: the header group and the body group. The order value (see the @order attribute) of all header group members must be lower than the smallest order value of the body group, i.e. all header elements are serialized before the body elements.

  • level: parameter
  • type: boolean
  • default: true

filter

Enable or disable event filters for an event. If enabled, event filters can be installed at run-time for the event via an object's Poco::RemotingNG::EventDispatcher::setEventFilter() method, and will be honored while dispatching the event. If disabled, all installed event filters will be ignored when dispatching the event.

  • level: event
  • type: boolean
  • default: false

format

For the REST transport, describes the format of a parameter passed in the request or response body.

  • level: parameter
  • type: string
  • default: "json"

Valid values are:

  • raw: The parameter is passed as a string or raw binary data. Can only be used for simple types, e.g. std::string and std::vector<char>. This is useful for passing raw binary data as a std::string or std::vector<char> in the request or response body. If specified, an appropriate content type should also be specified using the @consumes or @produces attribute.
  • json: The parameter is formatted as JSON. Can be used for simple and complex types.

Example:

//@ $file={in=path}
//@ return={in=body, format=raw}
//@ produces="text/plain"
std::string get(const std::string& file);

in

For the REST transport, defines the location of a parameter.

  • level: parameter
  • type: string
  • default: "body"

Valid values are:

  • path: The parameter is passed as part of the URI path. A @path attribute must also be specified for the method or object, containing a corresponding place holder for the parameter ({name}).
  • query: The parameter is a passed as URI query parameter.
  • form: The parameter is passed in the request body, using form encoding (content type "application/x-www-form-urlencoded").
  • header: The parameters is passed as HTTP request or response header.
  • body: The parameter is passed in the request or response body (raw string or JSON-formatted).

Example:

//@ $file={in=path}
//@ return={in=body, format=raw}
//@ produces="text/plain"
std::string get(const std::string& file);

inline

Change the way return values are serialized. This attribute can only be set for the return value of a method.

  • level: return value
  • type: boolean
  • default: true

For example a method:

Time currentTimeAsStruct() const;

will return the following XML structure if the SOAP Transport is used:

<currentTimeAsStructReply>
    <return>
        <hour>10</hour>
        <minut>31</minute>
        <second>22</second>
    </return>
</currentTimeAsStructReply>

To change that structure to:

<Time>
    <hour>10</hour>
    <minut>31</minute>
    <second>22</second>
</Time>

the @replyName attribute can be specified, along with the @inline attribute on the return value, as follows:

//@ replyName = "Time", return = {inline}
Time currentTimeAsStruct() const;

Note that inlining cannot be combined with attributes, only with elements. Furthermore, no other output parameters are permitted in the method signature if the @inline attribute is specified.

mandatory

Defines if a parameter or member variable is mandatory or optional. Valid on parameters and member variables. Only evaluated during deserialization. If not specified, the default value is true.

  • level: parameter/variable
  • type: boolean
  • default: true

See also @optional. If both @mandatory and @optional are specified, @mandatory takes precedence.

name

Rename a method, event, variable or parameter name. Useful for XML based transports, if the used schema requires a name which would be invalid in C++, like a name containing a minus sign. If used on a method, the @replyName attribute should be specified as well.

  • level: method/parameter/variable
  • type: string

namespace

Assigns an XML namespace to a class, method or parameter. Used by the SOAP Transport only.

  • level: class/method/parameter
  • type: string

oneway

Can be set on methods or events that do not have return values or output parameters. Ignored on all other methods. The @oneway attribute is an optimization that disables sending any response back to the caller. For example, calling a simple method like

void foo();

will result in sending a request and returning an empty response or in case of an error, an exception. Setting @oneway will force the skeleton and proxy to omit this response. While this will improve performance for most transports, it is a setting that should be used with care. It should only be used if the remote method is guaranteed not to throw an exception, or if it doesn't matter if an exception is thrown.

  • level: method/event
  • type: boolean
  • default: true

optional

Defines if a parameter or member variable is optional or mandatory. Valid on parameters and member variables. Only evaluated during deserialization. If not specified, the default value is false.

  • level: parameter/variable
  • type: boolean
  • default: false

See also @mandatory. If both @mandatory and @optional are specified, @mandatory takes precedence.

order

Enforces that parameters are serialized in a specific order. Useful when an XML schema requires an order which is impossible in C++ due to the use of default values. Also, the serializer orders member variables (but not parameters) by their name as default. This attribute can be used to change that behavior. Note that it is not recommended to only partially specify the order element. Omitted or duplicate order values lead to undefined results.

  • level: parameter/variable
  • type: unsigned integer

Example:

//@ remote, $first = {order = 1}, $second = {order = 2}
void foo(int first, int second);

path

For the REST transport, specifies the path template used for extracting parameters passed within the request URI.

  • level: class
  • type: string

The location of parameters within the path is indicated by putting the parameter name in curly brackets.

Example:

//@ remote
//@ path="/api/1.0/orders/{orderNo}/items/{itemNo}"
class ItemCollection
{
    ...
//@ $orderNo={in=path}
//@ $itemNo={in=path}
Item get(int orderNo, int itemNo);
    ...
};

permission

Specifies a permission (in the form of a string) that is required to invoke the method or all methods of a class (if specified on class level). If specified and set to a non-empty string, the Poco::RemotingNG::Authorizer instance registered with the Listener is used to verify that the user identified by the supplied credentials has the specific permission. Names and semantics of the permission string are entirely up to the supplied Poco::RemotingNG::Authorizer implementation.

  • level: class/method
  • type: string

produces

For the REST transport, specifies the MIME content type of the response body.

  • level: method
  • type: string
  • default: "application/json"

remote

Required for the generation of client and server stub code (proxy, skeleton, helper objects, etc.) for a class, method or event.

  • level: class/method/event
  • type: boolean
  • default: true

replyName

Allows to rename the reply structure (or XML element) name returned by a method. The default is the name of the function with Reply appended (e.g., getData returns a structure named getDataReply).

  • level: method/event
  • type: string

serialize

Enable generation of Serializer and Deserializer classes for the given class. Note that the classes must follow a certain coding style for this to work. Refer to the Remoting user manual for more information. If a class is serializable, all super classes must have the "serialize" attribute as well.

  • level: class
  • type: boolean
  • default: true

synchronized

If specified, calls to the remote object and the proxy will be serialized. This is required if the service object is not thread-safe. It is also required if the same proxy object is used simultaneously by multiple threads, although this practice is not recommended. Can be applied to proxies, remote objects, or both (default).

  • level: class/method
  • type: boolean or ["proxy"|"remote"|"all"|"none"]
  • default: true

type

Specify whether a parameter is serialized as XML element or XML attribute (XML-based transports only). Must be either "attr" or "elem". The default value is "elem". Note that "attr" can not be set on complex types or vectors. As a general rule of thumb, "elem" should be used whenever possible, "attr" only where XML schema restrictions require it.

  • level: parameter
  • type: ["attr"|"elem"]
  • default: elem