See also:
• A walkthrough of the collaboration conversion process
• A brief example of making a VisAD widget collaborative

Collaborative VisAD applications.

Refactoring an application for collaboration

Making an application collaborative

1. Choose a "service name", which is the name used to look up the server's information. I typically use the application's class name:
   String serviceName = getClass().getName();
   but any string will do, provided it is not used by multiple applications (or multiple instances of the same application) on a single machine. If you want to run multiple instances of an application on a single machine, you'll need to have the user specify the service name somehow.
2. Optionally add some way to start the application up in standalone, server and client modes. This is often done with a special argument in the String argument list passed to the application's main() method, but it could also be indicated through a property or even via a UI widget.
3. For standalone/server mode, call the data setup method to create the Display(s) and any data references.
4. For server mode:
   • start up a server using:
     RemoteServerImpl server = ClientServer.startServer(serviceName);
     
   • tell the server about the DisplayImpl(s) by calling:
     server.addDisplay(new RemoteDisplayImpl(display));
     once for each DisplayImpl in your application.
   • if you have any data references which are needed by user interface widgets (a Slider, for example) but which have not been added to the server's Display, tell the server about those by calling:
     server.addDataReference(new RemoteDataReferenceImpl(ref));
     
5. For client mode:
   • open a connection to the server using:
     RemoteServer client = ClientServer.connectToServer(hostName, serviceName);
     where serviceName is the name chosen above.
   • fetch local copies of the remote Display objects using:
     LocalDisplay[] dpys = ClientServer.getClientDisplays(client);
     or, to fetch individual Display objects:
     LocalDisplay dpy = ClientServer.getClientDisplay(client, 0);
     The getClientDisplays() method is preferred for fetching more than one display because using the second method for multiple displays tends to slow down client initialization, because it causes multiple trips across the network, slowing down program initialization.
   • fetch local copies of the remote DataReference objects using:
     DataReference ref = (DataReference )client.getDataReference(0);
     (where 0 is replaced by the number of the DataReference to be fetched. The references are numbered in the order they were added to the server.)
   • For the initial debugging, you may want to disable the user interface widget setup on the client end until you've got the basic collaborative application working.
6. For all modes, call the user interface setup method
   
   This is greatly simplified if you use the DisplayImpl.getWidgetPanel() method, which automatically builds controls for the Display's ScalarMaps.
7. Verify that all collaborative user interface widgets are based on either Controls or ScalarMaps (this is already true of all the widgets in the visad.util package). This means that, as well as changing some aspect of the display due to user input (via the itemStateChanged() method), a collaborative widget must also change its visible state based on Control or ScalarMap changes (as a ControlListener via the controlChanged() method, or as a ScalarMapListener via the mapChanged() method.)
   
   For instance, a standalone version of a widget to turn the VisAD box on and off might be implemented as a JCheckBox widget with an ItemListener which calls display.getDisplayRenderer().setBoxOn() with the appropriate value (true or false) A collaborative version needs to also listen to the RendererControl (which holds the state of several DisplayRenderer values) and reflect box visibility changes in RendererControl by changing the state of the UI widget (adding a checkmark when the box is turned on, removing a checkmark when the box is turned off.)

Testing your collaborative application

• If you are trying to create a user interface widget using a Control or ScalarMap saved during the data setup phase, the widget will throw a NullPointerException since the saved variable will not have been initialized because the client did not (and should not have) run the data setup.
• If a client Display change (via a UI widget) results in the same change happening to the server's Display but the server's UI widget is left unchanged, it is likely that the widget is not responding properly to Control/ScalarMap changes.
  
  See "Making a VisAD widget collaborative" for details on how to fix this.

Some things to consider

• Any shared data references or Controls should be initialized during the data setup phase, not as a side effect of the setup code for some widget in the user interface setup phase.
  
  If a shared VisAD object is initialized by a widget you have written, it will be *re*initialized when the widget is created by each client. This will be sent to the server, causing the current settings to be overwritten and then broadcast to all the other clients currently connected to the server.
  
  NOTE: All widgets in visad.util should properly handle shared VisAD objects, so you don't need to worry about them in a collaborative application.
• All shared user interface widgets should be initialized from Controls or ScalarMaps which have been fetched from the Display, rather than from a variable which had been initialized during the data setup phase. Since the client does not go through the data setup phase, it won't have a copy of any Controls or ScalarMaps saved during that phase.
• All shared user interface widgets (i.e. user interface widgets which will be implemented on both the server and the client) should be connected to Display-based Controls or ScalarMaps. All client-server coordination currently happens via Displays, and if a Control or ScalarMap isn't attached to a Display, changes to it will not be forwarded to the server.
• Most of the above only applies to simple collaborative applications. It is possible to build an application which is a client using a remote Display and acting as a server for a local Display or ScalarMap, or for an application to switch between standalone and client/server modes. You're only limited by your imagination (and the memory/bandwidth of your workstation :-)