<javarpc>
java remote procedure call

JavaScript: lz.javarpc
extends <rpc> » <node> » lz.Eventable »

JavaRPC is a feature that allows server-side Java objects and methods to be accessed from a client application. JavaRPC is part of the Laszlo RPC family and shares similar APIs with SOAP and XML-RPC. See the RPC and XML RPC chapters of the Developer's Guide for more information.

This tag causes the creation of a JavaRPC object. The remoteclassname attribute specifies what class javarpc represents. To use a class, place it in WEB-INF/classes or, if it exists in a jar, in WEB-INF lib. This will ensure that the class is accessible to the OpenLaszlo Server.

Java classes used in an application must be declared in a security element. Classes not defined in a security element are not allowed to be accessed or instantiated. The format of the security element looks like this:

    <security>
        <allow>
            <pattern>CLASS1</pattern>
            <pattern>CLASS2</pattern>
            ...
            <pattern>CLASSN</pattern>
        </allow>
    </security>
                

Each <pattern> is a regular expression.

    <security>
        <allow>
            <pattern>^org\.openlaszlo</pattern>
        </allow>
    </security>
                

This example demonstrates how to call methods in a java object that exists remotely in the server:

<canvas debug="true" height="300" width="800">
    
    <debug x="250" y="10" width="500" height="275"/>
    
    <security>
        <allow>
            <pattern>^examples\.TypesExample</pattern>
        </allow>
    </security>
    
    <!-- See WEB-INF/classes/TypesExample.java for java source. -->
    <javarpc name="types_example_rpc" scope="none" remoteclassname="examples.TypesExample">
    
        <handler name="onload">
        // Set buttons visible only after JavaRPC object loads
        canvas.buttons.setAttribute('visible', true);
        </handler>
        
        <handler name="ondata" args="res">
            Debug.debug('(types ondata) response is: %w', res);
        </handler>
        
        <handler name="onerror" args="errmsg">
            Debug.debug('(types onerror) error: %w', errmsg);
        </handler>
        
        <!-- Declaratively pass an integer. -->
        <remotecall funcname="passInteger">
            <param value="42"/>
        </remotecall>
        
        <!-- Declaratively pass a double. Note that we name this function pd1
        because we have multiple remotecall declarations that call
        passDouble but with different parameters. -->
        <remotecall name="pd1" funcname="passDouble">
            <param value="42.1"/>
        </remotecall>
        
        <!-- Declaratively pass a double with 0 decimal. The 0 decimal will
        truncate and the number will become an integer type when it reaches
        the server. This call will fail. -->
        <remotecall name="pd2" funcname="passDouble">
            <param value="42.0"/>
        </remotecall>
        
        <!-- Declaratively pass a double with 0 decimal. Wrapping the double in
        DoubleWrapper will ensure the value will remain a double when
        reaching the server. -->
        <remotecall name="pd3" funcname="passDouble">
            <param> 
                <method name="getValue">
                    return new LzRPCDoubleWrapper(42.0);
                </method>
            </param>
        </remotecall>
    
    </javarpc>
    
    
    <view name="buttons" visible="false" layout="spacing: 10">
    
        <button text="pass integer" onclick="types_example_rpc.passInteger.invoke()"/>
        
        <button text="pass double" onclick="types_example_rpc.pd1.invoke()"/>
        
        <button text="pass double (will fail)" onclick="types_example_rpc.pd2.invoke()"/>
        
        <button text="pass double w/LzRPCDoubleWrapper" onclick="types_example_rpc.pd3.invoke()"/>
        
        <button text="pass boolean" onclick="this.passBoolean.invoke()">
        <!-- This is a way to declare a remotecall closer to where it's being
        used. The remotecontext must be set. -->
            <remotecall funcname="passBoolean" remotecontext="$once{ types_example_rpc }">
                <param value="true"/>
            </remotecall>
        </button>
        
        <button text="pass array" onclick="this.passArray.invoke()">
            <remotecall name="passArray" funcname="passClientArray" remotecontext="$once{ types_example_rpc }">
                <param value="[1, 'a string', 4.5, false]"/>
            </remotecall>
        </button>
        
        <button text="pass hash" onclick="this.passObject.invoke()">
            <remotecall name="passObject" funcname="passClientObject" remotecontext="$once{ types_example_rpc }">
                <param value="{ a: 1, b: 3.14159, c: 'a string value', d: true}">
                </param>
            </remotecall>
        </button>
        
    </view>
    
    </canvas>

