java.lang.module
Class ModuleQuery

java.lang.Object
  java.lang.module.ModuleQuery

All Implemented Interfaces:

java.lang.Iterable<ModuleQuery>, Matcher<ModuleArchive>

Direct Known Subclasses:

AttributeExists, Binary, Exports, Unary, VersionMatches

public abstract class ModuleQuery
extends java.lang.Object
implements Matcher<ModuleArchive>, java.lang.Iterable<ModuleQuery>

A ModuleArchive Matcher that can be composed into boolean expression trees. Used to select one or more ModuleArchive instances from a collection (e.g., a ModuleRepository).

For small ModuleArchive collections, linear evaluation may be sufficient:

     ModuleArchive find(ModuleQuery query, List<ModuleArchive> list) {
         for (ModuleArchive archive : list) {
             if (query.matches(archive)) {
                 return archive;
             }
         }
         return null;
     }
 

For scalability, the use of one or more indices is recommended. For example, if searches using a module name are expected to be common, an index that maps a module name to the subset of archives with that name will reduce the number of required evaluations. It may also be desirable to index for exported package names, attribute names, or even values from a future ModuleQuery subtype; therefore, this class supports a fully generic and extensible model for extracting such values from a ModuleQuery.

For example, given the query:

     import static java.lang.module.ModuleQuery.*;
     ...
     ModuleQuery query = moduleNameEquals("com.acme.dynamite")
                         .and(versionMatches(aVersionRange)
                              .or(attributeExists(anAttribute)));
 

the findIndexable() method can be used to extract the name "com.acme.dynamite" and narrow the search:

     List list = listAll();
     ModuleNameEquals node = findIndexable(ModuleNameEquals.class);
     if (node != null) {
         String name = node.getModuleName();
         list = listByName(name);
     }
     ...
 

The findIndexable() method ensures that values are returned only if they may be safely used to narrow a search using an index. For example, the module name from the following query is not a candidate for use in an index, so findIndexable() will return null:

     import static module.ModuleQuery.*;
     ...
     ModuleQuery query = not(moduleNameEquals("my.module"));
 

Since:

Dec 10, 2008

Author:

Bryan Atsatt

Field Summary

static ModuleQuery	ANY A query that matches any module archive.
static ModuleQuery	NONE A query that does not match any module archive.

Constructor Summary

ModuleQuery()

Method Summary

protected java.util.List<ModuleQuery>	addTo(java.util.List<ModuleQuery> list) Add this ModuleQuery and any children to the specified list.
protected static java.util.List<ModuleQuery>	addTo(ModuleQuery query, java.util.List<ModuleQuery> list) Add the specified ModuleQuery and any children to the specified list.
ModuleQuery	and(ModuleQuery right) Returns a ModuleQuery that is the conjunction of this instance and the specified query.
static ModuleQuery	and(ModuleQuery left, ModuleQuery right) Returns a ModuleQuery that is the conjunction of two queries.
static ModuleQuery	any() Returns a ModuleQuery that matches any archive.
java.util.List<ModuleQuery>	asList() Returns this ModuleQuery and all child instances as a list.
static ModuleQuery	attributeEquals(java.lang.String attributeName, java.lang.String attributeValue) Returns a ModuleQuery that tests for the existence of an attribute and that the values are equal.
static ModuleQuery	attributeExists(java.lang.String attributeName) Returns a ModuleQuery that tests for the existence of an attribute.
static ModuleQuery	exports(ExportMatcher exportMatcher) Returns a ModuleQuery that tests for an export.
static ModuleQuery	exportsPackage(java.lang.String packageName) Returns a ModuleQuery that tests for an exported package.
static ModuleQuery	exportsPackage(java.lang.String packageName, Matcher<Version> versionMatcher) Returns a ModuleQuery that tests for an exported package, with optional version matching.
protected <T extends ModuleQuery> Indexable<T>	find(Indexable<T> indexable) Match this ModuleQuery and any children against the specified Indexable, stopping at the first match.
protected static <T extends ModuleQuery> Indexable<T>	find(ModuleQuery query, Indexable<T> indexable) Match the specified ModuleQuery and any children against the specified Indexable, stopping at the first match.
<T extends ModuleQuery> T	findIndexable(java.lang.Class<T> targetType) Walk this ModuleQuery and return the first node of the specified type that is safe to use in an index.
<T extends ModuleQuery> boolean	instanceOf(java.lang.Class<T> targetType) Test to see if this ModuleQuery is an instance of the specified type.
java.util.Iterator<ModuleQuery>	iterator() Returns an iterator over this and all child instances.
abstract boolean	matches(ModuleArchive target) Tests if the specified target matches this instance.
static ModuleQuery	moduleNameAndVersionMatch(java.lang.String moduleName, Matcher<Version> versionMatcher) Returns a ModuleQuery that matches a module name and a version, version range or version list.
static ModuleQuery	moduleNameEquals(java.lang.String moduleName) Returns a ModuleQuery that matches a module name.
ModuleQuery	not() Returns a ModuleQuery that inverts this query.
static ModuleQuery	not(ModuleQuery query) Returns a ModuleQuery that inverts the specified query.
ModuleQuery	or(ModuleQuery right) Returns a ModuleQuery that is the disjunction of this instance and the specified query.
static ModuleQuery	or(ModuleQuery left, ModuleQuery right) Returns a ModuleQuery that is the disjunction of two queries.
static ModuleQuery	versionMatches(Matcher<Version> version) Returns a ModuleQuery that matches a version, version range or version list.

