Writing JWAVE Wrapper Functions
warning | JWAVE uses an insecure protocol without authentication. This makes JWAVE insecure to use in an Internet facing configuration and would allow an attacker to execute arbitrary code on the server. If you choose to implement JWAVE in this way, you are responsible for the security of those applications that leverage JWAVE. |
This section explains how to write JWAVE wrapper functions. JWAVE wrapper functions are PV‑WAVE functions that contain JWAVE wrapper API calls, such as GETPARAM and GET_NAMED_COLOR. The wrapper API functions are described in Appendix A: JWAVE Wrapper API.
Example: Simple JWAVE Wrapper
The following JWAVE wrapper:
retrieves a single parameter from the client, “unpacks” the parameter processes the parameter returns a result Simple JWAVE wrapper function
FUNCTION PASSARR, client_data
; Unpack parameters received from the client.
arr = GETPARAM(client_data, 'ARRAY', /Value)
; Change the array.
mydata = arr * 1.5
; Return the changed array.
RETURN, mydata
END
Input Parameter: client_data
All JWAVE wrappers have a consistent interface. They all are functions that accept one parameter called, by convention, client_data.
The client_data parameter passes parameter name(s) and data that were “packaged” by the client Java program. (JWAVE client developers use the setParam method of the JWaveExecute class to “package” the parameters.) When the Java client calls the JWaveExecute.execute method, the packaged parameters are automatically sent in an array to the appropriate JWAVE wrapper function. (The Java client application also specifies the name of the wrapper function it intends to execute.)
GETPARAM Function
The GETPARAM function unpacks the information sent in the client_data parameter. In Simple JWAVE wrapper function, GETPARAM happens to retrieve an array. The GETPARAM arguments include:
client_data—The parameter information that was passed to the wrapper function from the client. ‘ARRAY’—The name of the parameter to unpack. This name was assigned in the client Java program at the time the parameter was “packaged” (with the setParam method). /Value—The Value keyword tells GETPARAM to retrieve just the value of the parameter that was sent. (See the following note.)note | In other situations, it is necessary for GETPARAM to return more than the value. For instance, in many cases, the JWAVE wrapper function will be used to execute one or more PV‑WAVE functions. Typically, this is accomplished with the PV‑WAVE EXECUTE command, and parameters from the client that were unpacked by GETPARAM are used to “build” a string containing the command for EXECUTE. To facilitate these cases, GETPARAM can return a string that is formatted appropriately. For example, if the Positional keyword were used instead of Value, GETPARAM would return a string of the form: ”, param_reference” (where param_reference is a symbolic reference to a value). The result could then be used directly in an EXECUTE statement. For example: x1=GETPARAM(client_data, 'ARRAY', /Positional) status=EXECUTE(”PLOT”+ x1) |
We will discuss the use of the Positional and Value keywords later in this chapter.
RETURN Statement
When RETURN is called in a JWAVE wrapper, the return parameters/data are automatically packaged and sent back to the client Java application. The client can access this data using the default return parameter name DATA. See "Returning Multiple Results to the Client" for information on sending multiple results back to the client.
Wrapper Functions Must Be Compiled
The JWAVE server operates in PV‑WAVE runtime mode. Therefore, all functions and procedures (including wrapper functions) that run on the JWAVE server must be compiled into .cpr files using the PV‑WAVE COMPILE procedure.
For example, a typical series of commands that you can use to compile a single PV‑WAVE routine is:
WAVE> DELPROC, /All
WAVE> DELFUNC, /All
WAVE> .RUN mywrapper.pro
WAVE> COMPILE, /All, File='mywrapper.cpr'
note | We have provided a set of routines that you can use to test your JWAVE wrapper functions before compiling them and publishing them on your Web server. See "Testing Wrapper Functions" for more information. |
