Remote Objects Client User Guide (0.0.2)

This is a step by step guide on use of the OpenLaszlo Client Library for RemoteObjects. The intended audience is OpenLaszlo application developers. Please see the RemoteObjects for an overview of the protocol.

Since Remote Objects is a kind of RPC framework, the section on RPC in the OpenLaszlo Application Developer’s Guide is good background information. In thinking about the class objects you will be creating, keep in mind that they may be defined either declaratively as LZX tags or programmatically using the Javascript ‘new’ function with attributes passed in a literal object. Please see the OpenLaszlo Application Developer Guide for details.

remote_server

All Remote Object classes communicate with a back end server using a remote_server class object, so one of these must be created first. The following attributes are those most commonly used by casual users of the library.

  • host is a string containing the IP address, domain name or virtual host of the server. (Required.)
  • port is a string with the port number to communicate with. (Not Required unless a port needs to be specified.)
  • protocol is a string, either ‘http’ or ‘https’. The default value is ‘http’. (Not Required.)
  • format is a string for the serialization format. (Currently ony ‘JSON’ is supported. Not Required.)
  • mesg_wait is an object with a set_wait() function that will be called on request/responses. On request calls: mesg_wait_obj.set_wait(true), on response or error calls: mesg_wait_obj.set_wait(false). This is useful for providing a “request in progress” visual cue. (Not Required.)

The following attributes are also provided for more control or customization of a remote_server:

  • content_type is a string used to set the ‘Content-Type’ request header. (Not Required.)
  • controller is an object with ‘url_for’ and ‘method_for’ functions which could be used to customize the way http requests are constructed. (Not Required.)
  • provider is an object which provides communication services. (Not Required.)
  • proxied is a boolean used to specify if the request will be proxied through the Laszlo Presentation Server.

Here is an example of a remote_server declaration:

<remote_server name="rs_robj"
    host="xyz.com"
    port="3099"
    mesg_wait="$once{ani_wait}"
</remote_server>

class remote_class

A remote_class class object must be created for each Ruby class to be accessed on the remote server. It loads information about the class and is used to invoke class methods of the remote class. (remote_instance described below is used to invoke instance methods.)

The remote_class load operation retrieves and registers any public class and instance method names returned. If the server is configured to disallow exposing method names, then the load operation returns with the object {‘policy’: ‘no_inspect’}. In this case invocation attempts on unregistered method names is allowed by this class, otherwise they must be registered before an invoke request is sent. The following class attributes are defined:

  • class_name is a string containing the remote class name to load. (Required.)
  • remote_server is the remote_server object to use to communicate. (Required.)
  • autoload is a boolean. If true, the remote_class load() function is called during class initialization. If false, load() must be called from the application prior to use of the remote class. (Not required if the default value of true is desired.)

This class also has an unload() function which prevents further use until it is re-loaded. The events onload and onunload are triggered by successful load and unload calls. An error triggers an onerror event with the error message passed as parameter.

Here is an example of a remote_class definition:

<remote_class name="rc_admin_svc"
    class_name="AdminService"
    remote_server="$once{canvas.rs_remote_objects}" >
    <method event="onload">
      Debug.write("rc_admin_svc: onload event");
    </method>
    <method event="onunload">
      Debug.write("rc_admin_svc: onunload event");
    </method>
    <method event="onerror" args="err">
      Debug.write("rc_admin_svc: onerror event:", err);
    </method>
</remote_class>

Once you have loaded a remote_class your application may call the remote class’s public class methods with it. The method invoke(method, params, owner) is used for this. method is the method name to invoke. params is an array or parameters to be passed in the call. owner is the object to whom an onreturn or onreturnerror event will be sent as a result of the call.

class remote_instance

A remote_instance represents an instance of a remote class on the remote server. Since session based objects are supported, the client may access multiple instances of the same class, each with different state that is saved in the session store. Unlike most RPC mechanisms that only support stateless services, this necessitates having a separate class to keep track of object instances.

The remote_instance class defines the following attributes:

  • remote_class is a remote_class object, as defined above. (Required.)
  • auto_instantiate is a boolean. If true, the remote_instance instantiate() function is called during class initialization. If false, instantiate() must be called from the application prior to use of the remote class. (Not required if the default value of true is desired.)
  • createargs is an array of constructor arguments. (Required only if the remote instance needs arguments passed to it’s initialize() function.)

This class has a destroy() function which destroys the object. The events onload and onunload are triggered by successful instantiate and destroy calls. An error triggers an onerror event with the error message passed as parameter.

Here is an example of a remote_instance definition:

<remote_instance name="ri_admin_svc"
    auto_instantiate="false"
    remote_class="$once{canvas.rc_admin_svc}" >
    <method event="onload">
      Debug.write("ri_admin_svc: onload event");
    </method>
    <method event="onunload">
      Debug.write("ri_admin_svc: onunload event");
    </method>
    <method event="onerror" args="err">
      Debug.write("ri_admin_svc: onerror event:", err);
    </method>
</remote_instance>

Once you have a successfully instantiated remote_instance your application may call the remote object’s public methods through this class. The method invoke(method, params, owner) is used for this. method is the method name to invoke and must have been registered with the remote_class referenced by this remote_instance during it’s load operation. params is an array or parameters to be passed in the call. owner is the object to whom an onreturn or onreturnerror event will be sent as a result of the call.

Here is an example of some class methods that do a remote object call and handle return or error events:

<submitter>
    <method name="submit">
      var cln = parent.class_name;
      var p = get_form_params(this);
      parent.admin_service.invoke("find_like_or",
                                 [cln, p],
                                 this);
    </method>
    <method event="onreturn" args="ret">
      windows_list[parent.class_name].open();
    </method>
    <method event="onreturnerror" args="error">
      error_popup("Find Like Or: " + error);
    </method>
</submitter>

Here, the parameters passed are a string ‘cln’ and an array ‘p’. Note that the event handlers are defined inside the same object where the invoke is done since the owner is set to ‘this’. Alternatively, a different object could be specified to handle the returns.