Methods inherited from class java.lang.Object

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

Field Detail

ANY

public static final ModuleQuery ANY

A query that matches any module archive.

NONE

public static final ModuleQuery NONE

A query that does not match any module archive.

Constructor Detail

ModuleQuery

public ModuleQuery()

Method Detail

matches

public abstract boolean matches(ModuleArchive target)

Tests if the specified target matches this instance.

Specified by:

matches in interface Matcher<ModuleArchive>

Parameters:

target - The target instance.

Returns:

true if the specified target matches this instance; false otherwise.

not

public static ModuleQuery not(ModuleQuery query)

Returns a ModuleQuery that inverts the specified query.

Parameters:

query - the specified query.

Returns:

the ModuleQuery object.

and

public static ModuleQuery and(ModuleQuery left,
                              ModuleQuery right)

Returns a ModuleQuery that is the conjunction of two queries.

Parameters:

left - The left query.

right - The right query.

Returns:

The ModuleQuery object.

or

public static ModuleQuery or(ModuleQuery left,
                             ModuleQuery right)

Returns a ModuleQuery that is the disjunction of two queries.

Parameters:

left - The left query.

right - The right query.

Returns:

The ModuleQuery object.

any

public static ModuleQuery any()

Returns a ModuleQuery that matches any archive.

Returns:

The ModuleQuery object.

versionMatches

public static ModuleQuery versionMatches(Matcher<Version> version)

Returns a ModuleQuery that matches a version, version range or version list.

Parameters:

version - The version matcher.

Returns:

The ModuleQuery object.

moduleNameEquals

public static ModuleQuery moduleNameEquals(java.lang.String moduleName)

Returns a ModuleQuery that matches a module name.

Parameters:

moduleName - The module name.

Returns:

The ModuleQuery object.

moduleNameAndVersionMatch

public static ModuleQuery moduleNameAndVersionMatch(java.lang.String moduleName,
                                                    Matcher<Version> versionMatcher)

Returns a ModuleQuery that matches a module name and a version, version range or version list.

Parameters:

moduleName - The module name.

versionMatcher - The version matcher.

Returns:

The ModuleQuery object.

exportsPackage

public static ModuleQuery exportsPackage(java.lang.String packageName)

Returns a ModuleQuery that tests for an exported package.

Parameters:

packageName - The package name.

Returns:

The ModuleQuery object.

exportsPackage

public static ModuleQuery exportsPackage(java.lang.String packageName,
                                         Matcher<Version> versionMatcher)

