Filtering

Introduction

Filters are powerful means to remove clutter from the dependency graph and to show only what is relevant. The bigger a project is the more filtering should be applied. Otherwise the dependency graph will just look like a ball of wool and won't reveal any useful insights.

Filters should be used to remove dependencies from the graph that do not provide much useful information about the structure of a project. Good candidates are for example utility or infrastructure libraries such as commons-lang, commons-collections, Guava or my-enterprise-project-commons. Almost every project uses some of them everywhere, which is in most cases absolutely fine. However, showing these dependencies in a dependency graph will not reveal useful information about the project.

This plugin provides three types of filters:

• Plain inclusions and exclusions of dependencies:
  These filters are used to just show/hide information that is relevant or not relevant.
• Inclusions and exclusions for transitive dependencies:
  Many projects are using frameworks which have their own dependencies. Showing these transitive dependencies in the graph might not be useful at all or only useful in some special cases.
• Filters leading to specific dependencies (aka. target dependencies):
  It can be important to analyze if a project has a dependency to a certain library, either directly or transitively. For example, if you use some kind of batch framework, it would be useful to know if any of your web front ends have accidentally a dependency to it.

Include and Exclude Filters

Parameters: includes and excludes

The include/exclude filters are quite simple. To be displayed in the graph a dependency must match the include filter and must not match the exclude filter. An empty include filter does always match, an empty exclude filter does never match. So, not defining any filters will match every dependency in the graph.

In case a dependency is excluded from the graph due to a filter, all of its children will also be excluded from the graph.

Transitive Include and Exclude Filters

Parameters: transitiveIncludes and transitiveExcludes

The transitive include/exclude filters work in a similar manner. The only difference is that the root module and its directly declared dependencies will always be displayed in the graph. Directly declared dependencies are:

• Dependencies in the <dependencies> section.
• Dependencies inherited from all <parent>'s <dependencies> section.

Target Include Filter

Parameter: targetIncludes

When this filter is used the dependency graph will show only the paths to the matching dependencies. This filter is evaluated during Dependency Graph Construction.

This filter uses an internal counter called cutOffDepth to keep track which paths should be included in the graph. A dependency will only be displayed in the graph if the path length from the root is at most the cutOffDepth.

When visiting a dependency, the counter will be set to the current size of the node stack if the dependency matches the filter. Otherwise the counter remains untouched. At the end of a visit the counter will be decreased to the actual size of the node stack if it is greater.

Example

This example shows a graph with root A and its dependencies. Target dependencies are nodes D and F.

The following table shows the construction of the dependency graph. The colors indicate:

• green:
  • Stack: nodes on the path to the target dependency
  • Graph: new edges added to the graph
• blue: the target dependencies
• red: Omitted nodes
• white: the constructed graph

Visitor Call	cutOffDepth	Node Stack	Constructed Graph
visit(A)	0		n/a
visit(B)	0		n/a
visit(C)	0		n/a
endVisit(C)	0		n/a
visit(D)	2		n/a
visit(E)	2		n/a
endVisit(E)	2		n/a
visit(F)	3		n/a
endVisit(F)	2
endVisit(D)	1
endVisit(B)	0
endVisit(A)	0

Combining filters

All available filters can be combined in any way possible. The dependency graph will only show nodes and edges that satisfy all configured filters. The strongest filter among all is the targetIncludes filter since it will omit every node that is not on the path to the matching dependencies.