Tutorials

# Communicating with the Server-side

## Connecting to a Local DataStore

If you're writing an RSE subsystem to connect to a local standalone DataStore, the following needs to be done during the connect:

    	...
    	ClientConnection clientConnection = new ClientConnection(connectionName);

    	// initialize the local datastore
    	clientConnection.localConnect();

    	DataStore dataStore = clientConnection.getDataStore();

    	// specify miners to load
    	dataStore.addMinersLocation("."); // initializes the default miners

    	// initialize miners
    	dataStore.getSchema();
    	dataStore.initMiners();
    	...

## Connecting to a Remote DataStore

If you're writing an RSE subsystem to connect to a remote DataStore, the only difference from the local scenario is that `connect` is called rather than `localConnect`.

    	...
    	ClientConnection clientConnection = new ClientConnection(connectionName);

    	// prepare connection
    	clientConnection.setHost(hostName);
    	clientConnection.setPort(port);

    	// connect
    	clientConnection.connect(ticket);

    	DataStore dataStore = clientConnection.getDataStore();

    	// specify miners to load
    	dataStore.addMinersLocation("."); // initializes the default miners

    	// initialize miners
    	dataStore.getSchema();
    	dataStore.initMiners();
    	...

## Loading an Additional DataStore Miner

If the new miner has been registered via the default minerFile.dat file, then no further steps are required to load it. Otherwise, after the subsystem is connected to the remote DataStore, you need to tell the DataStore to load the miner as follows.

    	...
    	dataStore.addMinersLocation(location);
    	dataStore.getSchema();
    	...

This tells the host DataStore to instantiate and initialize all miners listed in the specified minerFile.dat file.

## Sending Commands to a Miner

To send a command to a miner, the required command descriptor must first be obtained using the method `DataStore.localDescriptorQuery`. The method `DataStore.command` is then called with command descriptor and the subject of the command. For example, a query might need to be called on the miner as shown in the following code segment.

    		...
    		// the UI model object
    		MyRemoteObject obj = getMyRemoteObject();

    		// get the corresponding DataElement for this object
    		DataElement deObj = obj.getDataElement();

    		// get the DataStore from the DataElement
    		DataStore ds = deObj.getDataStore();

    		// get the query command descriptor for the subject
    		DataElement queryCmd = ds.localDescriptorQuery(deObj.getDescriptor(), "MY_QUERY_COMMAND");

     		// send the command
     		DataElement status = ds.command(queryCmd, deObj, true);
     		...

## Receiving Data from a Miner

After a command is sent to a miner, you might want to receive information that the miner produced in response to the command. DataStore commands and responses are sent asynchronously, much like events. On the server, the Server Command Handler reacts to incoming commands by calling the `handleCommand` method on the appropriate miner. For the client, the Client Command Handler reacts to incoming responses by firing domain notifications. In order to receive miner responses, asynchronously, you need to implement a DataStore domain listener.

A domain listener implements the IDomainListener interface. An instance of an IDomainListener needs to be added to the DataStore domain listener list. The following is what a simple domain listener looks like:

    	public class MyDomainListener implements IDomainListener
    	{
    	    public boolean listeningTo(DomainEvent e)
    	    {
    	    	// check if we care about this event
    	    	...
    	    }

    	    public void domainChanged(DomainEvent e)
    	    {
    	    	// get the data from this event
    	    	...
    	    }
    	}

A domain listener may either listen for the duration of a DataStore session or may be transient, to be used for a receiving data from a particular command. For example, after calling `DataStore.command`, which returns the status of the command instance, a listener can be added as follows:

    		...
           	MyDomainListener listener = new MyDomainListener(shell);
           `ds.getDomainNotifier().addDomainListener(listener);
           	listener.setStatus(status);
    		...