Package net.sourceforge.pmd.reporting

Interface GlobalAnalysisListener

All Superinterfaces:

AutoCloseable

All Known Implementing Classes:

AnalysisCacheListener, GlobalAnalysisListener.ViolationCounterListener, Report.GlobalReportBuilderListener, ReportStatsListener

public interface GlobalAnalysisListener
extends AutoCloseable

Listens to an analysis. This object produces new FileAnalysisListener for each analyzed file, which themselves handle events like violations, in their file. Thread-safety is required. The listener may provide a ListenerInitializer to get context information on the analysis before events start occurring.

Listeners are the main API to obtain results of an analysis. The entry point of the API (PmdAnalysis) runs a set of rules on a set of files. What happens to events is entirely the concern of the listener.

A useful kind of listener are the ones produced by renderers. Another is the report builder.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	GlobalAnalysisListener.ViolationCounterListener	A listener that just counts recorded violations.

Method Summary

Modifier and Type	Method	Description
void	close()	Notify the implementation that the analysis ended, ie all files have been processed.
static GlobalAnalysisListener	exceptionThrower()	A listener that throws processing errors when they occur.
default ListenerInitializer	initializer()	Provides an initializer to gather analysis context before events start occurring.
static GlobalAnalysisListener	noop()	A listener that does nothing.
default void	onConfigError(Report.ConfigurationError error)	Record a configuration error.
FileAnalysisListener	startFileAnalysis(TextFile file)	Returns a file listener that will handle events occurring during the analysis of the given file.
static GlobalAnalysisListener	tee(Collection<? extends GlobalAnalysisListener> listeners)	Produce an analysis listener that forwards all events to the given listeners.

Method Detail

initializer

default ListenerInitializer initializer()

Provides an initializer to gather analysis context before events start occurring.

Returns:

A listener initializer.

startFileAnalysis

FileAnalysisListener startFileAnalysis(TextFile file)

Returns a file listener that will handle events occurring during the analysis of the given file. The new listener may receive events as soon as this method returns. The analysis stops when the FileAnalysisListener.close() method is called.

Parameters:

file - File to be processed

Returns:

A new listener

Throws:

IllegalStateException - If close() has already been called. This prevents manipulation mistakes but is not a strong requirement.

close

void close()
    throws Exception

Notify the implementation that the analysis ended, ie all files have been processed. This listener won't be used after this is called.

Closing listeners multiple times should have no effect.

Specified by:

close in interface AutoCloseable

Throws:

Exception - If an error occurs. For example, renderer listeners may throw IOException

onConfigError

default void onConfigError(Report.ConfigurationError error)

Record a configuration error. This happens before the start of file analysis.

noop

static GlobalAnalysisListener noop()

A listener that does nothing.

tee

static GlobalAnalysisListener tee(Collection<? extends GlobalAnalysisListener> listeners)

Produce an analysis listener that forwards all events to the given listeners.

Parameters:

listeners - Listeners

Returns:

A composed listener

Throws:

IllegalArgumentException - If the parameter is empty

NullPointerException - If the parameter or any of its elements is null

exceptionThrower

static GlobalAnalysisListener exceptionThrower()

A listener that throws processing errors when they occur. They are all thrown as FileAnalysisExceptions. Config errors are ignored.

This will abort the analysis on the first error, which is usually not what you want to do, but is useful for unit tests.