com.partnersoft.io

Class ConnectionTracker

java.lang.Object

com.partnersoft.io.ConnectionTracker

public class ConnectionTracker
extends java.lang.Object

Tool to track, on a system-wide basis, opens and closes of files, URLs, or similar connections.

The concept of a connection is very abstract - no specific interface must be implemented for a connection object; the tracker simply keeps track of it from when client code marks it as open and then removes it when client code marks it as closed. Anything not closed is then reported at system shutdown time in the log.

You don't generally need to instantiate this class; a global instance is available in SystemServices.connectionTracker().

This class is thread safe.

Copyright 2011-2013 Partner Software, Inc.

Author:

Paul Reavis

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ConnectionTracker.ConnectionEntry This class models a single entry in the ConnectionTracker.

Constructor Summary

Constructors

Constructor and Description
ConnectionTracker() Creates a new ConnectionTracker, with generatingStackTraces set to false.
ConnectionTracker(boolean generatingStackTraces) Creates a new ConnectionTracker, with specified value for generatingStackTraces.

Method Summary

Methods

Modifier and Type	Method and Description
void	closeConnection(java.lang.String mode, java.lang.String url, java.lang.Object connectionObject) Stop tracking a connection.
boolean	isGeneratingStackTraces() If true, this ConnectionTracker generates a stack trace when any connection is opened, and stores it for later.
java.util.List<ConnectionTracker.ConnectionEntry>	listOpenConnections() Returns a copy of the current list of open connections.
void	logOpenConnections() Logs open connections to the system log.
void	onShutdown() This must be called when you are ready to shutdown this tracker.
void	openConnection(java.lang.String mode, java.lang.String url, java.lang.Object connectionObject) Start tracking a connection.
void	reportOpenConnections() Writes an open connection report to logs/reports/OpenConnections.txt.
java.lang.String	reportOpenConnectionsAsHtml() Returns an open connection report as an HTML string.
void	reportOpenConnectionsAsHtmlTo(VfsFile file) Writes an open connection report in HTML format to the given VfsFile.
java.lang.String	reportOpenConnectionsAsText() Returns an open connection report in text format as a String.

Methods inherited from class java.lang.Object

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

Constructor Detail

ConnectionTracker

public ConnectionTracker()

Creates a new ConnectionTracker, with generatingStackTraces set to false.

Equivalent to ConnectionTracker(false).

ConnectionTracker

public ConnectionTracker(boolean generatingStackTraces)

Creates a new ConnectionTracker, with specified value for generatingStackTraces.

Parameters:

generatingStackTraces - if true, generates stack traces for detailed logging

Method Detail

openConnection

public void openConnection(java.lang.String mode,
                  java.lang.String url,
                  java.lang.Object connectionObject)

Start tracking a connection. The connection is marked as open; if it is not closed by a corresponding call to closeConnection(String, String, Object) then the object will be logged at shutdown.

Parameters:

mode - file access or similar mode - can be anything, but usually read, write, or random.

url - URL accessed, if applicable. Does not have to be a URL if there is a more appropriate locator string

connectionObject - object tracked

closeConnection

public void closeConnection(java.lang.String mode,
                   java.lang.String url,
                   java.lang.Object connectionObject)

Stop tracking a connection. The connection is removed from the openConnections set. If this method is not called for an object registered with a corresponding call to openConnection(String, String, Object) then the object will be logged at shutdown.

Parameters:

mode - file access or similar mode - can be anything, but usually read, write, or random.

url - URL accessed, if applicable. Does not have to be a URL if there is a more appropriate locator string

connectionObject - object tracked

logOpenConnections

public void logOpenConnections()

Logs open connections to the system log.

reportOpenConnections

public void reportOpenConnections()

Writes an open connection report to logs/reports/OpenConnections.txt.

reportOpenConnectionsAsText

public java.lang.String reportOpenConnectionsAsText()

Returns an open connection report in text format as a String.

Returns:

String containing open connection report in text format

reportOpenConnectionsAsHtml

public java.lang.String reportOpenConnectionsAsHtml()

Returns an open connection report as an HTML string.

Returns:

HTML-formatted open connection report String

reportOpenConnectionsAsHtmlTo

public void reportOpenConnectionsAsHtmlTo(VfsFile file)

Writes an open connection report in HTML format to the given VfsFile.

Parameters:

file - file to write report to

onShutdown

public void onShutdown()

This must be called when you are ready to shutdown this tracker. It logs and reports open connections.

isGeneratingStackTraces

public boolean isGeneratingStackTraces()

If true, this ConnectionTracker generates a stack trace when any connection is opened, and stores it for later. If the connection fails to close through this tracker, the stack trace is logged to aid the developer. The stack trace reflects when the connection was opened via openConnection(String, String, Object).

Note that since the stack trace generation does take time and that stored stack traces take memory, having this enabled will exact some degree of performance penalty on the system. Thus, it is disabled by default and in the standard SystemServices.connectionTracker().

Returns:

true if the tracker is generating stack traces for every connection open

listOpenConnections

public java.util.List<ConnectionTracker.ConnectionEntry> listOpenConnections()

Returns a copy of the current list of open connections.

Returns:

newly allocated list of open connections