The java source code, which can be found in $LPS_HOME/WEB-INF/classes/examples, looks like:

        package examples;
        
        import java.util.Vector;
        import java.util.Hashtable;
        
        public class TypesExample {
        
        public static String passInteger(int i) {
            return "got integer parameter: " + i;
        }
        
        public static String passDouble(double d) {
        return "got double parameter: " + d;
        }
        
        public static String passBoolean(boolean b) {
            return "got boolean parameter: " + b;
        }
        
        public static String passClientArray(Vector v) {
            return "got vector parameter: " + v;
        }
        
        public static String passClientObject(Hashtable t) {
            return "got hashtable parameter: " + t;
        }
        
        }
    
JavaScript data type Parameter types expected by java method
Number (int) int
Number (double)* double
LzRPCDoubleWrapper double
Boolean boolean
Array Vector
Object Hashtable

* Any floating point number with a zero decimal value is considered to be an integer, i.e., 1.0 is really 1. Use LzRPCDoubleWrapper to ensure a number is considered a double. For example:

                    // assume myrpc is a javarpc object and myrpc.proxy.myMethod is a function
                    // that expects a single double as a parameter
                    var mydouble = new LzRPCDoubleWrapper(1.0);
                    myrpc.proxy.myMethod([ mydouble ], new LzDelegate(...));
                

See Also:

Attributes

Name (CSS property) Type (tag) Type (js) Default Category
attributename string String this.name read/write
  Attribute name of server remote object. Name or attributename must be set when scope is 'session' and 'webapp'. Default is the name of this object.
createargs expression any null read/write
  Used if loadoption='loadcreate' or loadoption='create'. Arguments to construct remote object with. The value passed in must be an array, e.g., [1, 'mystring', 1.45]. Default is null.
loadoption string String loadcreate read/write
  One of 'loadcreate', 'loadonly', or 'create'. 'Loadcreate' tries to load javarpc object if it exists in the server, else it creates it before loading. 'Loadonly' will only load object if it exists, else an error is returned. 'Create' will always create the object in the server. Default is 'loadcreate'.
objectreturntype string String pojo read/write
  Used to determine what server-side object member values are returned to the client. One of 'pojo' (returns public member values) or 'javabean' (returns members that have associated getters). Default is 'pojo' (plain old java object).
remoteclassname string String   read/write
  The remote class name associated with the remote object. This must be set if creating the remote object. If loading the object, the classname will be set during onload.
scope string String   read/write
  One of 'session', 'webapp', or 'none' to set the scope of the remote object. This attribute must be set before creating or loading the object. If scope is 'session' or 'webapp', name or attributename must be set.

Attributes inherited from <rpc>

autoload, proxy, proxyinfo, secure, secureport

Methods

load()
javarpc.load();
Load the object. If successful, this.proxy is set to an object with remote APIs.

makeProxyStubFunction()
javarpc.makeProxyStubFunction(fn);
Parameter Name Type Description
fn    

unload()
javarpc.unload();
Unload the remote object. On, this.proxy is set to null.

Methods inherited from <rpc>

load, makeProxyStubFunction, unload

Methods inherited from lz.Eventable

destroy, setAttribute

Events

Events inherited from <rpc>

ondata, onerror, onload, onunload

Events inherited from <node>

onconstruct, ondata, oninit

Events inherited from lz.Eventable

ondestroy