biz.chitec.quarterback.gjsa
Class SyncBurstReceiver

java.lang.Object
  biz.chitec.quarterback.gjsa.SyncBurstReceiver

All Implemented Interfaces:

java.lang.Runnable

public abstract class SyncBurstReceiver

extends java.lang.Object

implements java.lang.Runnable

Abstract class for handling synchronous bursts on client side. The both most interesting classes, initBurst() and handleBurstPart() are declared abstract and to be implemented by a subclass. This class itself handles the complete burst handling, e.g. doing the right calls to the server and looping as long as more results are available.

This class implements the Runnable interface, so that it can be used very simply in a separate thread. Of course, one has to take care that no other thread uses the SessionConnector while this class' thread being active. To archieve this, the caller must not use the SessionConnector between calling start() and any of the finished...() methods being called.

The run()-loop is worked through as long as the burst is not finished. With no errors occurring, finishedCorrectly() is called after the last data has been processed. If the server returns an errornous reply, the loop is aborted and finishedWithError() is called. In case of any client-side exceptions, finishedWithThrowable() is called.

Handling the answer may be stopped by calling stopHandleBurstPart(). Note that that method returns immideately, even though the main thread may continue running for some time as the current burst chunk request is always processed completely. Especially, it is not guaranteed that the SessionConnector may be used immideately after stopHandleBurstPart() returns.

For this case, the method stopHandleBurstPartAndWait() exists. That one initiates an abortion of the loop and waits synchronously afterwards until the loop and the appropriate finish...() method have completed. With this method, it is guaranteed that the SessionConnector is free to use afterwards.

Beside all the multi-thread-stuff, it is also possible to call the run() method of the object synchronously and run the complete receiver in the current thread. For convenience reasons, the runSynchronously() method exists. It can be used like this:

SessionConnector sc=... // define connector in which way ever
SyncBurstReceiver.runSynchronously(sc,new SyncBurstReceiver() {
  public ServerReply initBurst() throws IOException {
    return sc.query(ServerCommands.GETMAGICLIST);
  }
  public void handleBurstPart(final List v) {
    for (int i=0;i<v.size();i++)
      System.out.println(v.get(i));
  }
});

Version:

$Id: 092c50eefeedc9b9d1a2072cb80c8fd52a728d48 $

Author:

Dirk Hillbrecht/chitec 2000,2001 Distributed under the terms of the GNU LGPL.

Field Summary

private boolean	background
protected boolean	doclientloop Flag whether the loop shell be run through once again depending on client state.
private java.lang.Object	doloopfinishwaiter
private boolean	dolooprunning
protected boolean	doserverloop Flag whether the loop shell be run through once again depending on server transmissions.
protected ServerConnector	sc The connection object to the server.

Constructor Summary

SyncBurstReceiver()
Parameterless constructor.

SyncBurstReceiver(ServerConnector scx)
Standard constructor.

Method Summary

void	finishedByInterrupt() Callback for correct, but interrupted finishing.
void	finishedCorrectly() Callback for correct finishing.
void	finishedWithError(ServerReply sr) Callback for server-side errornous finishing.
void	finishedWithThrowable(java.lang.Throwable t) Callback for client-side errornous finishung.
abstract void	handleBurstPart(java.util.List v) Burst part handling method.
abstract ServerReply	initBurst() Burst initialisation method.
void	run() The run loop.
static void	runSynchronously(ServerConnector sc, boolean background, SyncBurstReceiver sbr) Run a SyncBurstReceiver synchronously.
static void	runSynchronously(ServerConnector sc, SyncBurstReceiver sbr) Run a SyncBurstReceiver synchronously without yielding in the receiver loop.
void	setServerConnector(ServerConnector scx) Sets the ServerConnector.
void	stopHandleBurstPart() Stop the handling.
void	stopHandleBurstPartAndWait() Stop handling and wait until it is stopped.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

background

private boolean background

dolooprunning

private boolean dolooprunning

doloopfinishwaiter

private java.lang.Object doloopfinishwaiter

sc

protected ServerConnector sc

The connection object to the server.

doserverloop

protected boolean doserverloop

Flag whether the loop shell be run through once again depending on server transmissions.

doclientloop

protected boolean doclientloop

Flag whether the loop shell be run through once again depending on client state.

Constructor Detail

SyncBurstReceiver

public SyncBurstReceiver()

Parameterless constructor. Mainly for declaration of anonymous instances for synchronous invokation.

SyncBurstReceiver

public SyncBurstReceiver(ServerConnector scx)

Standard constructor. Gets the connection object, stores it internally any does nothing more.

Method Detail

initBurst

public abstract ServerReply initBurst()
                               throws java.io.IOException

Burst initialisation method. Called by run() method to initialize the burst. May do anything it wants, must return the server's answer to the burst-starting command.

Throws:

java.io.IOException

handleBurstPart

public abstract void handleBurstPart(java.util.List v)

Burst part handling method. Called by run() method to handle a chunk of burst data. The method can do whatever it wants.

stopHandleBurstPart

public void stopHandleBurstPart()

Stop the handling. The querying of the server is stopped and no new chunks of data are processed. If there is anything in work, that one is finished however.

stopHandleBurstPartAndWait

public void stopHandleBurstPartAndWait()

Stop handling and wait until it is stopped. Useful in the multi-thread-case where this method will wait until everything is finished before it returns.

setServerConnector

public void setServerConnector(ServerConnector scx)

Sets the ServerConnector.

finishedCorrectly

public void finishedCorrectly()

Callback for correct finishing. Called if the processing finishes without an error and noone called stopHandleBurstPart() or stopHandleBurstPartAndWait().

finishedByInterrupt

public void finishedByInterrupt()

Callback for correct, but interrupted finishing. Called if there were no server-side errors but an interrupt request on the client side by calling stopHandleBurstPart() or stopHandleBurstPartAndWait().

finishedWithError

public void finishedWithError(ServerReply sr)

Callback for server-side errornous finishing.

finishedWithThrowable

public void finishedWithThrowable(java.lang.Throwable t)

Callback for client-side errornous finishung. The run loop catches all Throwables and finally calls this method if anything like that occurs.

run

public final void run()

The run loop. Calls initBurst() and continues issuing CONTINUEBURST requests to the server as long as the data continues to flow.

Specified by:

run in interface java.lang.Runnable

runSynchronously

public static void runSynchronously(ServerConnector sc,
                                    SyncBurstReceiver sbr)

Run a SyncBurstReceiver synchronously without yielding in the receiver loop.

Parameters:

sc - ServerConnector to connect the receiver to.

sbr - SyncBurstReceiver which is run.

runSynchronously

public static void runSynchronously(ServerConnector sc,
                                    boolean background,
                                    SyncBurstReceiver sbr)

Run a SyncBurstReceiver synchronously. Convenience method. Sets SessionConnector and calls sbr.run().

Parameters:

sc - ServerConnector to connect the receiver to.

background - Flag whether the receiver should run with reduced priority

sbr - SyncBurstReceiver which is run.