org.azyva.dragom.reference

Class ReferencePathMatcherByElement

java.lang.Object

org.azyva.dragom.reference.ReferencePathMatcherByElement

All Implemented Interfaces:

ReferencePathMatcher

public class ReferencePathMatcherByElement
extends Object
implements ReferencePathMatcher

ReferencePathMatcher that matches ReferencePath's using a sequence of matching elements. TODO: Most of this documentation should be on the project Web site to avoid duplication. A ReferencePathMatcherByElement is a sequence of ElementMatcher's. Each ElementMatcher includes matchers for matching different parts of a reference in a ReferencePath. The parts that can be matched are: Source-level parts: - NodePath of the module - Version of the module Artifact-level parts: - GroupId of the artifacts produced by the module - ArtifactId of the artifacts produced by the module - ArtifactVersion of the artifacts produced by the module A ElementMatcher cannot contain both source-level and artifact-level parts. The "*" ElementMatcher matches any one reference in a ReferencePath. The "**" ElementMatcher matches not only any reference, but any number (including 0) of consecutive references in a ReferencePath. A ReferenceGaphPathMatcher is always absolute meaning that all references in the ReferencePath must match starting with the first one and ending with the last one. But if the first element in a ReferencePathMatcherByElement is the "**" element, this effectively results in a relative ReferencePathMatcherByElement. A part matcher can be either a fixed string which must match exactly, or a regex. It can also be tete which always matches, regardless of the value of the corresponding ReferencePath element part. A ReferencePathMatcherByElement has a literal form which is a sequence of ElementMatcher literals separated with "->". Each ElementMatcher literal has either of the following forms: - /<module-node-path-matcher>[:<version-matcher>] for source-level part matchers. The leading "/" differentiates from artifact-level ElementMatcher and is not part of the NodePath. But since nodes in a NodePath are separated with this same character this makes it intuitive. - <group-id-matcher>[:<artifact-id-matcher>[:<artifact-version-matcher>]] for artifact-level part matchers. - ** for a "**" ElementMatcher. This notation is used for similarity with Ant-style globs. - * for a "*" ElementMatcher. This notation is used for similarity with Ant-style globs. A given ReferencePathMatcherByElement literal can contain a mix of source-level and artifact-level ElementMatcher's. But obviously a given ElementMatcher is either a source-level or an artifact-level ElementMatcher, but not both. The [] characters above are not literals and indicate optional parts. A part which is not present always matches. An empty part always matches as well. Therefore "/:", "/", "::" and ":" all match any Reference in a ReferencePath and are therefore equivalent to the "*" ElementMatcher (but not to the "**" ElementMatcher). The empty string (which could theoretically be equivalent to the "*" ElementMatcher) is not a valid ElementMatcher. A part matcher is by default a fixed string, but if enclosed within "(" and ")" it is treated as a Java regex (Pattern class), these characters not actually being part of the regex itself. "(" and ")" are reserved characters in regexes but can still be used since a ")" will be considered as a closing delimiter only if followed by ":", "->" or the end of the ReferencePathMatcherByElement literal. Because of the way the different parts of a ReferencePathMatcherByElement literal are delimited, some characters and character sequences cannot be used within ElementMatcher parts. They are ":" and "->". Dragom currently does not support escaping them. Fortunately they are generally not used within ReferencePath elements. And ":" can still be used within a regex, either as a literal (escaped with "\") or as the special character, since when the opening regex delimiter "(" is found, the part is delimited by the closing ")" followed by ":", "->" or the end of the ReferencePathMatcherByElement literal, regardless of occurrences of ":" within the regex. Note that a ReferencePath is, as implied by its name, a sequence of references between modules. This has a few implications worth noting: - The first element in a ReferencePath is not a reference from a module to another module, but rather user-supplied reference to a root module. Such a reference is generally always a source-level reference, so that the first element in a ReferencePathMatcherByElement is generally always a source-level ElementMatcher; - A given module can produce multiple artifacts and therefore multiple artifact-level references can refer to the same module. A ReferencePathMatcherByElement that includes an artifact-level ElementMatcher will match only corresponding artifact-level references. If the module includes a reference to an artifact that is not matched by the ElementMatcher, the match is negative even though the artifact may be produced by the same module. Note that a ReferencePath does not include internal references within modules. Some build tools such as Maven support submodules within a main module and submodules (including the main module) can refer to other submodules. Dragom only considers intermodule (as opposed to intramodule) references. This means that a ReferencePathMatcherByElement using artifact-level ElementMatcher can sometimes be confusing as only the external references are part of ReferencePath's. Here are examples of ReferencePathMatcherByElement literals along with some explanations: - /Domain1/app-a: Matches the specific Module whose NodePath is "Domain1/app-a", regardless of its Version, when that Module is the first element of the ReferencePath; - **->/Domain1/app-a:(D/.*): Matches the specific Module whose NodePath is "Domain1/app-a" if its Version is dynamic, when that module is the last element of the ReferencePath (there can be any number of other elements preceding it within the ReferencePath; - /Domain1/app-a->**: Matches any ReferencePath of depth 1 or more, as long as the first Module has the NodePath "Domain1/app-a"; - *->/Domain1/app-a->**: Matches any ReferencePath of depth 2 or more, as long as the second Module has the NodePath "Domain1/app-a"; - **->com.acme::(.*-SNAPSHOT): Matches any ReferencePath of depth 1 or more, where the last reference is to an artifact having the groupId "com.acme" and a SNAPSHOT ArtifactVersion.

Author:

David Raymond

Constructor Summary

Constructors

Constructor and Description
ReferencePathMatcherByElement(String stringReferencePathMatcherByElement, Model model) Constructor using a ReferencePathMatcherByElement literal.

Method Summary

Modifier and Type	Method and Description
boolean	canMatchChildren(ReferencePath referencePath) Verifies if a ReferencePathMatcherByElement can potentially match children of a ReferencePath.
boolean	equals(Object other)
boolean	matches(ReferencePath referencePath) Verifies if a ReferencePathMatcherByElement matches a ReferencePath.
static ReferencePathMatcherByElement	parse(String stringReferencePathMatcherByElement, Model model) Parses a ReferencePathMatcherByElement literal.
String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

ReferencePathMatcherByElement

public ReferencePathMatcherByElement(String stringReferencePathMatcherByElement,
                                     Model model)

Constructor using a ReferencePathMatcherByElement literal.

Throws RuntimeException if parsing fails.

Parameters:

stringReferencePathMatcherByElement - ReferencePathMatcherByElement literal.

model - Model. The Model is required since a ReferencePathMatcherByElement can refer to ArtifactGroupId's which must be translated to NodePath's.

Method Detail

parse

public static ReferencePathMatcherByElement parse(String stringReferencePathMatcherByElement,
                                                  Model model)
                                           throws ParseException

Parses a ReferencePathMatcherByElement literal.

Parameters:

stringReferencePathMatcherByElement - ReferencePathMatcherByElement literal.

model - Model. The Model is required since a ReferencePathMatcherByElement can refer to ArtifactGroupId's which must be translated to NodePath's.

Returns:

ReferencePathMatcherByElement.

Throws:

ParseException - If parsing fails.

toString

public String toString()

Overrides:

toString in class Object

Returns:

ReferencePathMatcherByElement literal.

matches

public boolean matches(ReferencePath referencePath)

Verifies if a ReferencePathMatcherByElement matches a ReferencePath. A ReferencePathMatcherByElement matches a ReferencePath if all the elements in the ReferencePath are matched by all the ElementMatcher's, also taking into consideration the "*" and "**" ElementMatcher's.

Specified by:

matches in interface ReferencePathMatcher

Parameters:

referencePath - ReferencePath.

Returns:

true if the ReferencePath is matched by the ReferencePathMatcherByElement.

canMatchChildren

public boolean canMatchChildren(ReferencePath referencePath)

Verifies if a ReferencePathMatcherByElement can potentially match children of a ReferencePath.

In many cases this is obvious. ReferencePathMatcherByElement X -> Y will not match any children of ReferencePath A -> B.

But the rule that forbids any Module cycle within a reference graph allows us to determine in certain cases that the children of a ReferencePath cannot be matched by a ReferencePathMatcherByElement. For example ReferencePathMatcherByElement ** -> B -> A cannot match children of ReferencePath A -> B since this would imply a cycle A -> B -> A which is not permitted. There are many other more subtle cases that are covered by this method such as ReferencePathMatcherByElement A -> ** -> B -> ** -> C that can match children of A -> E, but not A -> C.

This is used for optimizing the traversal of reference graphs (traversal avoidance).

Note that when regexes are used within a ElementMatcher for the Module, it is not always possible to determine if children of a ReferencePath can be matched or not. In that case, the method returned that children can be matched, forcing the caller to perform the traversal and apply the ReferencePathMatcherByElement's.

Specified by:

canMatchChildren in interface ReferencePathMatcher

Parameters:

referencePath - ReferencePath.

Returns:

true if the ReferencePath is matched by the ReferencePathMatcherByElement.

equals

public boolean equals(Object other)

Overrides:

equals in class Object