Returns a ModuleQuery that tests for an exported package, with optional version matching.

Parameters:

packageName - The package name.

versionMatcher - The version matcher. May be null.

Returns:

The ModuleQuery object.

exports

public static ModuleQuery exports(ExportMatcher exportMatcher)

Returns a ModuleQuery that tests for an export.

Parameters:

exportMatcher - The export matcher

Returns:

The ModuleQuery object.

attributeExists

public static ModuleQuery attributeExists(java.lang.String attributeName)

Returns a ModuleQuery that tests for the existence of an attribute.

Parameters:

attributeName - The attribute name.

Returns:

The ModuleQuery object.

attributeEquals

public static ModuleQuery attributeEquals(java.lang.String attributeName,
                                          java.lang.String attributeValue)

Returns a ModuleQuery that tests for the existence of an attribute and that the values are equal.

Parameters:

attributeName - The attribute name.

attributeValue - The attribute value.

Returns:

The ModuleQuery object.

not

public ModuleQuery not()

Returns a ModuleQuery that inverts this query.

Returns:

the ModuleQuery object.

and

public ModuleQuery and(ModuleQuery right)

Returns a ModuleQuery that is the conjunction of this instance and the specified query.

Parameters:

right - The right query.

Returns:

The ModuleQuery object.

or

public ModuleQuery or(ModuleQuery right)

Returns a ModuleQuery that is the disjunction of this instance and the specified query.

Parameters:

right - The right query.

Returns:

The ModuleQuery object.

iterator

public java.util.Iterator<ModuleQuery> iterator()

Returns an iterator over this and all child instances.

Specified by:

iterator in interface java.lang.Iterable<ModuleQuery>

Returns:

an Iterator.

asList

public java.util.List<ModuleQuery> asList()

Returns this ModuleQuery and all child instances as a list.

Returns:

The list.

findIndexable

public <T extends ModuleQuery> T findIndexable(java.lang.Class<T> targetType)

Walk this ModuleQuery and return the first node of the specified type that is safe to use in an index. In this sequence:

     ModuleQuery q = not(attributeExists("foo"));
     AttributeExists exists = q.findIndexable(AttributeExists.class);
 

exists will be set to null. Double negation works as expected, so that in this sequence:

     ModuleQuery q = not(not(attributeExists("foo"));
     AttributeExists exists = q.findIndexable(AttributeExists.class);
 

exists will be valid and can be used to extract the original attribute name:

     String attributeName = exists.getAttributeName();
 

Parameters:

targetType - The required ModuleQuery subtype.

Returns:

A ModuleQuery instance of the specified type that may be used in an index or null if not found or not usable in an index.

instanceOf

public <T extends ModuleQuery> boolean instanceOf(java.lang.Class<T> targetType)

Test to see if this ModuleQuery is an instance of the specified type.

Parameters:

targetType - The required ModuleQuery subtype.

Returns:

true if this is an instance of the target type; otherwise, returns false.

addTo

protected java.util.List<ModuleQuery> addTo(java.util.List<ModuleQuery> list)

Add this ModuleQuery and any children to the specified list.

Parameters:

list - The list to add to.

Returns:

The list.

addTo

protected static java.util.List<ModuleQuery> addTo(ModuleQuery query,
                                                   java.util.List<ModuleQuery> list)

Add the specified ModuleQuery and any children to the specified list.

Parameters:

query - The query.

list - The list to add to.

Returns:

The list.

find

protected <T extends ModuleQuery> Indexable<T> find(Indexable<T> indexable)

Match this ModuleQuery and any children against the specified Indexable, stopping at the first match.

Parameters:

indexable - The indexable to match.

Returns:

The indexable.

find

protected static <T extends ModuleQuery> Indexable<T> find(ModuleQuery query,
                                                           Indexable<T> indexable)

Match the specified ModuleQuery and any children against the specified Indexable, stopping at the first match.

Parameters:

query - The query to walk.

indexable - The indexable to match.

Returns:

The indexable.