Package net.sourceforge.pmd.reporting

Interface GlobalAnalysisListener

All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
DeterministicOutputListenerWrapper, 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.

  • Method Details

    • 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.
      Implementation Requirements:
      This routine may be called from several threads at once and needs to be thread-safe. But the returned listener will only be used in a single thread.
      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.