Jiffie: Java InterFace For Internet Explorer

net.sf.jiffie
Class TrackingElementFactory

java.lang.Object
  net.sf.jiffie.DefaultElementFactory
      net.sf.jiffie.TrackingElementFactory

All Implemented Interfaces:

ElementFactory

public class TrackingElementFactory
extends DefaultElementFactory

This class extends the default element factory to include functionality to track all entities created by the factory. When the release method of this factory is called, any unreleased entities will have their release method called. This is designed to be used for example as part of the test fixture setUp and tearDown methods supported by JUnit. After each test this factory can be used to ensure that no entities have been leaked due to their release methods not being called. The second purpose of this class is to provide debugging information about leaked entities. If the debug output flag is set to true, then an instance of this factory will generate a list of the entities which have not been released by the caller. This functionality can be extended by setting the stack trace flag to true, which will capture stack trace details each time an entity is created, and will output these as part of the debug message allowing the user to determine where in their code they are not cleaning up resources they have allocated. Note that working in its default mode this class is not suitable for long-running processes which use Jiffie, as it holds on to references to all entities created by the underlying factory. To support longer running processes a watchdog thread has been implemented. This can be started and stopped from the start/stopWatchdogThread methods. It wakes up periodically and removes any entities from the internal list which have already been released. By default the watchdog wakes up every 10 seconds, but this time period can be set by calling the setWatchdogSleepTime method. Obviously developers can rely on the finalize method of any leaked resources being called by the JVM, assuming that they are eligible for garbage collection. However when dealing with Windows COM resources it is probably best practice not to allow these resources to leak as you may end up with Windows getting itself into difficulties if large numbers of entities are not released.

Nested Class Summary

protected class	TrackingElementFactory.TrackedItem Simple container for entities being tracked.
protected class	TrackingElementFactory.WatchdogThread Simple watchdog thread used to remove released items from the list.

Field Summary

protected boolean	m_runWatchdog
protected boolean	m_stackTrace
protected int	m_watchdogSleepTime

Constructor Summary

TrackingElementFactory()

Method Summary

IDispatch	createElement(InternetExplorer parentBrowser, Dispatch dispatch) Create an object representing an HTML element.
ElementList	createElementList(InternetExplorer parentBrowser, Variant variant) Create a class implementing the ElementList interface which may contain, zero, one or many IHTMLElement instances.
int	flushReleasedAndCount() This method is used to remove any entries from the list of items being tracked by this factory which have already been released, and will return a count of the number of unreleased items.
boolean	getDebugOutput() Retrieves a flag indicating if debug output is being generated.
java.io.PrintStream	getDebugPrintStream() Retrieves the destination print stream for debug output.
boolean	getStackTrace() Retrieves a flag indicating if stack traces are produced as part of the debug output.
int	getWatchdogSleepTime() Retrieves the watchdog sleep time.
void	release() This method is called to release any previously unreleased entities.
void	setDebugOutput(boolean debugOutput) Set this flag to true to produce debug output listng unreleased entities.
void	setDebugPrintStream(java.io.PrintStream ps) This method is called to set the destination for any debugging output produced by this class.
void	setStackTrace(boolean stackTrace) Set this flag to true to generate stack traces as part of the debug output.
void	setWatchdogSleepTime(int sleepTimeInSeconds) Set the watchdog thread sleep time in seconds.
void	startWatchdogThread() Launches the watchdog thread.
void	stopWatchdogThread() Stops the watchdog thread.
protected void	track(Releaseable object) This method is called to begin tracking an entity.
protected void	writeDebugOutput(TrackingElementFactory.TrackedItem item) This method is designed to be overloaded by subclasses to allow developers to produce their own diagnostic ouput if any is required.

Methods inherited from class net.sf.jiffie.DefaultElementFactory

createElementFromTag

Methods inherited from class java.lang.Object

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

Field Detail

m_stackTrace

protected boolean m_stackTrace

m_runWatchdog

protected boolean m_runWatchdog

m_watchdogSleepTime

protected int m_watchdogSleepTime

Constructor Detail

TrackingElementFactory

public TrackingElementFactory()

Method Detail

createElement

public IDispatch createElement(InternetExplorer parentBrowser,
                               Dispatch dispatch)
                        throws JiffieException

Create an object representing an HTML element.

Specified by:

createElement in interface ElementFactory

Overrides:

createElement in class DefaultElementFactory

Parameters:

parentBrowser - parent browser

dispatch - dispatch interface for HTML element COM object

Returns:

HTML element object

Throws:

JiffieException - if an exception occurs creating the element

createElementList

public ElementList createElementList(InternetExplorer parentBrowser,
                                     Variant variant)
                              throws JiffieException

Create a class implementing the ElementList interface which may contain, zero, one or many IHTMLElement instances.

Specified by:

createElementList in interface ElementFactory

Overrides:

createElementList in class DefaultElementFactory

Parameters:

parentBrowser - parent browser

variant - variant representing a dispatch interface

Returns:

object implementing the ElementList interface

Throws:

JiffieException - if an exception occurs creating the list

setDebugOutput

public void setDebugOutput(boolean debugOutput)

Set this flag to true to produce debug output listng unreleased entities.

Parameters:

debugOutput - boolean flag

getDebugOutput

public boolean getDebugOutput()

Retrieves a flag indicating if debug output is being generated.

Returns:

boolean flag

setDebugPrintStream

public void setDebugPrintStream(java.io.PrintStream ps)

This method is called to set the destination for any debugging output produced by this class. Note that the default destination for this output is System.err

Parameters:

ps - print stream

getDebugPrintStream

public java.io.PrintStream getDebugPrintStream()

Retrieves the destination print stream for debug output.

Returns:

debug print stream

setStackTrace

public void setStackTrace(boolean stackTrace)

Set this flag to true to generate stack traces as part of the debug output.

Parameters:

stackTrace - boolean flag

getStackTrace

public boolean getStackTrace()

Retrieves a flag indicating if stack traces are produced as part of the debug output.

Returns:

boolean flag

setWatchdogSleepTime

public void setWatchdogSleepTime(int sleepTimeInSeconds)

Set the watchdog thread sleep time in seconds. By default this value is set to 10 seconds.

Parameters:

sleepTimeInSeconds - sleep time in seconds

getWatchdogSleepTime

public int getWatchdogSleepTime()

Retrieves the watchdog sleep time.

Returns:

sleep time in seconds

startWatchdogThread

public void startWatchdogThread()

Launches the watchdog thread.

stopWatchdogThread

public void stopWatchdogThread()

Stops the watchdog thread.

track

protected void track(Releaseable object)

This method is called to begin tracking an entity.

Parameters:

object - entity t be tracked

flushReleasedAndCount

public int flushReleasedAndCount()

This method is used to remove any entries from the list of items being tracked by this factory which have already been released, and will return a count of the number of unreleased items.

Returns:

count of the number of unreleased items

release

public void release()

This method is called to release any previously unreleased entities. Optionally it will produce debugging output describing what has not been released, and where it was initially allocated.

writeDebugOutput

protected void writeDebugOutput(TrackingElementFactory.TrackedItem item)

This method is designed to be overloaded by subclasses to allow developers to produce their own diagnostic ouput if any is required.

Parameters:

item - item which has not been released