Description

RealityServer Web Services Protocol system. Protocol processing is the final step when dealing with an HTTP request. Here, a protocol module process the request, decodes any service commands from it and passes them back to RealityServer Web Services. The commands are executed and the results given back to the protocol module for it to serialize back to the HTTP connection.

Unlike other modules protocols are not registered on a per url basis. Instead, each registered protocol is called in turn and returns a confidence level indicating whether it thinks it can handle the request or not. Each protocol is then called in confidence order and attempts to handle the request. Once a protocol indicates that it has handled the request the supplied commands are executed and the protocol is called again to encode the command responses into an HTTP response. The process is as follows:

• call mi::rswservices::IProtocol::test_request() to obtain a confidence level. If returns mi::rswservices::IProtocol::PROTOCOL_CONFIDENCE_NONE then this protocol is excluded from further processing.

• call mi::rswservices::IProtocol::deserialize(). Attempt to decode the request and populate the array returned by mi::rswservices::IProtocol_context::get_command_array() with the commands to execute. Returns mi::nservices::NRS_ERROR_NONE if successfully decoded. The core then executes the supplied commands.

• call mi::rswservices::IProtocol::serialize() with the respones to the executed commands. The protocol should encode the responses and send them on the provided connection.

Many weakly typed protocols will not have detailed knowledge of the expected argument and return types for a given command. For example REST is completely untyped and all arguments come in as strings. These protocols may simply provide all arguments as strings and they will be converted to the correct types just before command execution. To facilitate this protocols can register a converter implemention via mi::rswservices::IProtocol_context::set_converter(). This converter will be used to convert the arguments once their types are known. RealityServer Web Services provides a default converter which can be obtained using mi::rswservices::IProtocol_context::get_converter(). It is recommended that any user converter only provides conversions to and from mi::IString and other types. For other conversions it should simply wrap calls to the default converter.

A protocol may pass information between the deserialize and serialize phases by using mi::rswservices::IProtocol_context::get_attachments(). They must not use class members for this as a single instance of the protocol module is shared by every HTTP request and multiple requests from parallel threads will overwrite each others information.

Protocols may also provide command descriptions to clients, for example a SOAP WSDL may be generated. To achieve this the protocol should obtain the command descriptions required from mi::rswservices::IProtocol_context during the deserialize phase. The description information should be attached and deserialize() return mi::nservices::NRS_ERROR_NONE without adding any commands to the command array. The core will skip command execution and call serialize() immediately. The module can then extract the descriptions from the attachments and return them to the client.

Protocol modules are implemented in RealityServer Web Services plugins using the mi::rswservices::IProtocol interface. These are registered with RealityServer Web Services via mi::rswservices::IExtension_context.

RealityServer Web Services supplies a built in protocol to support the JSON-RPC protocol (versions 1 and 2).