| Package | com.mi.rs |
| Interface | public interface IService extends flash.events.IEventDispatcher |
| Implementors | RSService |
Defines the interface of a service object that can process RealityServer commands. This interface specifies the methods and properties that allows commands to be processed by RealityServer and introduce a couple of important concepts that will be briefly covered here.
Command Processing
The most obvious goal of the RealityServer client library is to make it as easy as possible to process RealityServer webservice commands. The service accepts commands for processing from the application, for instance by calling IService.addCommand(). Commands will be processed one by one in the order they are added. If the responses of the commands are of interest it is possible to add response handlers that will be called when commands have been processed. The service can optimize command processing by sending a bunch of commands to the server at once, but logically all commands are serialized and processed one by one. Commands also fail individually so command processing will always continue with the next command even if the previous command failed. Command processing is asynchronous and adding commands while the service is busy will cause the commands to queue up, meaning it might take some time before they are finally sent to the server and processed. The RealityServer client library will alwasy process all added commands and even if processing of commands might be delayed there is no concept of a command queue or any possibility to remove reduntant commands once they are added to the service. This means that it is vital that the application don't add any redundant commands. To be able to accomplish this the application will need some way to know when the service is ready to process commands. This is solved by the central concept called Process Commands Callback.Process Commands Callback
This is the core mechanism that the RealityServer Client Library use to process commands and is used to know when the service is ready to process commands. When the application needs to process commands, for instance in response to user input, it should generally not add the commands directly by using IService.addCommand(). Instead it should add a Process Commands Callback by calling IService.addCallback(callbackFunc). What the application essentially say is this: Hello service! I have some commands I need to process. Please call the supplied function when you have time to process them. The service may then call this function immediately, or after some time if currently busy, at which point the application adds the commands.
When adding a callback using IService.addCallback() it will be placed in a callback queue. Each callback represents some part of the application that wish to process commands, for instance to update the scene database, render the scene, or maybe persist some data to a database. Each callback, when made, can then add zero or more commands that will then be processed by the service immediately. It is important to note that while there is no concept of a command queue in the RealityServer Client Library, there is a process commands callback queue instead. The same callback can only be added once at a time, but is single shot. When the applicaiton needs to process commands again it needs add the callback again. It is the responsibility of the application to keep track of user input, etc, occuring in the time between adding the callback and when it is actually made, at which point the application must add an optimized sequence of commands.
Exmple: Scene Navigation
An application wants to implement scene navigation by letting the user drag the mouse on the rendered scnene image. To accomplish this the application would have to perform the following steps:
1. When the user triggers a mouse drag event, register a process commands callback and indicate that a callback is pending.
2. While the callback is pending, update a client local camera transform each time the user triggers new mouse drag events.
3. When the callback is made, add a RealityServer command that updates the camera transform to the current value.
4. Clear the indication that a callback is pending and repeat from step 1.
As can be seen in this example the callback mechanism can be used to add a single command to update the camera transform at the time when the service is ready to process the command. This can't be accomplished with the IService.addCommand() method since the service will always execute all commands added and there is no way to know when it is a good time to add commands. It is important to note that IService.addCommand() is just a convenience method so that a callback does not need to be registered when not needed. Internally a call to addCommand will result in a callback being added to the callback queue, so commands added this way will not be executed before any callbacks already in the queue. This means that adding command A using addCommand() is equivalent to adding a callback and adding A when the callback is made. An example when callbacks are not needed is for instance when initializing an application. During initialization it is common for a fixed sequence of commands, for instance to load a scene, create scopes, etc, to be executed. It is perfectly safe to use both addCommand() and the callback mechanism at the same time.
State Data
RealityServer commands are executed in a specific state that is set up by optional state handers on the server. The state handler determines things like the scope in which to execute commands based on parameters passed with the low level request, for instance an HTTP request. Since the user of the RealityServer Client library should not have to worry how commands are sent to the server this state data is instead specified using an object implementing the IStateData interface. This interface allow specification of a path and a set of key/value pairs that the server side state handler then inspects to determine the state to execute the commands in. The IStateData instance to use when executing a command is determined when calling the IService.addCallback method (or the IService.addCommand method). All commands added in the callback will be associated with this state data and the service will make sure that the commands are processed on the server in such a way that the RealityServer state handler is invoked with the provided data. Note that this means that to add commands using different state data they have to be added in different callbacks. The IStateData interface also allow specification of state commands which can be used to for instance call the set_scope command. Again the service will make sure that commands are processed on the server in such a way that state commands affect all the commands associated with a specific IStateData instance.
IService also allow setting a default IStateData to use when no explicit state data is specified in calls to addCommand or addCallback. If no state is specified at all then the commands will be executed in the default (global) scope.
Connectors
The RealityServer Client library delegates actual processing of commands to IRSConnector. All client library implementations support a HTTP connector which process commands using HTTP requests. The ActionScript libary also supports an RTMP connection in addition to the HTTP connector which can be enabled to get access to RTMP specific commands. The IRSService.connectorName can be used to determine which connector is currently in use. The IService will also dispatch RSService events to indication when the connector has switched so that the application can take advantage of any connecort specific commands.
See also
| Property | Defined By | ||
|---|---|---|---|
|
baseURL : String [read-only]
Returns the base URL to the service.
|
IService | ||
|
connectorName : String [read-only]
Returns the name of the current connector.
|
IService | ||
|
defaultStateData : IStateData
The default state data for this IService instance.
|
IService | ||
| Method | Defined By | ||
|---|---|---|---|
|
addCallback(callback:Function, stateData:IStateData = null, delayProcessing:Boolean = false):void
Adds a callback to the end of the callback queue.
|
IService | ||
|
addCommand(cmd:ICommand, responseHandler:Function = null, stateData:IStateData = null, delayProcessing:Boolean = false):void
Adds a command to be processed.
|
IService | ||
|
cancelCallback(callback:Function):Boolean
Cancels a registered process commands callback.
|
IService | ||
| baseURL | property |
baseURL:String [read-only]
Returns the base URL to the service. The base URL is the URL with no path or URL arguments added.
Example: http://somehost:8080/
public function get baseURL():String| connectorName | property |
connectorName:String [read-only]
Returns the name of the current connector. The connector encapsulates the on-the-wire protocol used to process commands. Currently two connectors are available:
"HTTP" - Commands are processed using HTTP requests. "RTMP" - Commands are processed using a RTMP connection.
RTMP specific commands are only available when the RTMP connector is used. public function get connectorName():String| defaultStateData | property |
defaultStateData:IStateData
The default state data for this IService instance. If no state data is specified in the addCommand and addCallback methods, then this is the state data that will be used.
public function get defaultStateData():IStateData public function set defaultStateData(value:IStateData):void| addCallback | () | method |
public function addCallback(callback:Function, stateData:IStateData = null, delayProcessing:Boolean = false):void
Adds a callback to the end of the callback queue. The callback will be made at the point in time when the service is ready to process commands generated by this callback. Callbacks will always be made in the order they were registered with the service, so if callback A is added before callback B, then A will be called before B and consequently any commands added by A will be processed before any commands added by B.
Callbacks are one-shot, meaning that a callback needs to be registered every time the application needs to process commands. The same callback can only be registered once at a time. The application is responsible for keeping track of any user input that occurs while waiting for the callback and convert that user input into an optimized sequence of NWS commands. The same callback function can be added again as soon as it has been called or cancelled.
NOTE: When the callback is made the supplied ICommandSequence instance must be used to add the commands, not IService.addCommand().
Parameters
callback:Function — The callback function. This function needs to
have the following signature:
addCommands(cmds:ICommandSequence):void
|
|
stateData:IStateData (default = null) |
|
delayProcessing:Boolean (default = false) |
| addCommand | () | method |
public function addCommand(cmd:ICommand, responseHandler:Function = null, stateData:IStateData = null, delayProcessing:Boolean = false):void
Adds a command to be processed.
Note that adding commands using this method is equivalent to registering a process commands callback and adding commands when the process commands callback is made. This means that any callbacks already registered will be executed before the command (or commands if the delayProcessing flag is used) added using this method.
Example: Adding commands A, B, and C with delayProcessing set to true for A and B, but false for C will be equivalent to register a callback and add A, B, and C when the callback is made.
Parameters
cmd:ICommand — The command to add.
|
|
responseHandler:Function (default = null) |
|
stateData:IStateData (default = null) |
|
delayProcessing:Boolean (default = false) |
See also
| cancelCallback | () | method |
public function cancelCallback(callback:Function):Boolean
Cancels a registered process commands callback. This call removes the callback from the queue. Useful if the callback is no longer needed, or if the callback needs to be moved to the end of the queue. In the latter case, first cancelling and then adding the callback makse sure that it is executed after any callbacks already in the callback queue.
Parameters
callback:Function — The previously added callback function.
|
Boolean — true if the callback was cancelled, false if it was not
in the queue.
|