* * In addition to the standard methods inherited from its superclass, this class * also provides the ability to attach a {@link QueueListener} object to the * ToEclipseQueue, as a handler for data requests from ECLiPSe. *
* There is no public constructor; to access an ToEclipseQueue use the
* createToEclipseQueue() of an object implementing the {@link
* EclipseConnection} interface or the getEclipseStdin() method of
* an object implementing the {@link EclipseEngine} interface.
*
*/
public class ToEclipseQueue extends OutputStream {
/* Name of queue which is to be used by the user on the Java side.
The corresponding stream on the Eclipse
side may be referenced by the same string, but may also have other names. */
private String name;
/* Stream number uniquely identifying the stream on the Eclipse side, and also
used by classes inside this package on the Java side */
private int id;
/* The Eclipse which this queue is a queue to. Declared as an
EclipseConnectionImpl because this is the abstract class containing the methods
such as writeToStream which are called from this class */
private EclipseConnectionImpl eclipse;
/**
* Listener for handling outgoing data, none by default
*/
private QueueListener listener = null;
/**
* Flag to indicate whether close() method has been called.
*/
private boolean isClosed = false;
/**
* Flag indicating whether this is a system or user queue. The eclipse side of
* a System queue does not get closed when the EclipseConnectionImpl's
* closeAllQueues method is called. Examples of system queues are ec_rpc_in
* ec_rpc_out, and standard stream queues.
*/
private boolean systemQueue = false;
/**
* construct a toEclipseQueue
*/
ToEclipseQueue(int id,String name, EclipseConnectionImpl eclipse)
{
this.eclipse = eclipse;
this.id = id;
this.name = name;
}
int getID()
{
return(id);
}
/**
* Returns true if this queue is a system queue, such as ec_rpc_in.
*/
boolean isSystemQueue()
{
return(systemQueue);
}
/**
* sets flag indicating wether this is a system queue
*/
void setSystemQueue(boolean newValue)
{
systemQueue = newValue;
}
// write a single byte: calls writeByteToStream in the
// EclipseConnectionImpl class.
public void write(int b) throws IOException
{
testClosed();
eclipse.writeByteToStream(id, (byte) b);
}
// invokes a method in the underlying eclipse which writes to a stream
public void write(byte b[], int off, int len) throws IOException
{
testClosed();
eclipse.writeToStream(id,b,off,len);
}
/**
* Attach a QueueListener to this ToEclipseQueue for handling
* requests for data. When ECLiPSe
* tries to read from an empty queue with a QueueListener
* attached,
* the dataAvailable() method of the
* QueueListener is invoked.
*/
public void setListener(QueueListener l) throws IOException
{
testClosed();
listener = l;
}
/**
* Detach any QueueListener from this ToEclipseQueue.
*/
public void removeListener() throws IOException
{
testClosed();
listener = null;
}
/**
* Called to notify that data has been requested, this forwards the request
* to any listeners.
*/
void notifyRequest()
{
// if there is a listener, invoke its dataRequest method
if(listener != null)
{
listener.dataRequest(this);
}
}
/**
* Calls the superclass' flush method
*/
public void flush() throws IOException
{
testClosed();
// Get the underlying eclipse to flush the relevant stream
eclipse.flushStream(this.id);
// somehow here allow eclipse to handle events
}
/**
* Closes the queue (both eclipse and Java sides), removing any listener.
*/
public void close() throws IOException
{
testClosed();
close_cleanup();
eclipse.closeToEclipseStreamEclipseSide(id);
eclipse.closeToEclipseStreamJavaSide(id);
}
// method to clean up locally
void close_cleanup()
{
try
{
this.removeListener();
}
catch(IOException ioe)
{
// only thrown if the queue has already been closed, which it hasn't
System.err.println("Error: removal of listener threw an IOException.");
System.err.flush();
}
isClosed = true;
}
/**
* Test whether the queue has been closed; if so, throw an IOException
* "Operation not possible: stream closed."
*/
private void testClosed() throws IOException
{
if(isClosed)
{
throw new IOException("Operation not possible: stream closed.");
}
}
}