State Processing

RealityServer Web Services State processing is applied after authorization and before request decoding. State handlers are able to setup the initial environment before server requests are processed. State processing occurs for both HTTP and RTMP requests and performs essentially the same function in both. However due to the differences in the capabilities of the two protocols separate state implementations are provided for each.

Handler selection

Multiple state handlers can be registered with RealityServer Web Services and which state to use can be configured on a per URL basis. If a particular URL matches more than one State handler then all matching State handlers are called in URL match length order. For example if the URL '/applications/car_configurator/' matches handlers configured as '/' and '/applications/car_configurator' then the '/' handler is called first followed by '/applications/car_configurator'.

Implementation

State handlers are implemented in RealityServer Web Services plugins using the mi::rswservices::IState interface. These are registered with RealityServer Web Services via mi::rswservices::IExtension_context.

Like Authorizers, State handlers are also able to allow or deny a particular request. Handlers should return true to allow a request or false to deny it. Unlike Authorizers, State handlers are not able to provide custom failure responses and always return 403 Forbidden messages. These will however be protocol encoded if possible.

Due to significant differences in the amount of information provided by HTTP requests and RTMP RPC requests handling of each is fundamentally different.

HTTP Implementation

HTTP state handlers have access to the entire HTTP request. They can therefore check for state information in any part of the HTTP request, request headers, URL arguments or even the URL path. Information found can either be used directly (EG: checking a cookie for name of the execution scope to use) or indirectly (EG: using a URL argument to retrieve a user scope by name and looking up the execution scope within the neuray library database). It is recommended that component used to specify state be removed from the request so it does not interfere with later processing. For example a session ID embedded into the URL path should be removed so it does not interfere with mapping the path into the content root directory.

RTMP Implementation

RTMP RPC requests do not provide the ability to send additional data with the command request. Requests are simply composed of the command name and it's positional arguments. Due to this, and the fact that RPC uses positional arguments and neuray Services uses named arguments RealityServer Web Services defines it's own method for providing arguments and state information with requests.

A typical RTMP Web Service command call is made by providing the command name to execute, any response methods and and an object containing the named command arguments. For example the following ActionScript code snippet would be used to set the gold_shader.refl_color attribute to Color(0.3,0.6,0.8,1):

	var connection:NetConnection = ...;
	connection.call("element_set_attribute",new Responder(elementSet,commandError),
	    {
	        "element_name":"gold_shader",
	        "attribute_name":"refl_color",
	        "attribute_value": { "r":0.3,"g":0.6,"b":0.8,"a":1.0 }
	    }
	);
	

State information is specified by adding two optional arguments. The first is a String containing the URL path to execute the request at. This URL, if not NULL is instead of the connection URL to search for State handlers to execute and as the base for path mapping. The second is an Object containing String/Value pairs representing additional state information.

	var connection:NetConnection = ...;	
	connection.call("element_set_attribute",new Responder(elementSet,commandError),
	    {
	        "element_name":"gold_shader",
	        "attribute_name":"refl_color",
	        "attribute_value": { "r":0.3,"g":0.6,"b":0.8,"a":1.0 }
	    },
	    "/applications/rtmp_demo/",        // URL path
	    {
	        "scope_name":"user_scope_1"    // state information
	    }
	);
	

Both the URL and object are passed into the RTMP State handler. RTMP state handlers can setup and modify the same information as HTTP handlers including remapping the URL.