EAF 7.4 Implementation

com.lutris.util
Class OutputStreamEventQueue

java.lang.Object
  extended by java.io.OutputStream
      extended by com.lutris.util.OutputStreamEventQueue
All Implemented Interfaces:
java.io.Closeable, java.io.Flushable

public class OutputStreamEventQueue
extends java.io.OutputStream

A queue of "events". Each event is a write to the OutputStream. This class implements both the reader and writer half of the queue.

Each "event" is returned as an OutputStreamEventQueueEntry object.

The "writer" interface is the set of OutputStream calls. This class extends OutputStream, overriding all the OutputStream methods. All data written to this object is stored up as "events" in an internal queue. Each write is a separate event, so sometimes you will get one event with data followed by one with just a newline. You can pass objects of this class to anything that expects and OutputStream. Calls to the OutputStream methods always return immediatly.

You may optionally specify a maximum number of bytes to store. After each write to the queue, if the new total number of bytes is larger than this limit, then the oldest entries are discarded until the total is at or below the limit. This could result in throwing out all the elements in the queue. Only the number of bytes of data written by the write() methods is counted, not the additional date stamping and object encapsulation. If you specify a size limit of zero, then no limit is imposed.

The "reader" interface is the getEvent() method. Calls to this method will block until there is an event to return. Readers may also call the hasEventsPending() method to see if there are any events. This call does not block.

One possible use for this class is with the PrintTransactionFilter class. If you pass in an instance of this class as the OutputStream, you may then fetch the logging data in a convienent way.

Author:
Andy John
See Also:
OutputStreamEventQueueEntry, OutputStream, com.lutris.servlet.filter.PrintTransactionFilter

Constructor Summary
OutputStreamEventQueue()
          Create a new, empty, OutputStreamEventQueue with no limit on the size of the data stored.
OutputStreamEventQueue(int maxBytes)
          Create a new, empty, OutputStreamEventQueue with a limit on the number of bytes it will store.
 
Method Summary
 void close()
          Closes the OutputStream.
 void flush()
          Does nothing.
 OutputStreamEventQueueEntry getEvent()
          Get an event from the queue.
 boolean hasEventsPending()
          Is there an event waiting in the queue right now? This call will not block, however it is possible that another thread will take the event before you do, so your call to getEvent may still block.
 void write(byte[] b)
          Add an event to the queue containing an array of bytes.
 void write(byte[] b, int off, int len)
          Add an event to the queue containing part of an array of bytes.
 void write(int b)
          Add an event to the queue containing one byte.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

OutputStreamEventQueue

public OutputStreamEventQueue()
Create a new, empty, OutputStreamEventQueue with no limit on the size of the data stored.


OutputStreamEventQueue

public OutputStreamEventQueue(int maxBytes)
Create a new, empty, OutputStreamEventQueue with a limit on the number of bytes it will store.

Method Detail

write

public void write(int b)
           throws java.io.IOException
Add an event to the queue containing one byte.

Specified by:
write in class java.io.OutputStream
Parameters:
b - The byte to save in the queue.
Throws:
java.io.IOException - If close() has been called.
See Also:
java.io.OutputSream

write

public void write(byte[] b)
           throws java.io.IOException
Add an event to the queue containing an array of bytes.

Overrides:
write in class java.io.OutputStream
Parameters:
b - The array of bytes to save in the queue.
Throws:
java.io.IOException - If close() has been called.
See Also:
java.io.OutputSream

write

public void write(byte[] b,
                  int off,
                  int len)
           throws java.io.IOException
Add an event to the queue containing part of an array of bytes. Bytes b[off]..b[off+len-1] are used.

Overrides:
write in class java.io.OutputStream
Parameters:
b - The array of bytes to save part of in the queue.
Throws:
java.io.IOException - If close() has been called.
See Also:
java.io.OutputSream

flush

public void flush()
           throws java.io.IOException
Does nothing. There is no buffering; every write immediatly adds an event to the queue. This method is provided because OutputStream does.

Specified by:
flush in interface java.io.Flushable
Overrides:
flush in class java.io.OutputStream
Throws:
java.io.IOException - If close() has been called.
See Also:
java.io.OutputSream

close

public void close()
           throws java.io.IOException
Closes the OutputStream. It is no longer available for writing. Any further writes will throw an IOException.

Closing the stream wakes up all the threads blocked on a read. If the queue is empty, they will all notice this and return null. This is your signal that there are no events and there never will be.

Specified by:
close in interface java.io.Closeable
Overrides:
close in class java.io.OutputStream
Throws:
java.io.IOException - If close() has already been called.
See Also:
java.io.OutputSream

getEvent

public OutputStreamEventQueueEntry getEvent()
Get an event from the queue. This will block until there is an event to return. The data about the event is stored in a OutputStreamEventQueueEntry object.

If null is returned, that means there are no more events, and the stream is closed, so no further events will be generated.

Returns:
A OutputStreamEventQueueEntry object describing the event, or null if the queue is empty and no more events are possible.
See Also:
OutputStreamEventQueueEntry

hasEventsPending

public boolean hasEventsPending()
Is there an event waiting in the queue right now? This call will not block, however it is possible that another thread will take the event before you do, so your call to getEvent may still block.

Returns:
True is there is an event waiting in the queue.

EAF 7.4 Implementation