A Proxy class is an interface that describes a data proxy. The subclass of the Proxy class used by JWAVE clients to refer to data that is stored on the server is JWaveDataProxy.

Usually, a JWAVE wrapper function processes data in some way and stores the results. The JWAVE client may wish to use another JWAVE wrapper to perform further analysis on the stored results. To do this, the client needs to be able to reference the data stored on the server. The most efficient way to do this is to ask the server to return a data proxy, which the client can then use in the setParam method of subsequent function calls from the first wrapper, as shown in Figure 6-1: Proxy Object.

While the end result of this processing might be some kind of plot or image that is sent back to the client, the important point to remember is that the actual data never has to leave the server.

How the data arrives on the server in the first place is up to the JWAVE application developer. The data could have originated on the client and been uploaded to the server. Or, the data could have been loaded on the server from a file or database, or calculated by a JWAVE wrapper function.

The data referred to by a JWaveDataProxy object persists on the server until it is explicitly deleted or the PV‑WAVE session is shut down.

A JWaveDataProxy object is instantiated with:

For instance, one way to construct a JWaveDataProxy object is:

where myconnection is the previously instantiated JWaveConnection object (tells the proxy how to find the server), MYDATA is the name of the data stored on the server, and MYDOMAIN is the domain.

When you construct a JWaveDataProxy object in this way, you are only providing the name of the data. This JWaveDataProxy object refers to a place to store data, but there is no guarantee that there is actually data there. If you do not know that there is already data on the server, you can use the Proxy.store method to send data to the PV‑WAVE session.

There are two other ways to create a JWaveDataProxy object, and they both are used in conjunction with a JWaveExecute object.

The first way is to supply a ServerDataID object (which encapsulates the name and domain of a JWaveDataProxy object) using setParam.

setParam(String name, Object value, ServerDataID dataName) 

This associates values with the parameter name, as usual, but additionally the server stores the data as named by the ServerDataID object when it is sent with the next execute call.

This technique is useful when you have some data on the client, and you want to use that same dataset with several JWAVE wrapper functions. So you use the above setParam method to save the data on the first call, and then you use the following setParam on subsequent calls to associate a named parameter with that stored data:

setParam(String name, ServerDataID dataName) 

This technique stores data on the server, even though you are not manipulating JWaveDataProxy objects directly. If you need direct access to the data (like to delete it when you are done) you can use the same ServerDataID object that identifies the data name in a constructor to a new JWaveDataProxy object.

Another way to create a data proxy is when data is returned by a JWAVE wrapper function. Normally, the JWAVE wrapper returns values back to the client, but you can change this. Before you call the execute method, you can use the setReturnParamMode method to change how returned data will be handled.

There are a couple of overloaded methods for setReturnParamMode, but the primary one is:

 setReturnParamMode(String name, boolean returnVals, ServerDataID dataName)

If you use this method, and specify a ServerDataID object for the data name, then that parameter will be stored on the server when the JWAVE wrapper function returns. You can also use the boolean flag with one of the values JWaveExecute.RETURN_NO_VALUES or
JWaveExecute.RETURN_VALUES. If you set this flag to RETURN_NO_VALUES, then no values are returned, but a JWaveDataProxy object to the stored data is returned.

This technique is useful for “chaining” the output of one JWAVE wrapper to the input of another, as you will see in a later example.

There are other ways to use setReturnParamMode object. If you set the flag to RETURN_VALUES and you set a ServerDataID object, then the data is stored and also returned to the client. You can even discard data that you do not want by setting RETURN_NO_VALUES without a ServerDataID object.