com.edugility.jpa.maven.plugin
Class ListEntityClassnamesMojo

java.lang.Object
  org.apache.maven.plugin.AbstractMojo
      com.edugility.jpa.maven.plugin.AbstractJPAMojo
          com.edugility.jpa.maven.plugin.ListEntityClassnamesMojo

All Implemented Interfaces:

ContextEnabled, Mojo

public class ListEntityClassnamesMojo
extends AbstractJPAMojo

Generates a .properties file, suitable for use as a Maven filter, whose contents are the set of names of classes that have been annotated with the Entity, MappedSuperclass, Embeddable and IdClass annotations.

Since:

1.0-SNAPSHOT

Author:

Laird Nelson

See Also:

AbstractJPAMojo, Entity, MappedSuperclass, Embeddable, IdClass

Goal:

list-entity-classnames

Runs by Default in Maven Lifecycle Phase:

process-test-classes

Requires Dependency Resolution in Scope:

test

Field Summary

private static String	DEFAULT_DEFAULT_PROPERTY_NAME The property name to use for classnames that belong to the default package when another default property name cannot be found.
private static String	DEFAULT_OUTPUT_FILENAME The default name used in constructing the outputFile when no output file has been specified and the return value of the getUseOutputFile() method is true.
(package private) static String	DEFAULT_SUBDIR_PREFIX The default subdirectory prefix that is added to the value of the current Maven project's build directory when constructing a prefix for non-absolute output file specifications.
private String	defaultPropertyName The property key under which the entity classname listing will be stored.
private String	encoding The character encoding to use when writing the outputFile.
private String	firstItemPrefix The textual prefix to prepend to the list of classnames.
private static List<String>	JPA_ANNOTATIONS The List of JPA annotations that this ListEntityClassnamesMojo scans for.
private String	lastItemSuffix The suffix to append to the list of classnames.
private File	outputFile The File to which entity- and mapped superclass-annotated classnames will be written.
private String	prefix The textual prefix to prepend to every element of the list of classnames, excluding the first element.
private Map<String,String>	propertyNames A Map of property names indexed by package prefix segments.
private static Pattern	quotePattern A workaround for MODELLO-256; a Pattern used to strip initial leading and (matching) trailing quotes from a String.
private boolean	stripQuotes A workaround for MODELLO-256; if true then values for the prefix, suffix, firstItemPrefix and lastItemSuffix will have any leading and trailing quotes (if they are a matched pair) removed.
private String	suffix The suffix to append to every element of the list of classnames, excluding the last element.
private Set<URL>	urls The Set of URLs to scan.
(package private) boolean	useOutputFile Whether or not to write properties to an external file.

Fields inherited from interface org.apache.maven.plugin.Mojo

ROLE

Constructor Summary

ListEntityClassnamesMojo()
Creates a new ListEntityClassnamesMojo.

Method Summary

protected AnnotationDB	createAnnotationDB() Creates a new AnnotationDB in the (common) case where a user has not supplied this AbstractJPAMojo with a pre-configured AnnotationDB.
protected String	decorate(String classname, String prefix, String suffix) Decorates the supplied class name with the supplied prefix and suffix parameters and returns the result.
String	determinePropertyName(String className) Returns the appropriate property name given a class name.
void	execute() Executes this mojo.
String	getDefaultPropertyName() Returns the property name to use for the names of Classes that belong to the default package.
String	getEncoding() Returns the encoding used to write the Properties file that this mojo generates.
String	getFirstItemPrefix() Returns the prefix prepended to the list of classnames.
String	getLastItemSuffix() Returns the suffix appended to the list of classnames.
File	getOutputFile() Returns the output File.
String	getPrefix() Returns the prefix prepended to every element of the list of classnames, excluding the first element.
String	getProjectBuildDirectoryName() Returns this ListEntityClassnamesMojo's best guess as to its related Maven project's build directory.
Map<String,String>	getPropertyNames() Returns a Map of property names indexed by package fragments.
String	getSuffix() Returns the suffix appended to every element of the list of classnames, excluding the last element.
private Set<URL>	getTestClasspathURLs() Returns a Set of URLs that represents the test classpath.
Set<URL>	getURLs() Returns the Set of URLs to scan for annotations.
boolean	getUseOutputFile() Returns whether or not this ListEntityClassnamesMojo should write its properties out to the associated output file.
private void	initialize() Called by the execute() method; initializes all fields to their defaults if for some reason they were not already set appropriately.
private File	initializeOutputFile() Initializes the outputFile property and returns its value.
(package private) File	initializeOutputFile(File outputFile) Validates and "absolutizes" the supplied File and returns the corrected version.
private void	initializePropertyNames() Called by the initialize() method; sets up the propertyNames field appropriately.
private Set<URL>	initializeURLs() Initializes the Set of URLs to scan and returns it.
private AnnotationDB	scan() Scans the Set of URLs this ListEntityClassnamesMojo has been configured with and returns the AnnotationDB that performed the scanning.
void	setDefaultPropertyName(String defaultPropertyName) Sets the property name to use for the names of Classes that belong to the default package.
void	setEncoding(String encoding) Sets the encoding used to write the Properties file that this mojo generates.
void	setFirstItemPrefix(String firstItemPrefix) Sets the prefix prepended to the list of classnames.
void	setLastItemSuffix(String lastItemSuffix) Sets the suffix appended to the list of classnames.
void	setOutputFile(File file) Sets the File to use as the output file parameter.
void	setPrefix(String prefix) Sets the prefix prepended to every element of the list of classnames, excluding the first element.
void	setPropertyNames(Map<String,String> propertyNames) Sets the Map of property names indexed by package fragments that will be used to determine under which property name a given class name should be listed.
void	setSuffix(String suffix) Sets the suffix appended to every element of the list of classnames, excluding the last element.
void	setURLs(Set<URL> urls) Sets the Set of URLs to scan for annotations.
void	setUseOutputFile(boolean useOutputFile) Sets whether or not this ListEntityClassnamesMojo should write its properties out to the associated output file.
(package private) String	stripQuotes(String text) A workaround for MODELLO-256; strips leading and trailing quotes from the supplied text parameter value and returns the result.
private boolean	validateOutputDirectory(File outputDirectory) Ensures that the supplied File, after this method is invoked, will designate a directory that exists and is writable.

Methods inherited from class com.edugility.jpa.maven.plugin.AbstractJPAMojo

cloneAnnotationDB, getProject, getURLFilter, scan, setAnnotationDB, setProject, setURLFilter

Methods inherited from class org.apache.maven.plugin.AbstractMojo

getLog, getPluginContext, setLog, setPluginContext

Methods inherited from class java.lang.Object

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

Field Detail

quotePattern

private static final Pattern quotePattern

A workaround for MODELLO-256; a Pattern used to strip initial leading and (matching) trailing quotes from a String. Used indirectly by the setPrefix(String), setSuffix(String), setFirstItemPrefix(String) and setLastItemSuffix(String) methods.

See Also:

stripQuotes(String)

DEFAULT_DEFAULT_PROPERTY_NAME

private static final String DEFAULT_DEFAULT_PROPERTY_NAME

The property name to use for classnames that belong to the default package when another default property name cannot be found.

See Also:

Constant Field Values

DEFAULT_OUTPUT_FILENAME

private static final String DEFAULT_OUTPUT_FILENAME

The default name used in constructing the outputFile when no output file has been specified and the return value of the getUseOutputFile() method is true.

DEFAULT_SUBDIR_PREFIX

static final String DEFAULT_SUBDIR_PREFIX

The default subdirectory prefix that is added to the value of the current Maven project's build directory when constructing a prefix for non-absolute output file specifications.

This field is package-private for unit testing purposes only.

JPA_ANNOTATIONS

private static final List<String> JPA_ANNOTATIONS

The List of JPA annotations that this ListEntityClassnamesMojo scans for. A class that has been annotated with one of these annotations must be made known to the JPA persistence unit in some fashion, which is the task with which this mojo provides assistance.

See Also:

Embeddable, Entity, IdClass, MappedSuperclass, Java Persistence 2.0 Specification

stripQuotes

private boolean stripQuotes

A workaround for MODELLO-256; if true then values for the prefix, suffix, firstItemPrefix and lastItemSuffix will have any leading and trailing quotes (if they are a matched pair) removed. This should protect these values from undesired trimming by Maven.

Plugin Parameter

default-value="true"

encoding

private String encoding

The character encoding to use when writing the outputFile. The default value as configured by Maven will be ${project.build.sourceEncoding}. This field may be null at any point.

Plugin Parameter

default-value="${project.build.sourceEncoding}" property="encoding"

outputFile

private File outputFile

The File to which entity- and mapped superclass-annotated classnames will be written. This field may be null at any point. If this File is found to be relative, it will be relative to ${project.build.directory}${file.separator}generated-test-sources${file.separator}jpa-maven-plugin${file.separator}.

Plugin Parameter

default-value="${project.build.directory}${file.separator}generated-test-sources${file.separator}jpa-maven-plugin${file.separator}entityClassnames.properties" property="outputFile"

useOutputFile

boolean useOutputFile

Whether or not to write properties to an external file.

Plugin Parameter

default-value="true" property="useOutputFile"

defaultPropertyName

private String defaultPropertyName

The property key under which the entity classname listing will be stored. Maven will configure this by default to be entityClassnames. This field may be null at any point.

Plugin Parameter

default-value="entityClassnames" property="defaultPropertyName"

propertyNames

private Map<String,String> propertyNames

A Map of property names indexed by package prefix segments. Class names found belonging to packages that start with the given package prefix segment will be stored in the outputFile indexed by the corresponding property name.

Segments in package names are delimited with a period (.). The following are examples of package prefix segments:

• com.foobar.biz
• com.foobar
• com

Plugin Parameter

property="propertyNames"

firstItemPrefix

private String firstItemPrefix

The textual prefix to prepend to the list of classnames.

Plugin Parameter

default-value="" property="firstItemPrefix"

prefix

private String prefix

The textual prefix to prepend to every element of the list of classnames, excluding the first element.

Plugin Parameter

default-value="" property="prefix"

suffix

private String suffix

The suffix to append to every element of the list of classnames, excluding the last element. be null at any point.

Plugin Parameter

default-value="${line.separator}" property="suffix"

lastItemSuffix

private String lastItemSuffix

The suffix to append to the list of classnames.

Plugin Parameter

default-value="" property="lastItemSuffix"

urls

private Set<URL> urls

The Set of URLs to scan. If not explicitly specified, this mojo will scan the test classpath.

Plugin Parameter

property="URLs"

Constructor Detail

ListEntityClassnamesMojo

public ListEntityClassnamesMojo()

Creates a new ListEntityClassnamesMojo.

Method Detail

getPropertyNames

public Map<String,String> getPropertyNames()

Returns a Map of property names indexed by package fragments.

This method may return null.

Returns:

a Map of property names indexed by package fragments, or null

setPropertyNames

public void setPropertyNames(Map<String,String> propertyNames)

Sets the Map of property names indexed by package fragments that will be used to determine under which property name a given class name should be listed.

Note: it is technically permissible for the determinePropertyName(String) method to be overridden such that this Map is ignored.

Parameters:

propertyNames - the Map of property names indexed by package fragments; may be null in which case the default property name will be used for all classes

stripQuotes

final String stripQuotes(String text)

A workaround for MODELLO-256; strips leading and trailing quotes from the supplied text parameter value and returns the result.

This method may return null.

This method only does something if the stripQuotes field is set to true.

This method is package-private for testing only.

Parameters:

text - the text to strip; may be null in which case no substitution will occur

Returns:

the supplied text with leading and trailing quotes stripped, or null if the supplied text was null

See Also:

MODELLO-256

getPrefix

public String getPrefix()

Returns the prefix prepended to every element of the list of classnames, excluding the first element.

This method may return null.

Returns:

the prefix prepended to every element of the list of classnames, excluding the first element, or null

See Also:

setPrefix(String)

setPrefix

public void setPrefix(String prefix)

Sets the prefix prepended to every element of the list of classnames, excluding the first element.

Parameters:

prefix - the prefix in question; may be null

See Also:

getPrefix(), setFirstItemPrefix(String)

getFirstItemPrefix

public String getFirstItemPrefix()

Returns the prefix prepended to the list of classnames.

This method may return null.

Returns:

the prefix prepended to the list of classnames, or null

See Also:

getPrefix(), setFirstItemPrefix(String)

setFirstItemPrefix

public void setFirstItemPrefix(String firstItemPrefix)

Sets the prefix prepended to the list of classnames.

Parameters:

firstItemPrefix - the prefix to be prepended to the list of classnames; may be null

See Also:

getFirstItemPrefix(), setPrefix(String)

getSuffix

public String getSuffix()

Returns the suffix appended to every element of the list of classnames, excluding the last element.

This method may return null.

Returns:

the suffix appended to every element of the list of classnames, excluding the last element, or null

See Also:

setSuffix(String)

setSuffix

public void setSuffix(String suffix)

Sets the suffix appended to every element of the list of classnames, excluding the last element.

Parameters:

suffix - the suffix in question; may be null

See Also:

getSuffix(), setLastItemSuffix(String)

getLastItemSuffix

public String getLastItemSuffix()

Returns the suffix appended to the list of classnames.

This method may return null.

Returns:

the suffix appended to the list of classnames, or null

See Also:

getSuffix(), setLastItemSuffix(String)

setLastItemSuffix

public void setLastItemSuffix(String lastItemSuffix)

Sets the suffix appended to the list of classnames.

Parameters:

lastItemSuffix - the suffix to be appended to the list of classnames; may be null

See Also:

getLastItemSuffix(), setSuffix(String)

initializeURLs

private final Set<URL> initializeURLs()
                               throws org.apache.maven.artifact.DependencyResolutionRequiredException

Initializes the Set of URLs to scan and returns it.

This method calls setURLs(Set) as part of its implementation.

This method never returns null.

Returns:

the Set of URLs that will be returned by future calls to getURLs(); never null

Throws:

org.apache.maven.artifact.DependencyResolutionRequiredException

getTestClasspathURLs

private final Set<URL> getTestClasspathURLs()
                                     throws org.apache.maven.artifact.DependencyResolutionRequiredException

Returns a Set of URLs that represents the test classpath.

This uses the associated MavenProject to supply the information. If that MavenProject is null, then an empty unmodifiable Set is returned.

String-to-URL conversion is accomplished like this:

• The MavenProject.getTestClasspathElements() method returns an untyped List. There is no contractual guarantee about the type of its contents. Each element is therefore treated as an Object.
• If the element is non-null, then its Object.toString() method is invoked. The resulting String is used to construct a File.
• The resulting File's File.toURI() method is invoked and the result's URI.toURL() method is invoked. The return value is added to the Set that will be returned.

This method never returns null.

Returns:

a Set of URLs representing the test classpath, never null. The Set's iteration order is guaranteed to be equal to that of the iteration order of the return value of the MavenProject.getTestClasspathElements() method.

Throws:

org.apache.maven.artifact.DependencyResolutionRequiredException - if the MavenProject.getTestClasspathElements() method throws a DependencyResolutionRequiredException

getProjectBuildDirectoryName

public final String getProjectBuildDirectoryName()

Returns this ListEntityClassnamesMojo's best guess as to its related Maven project's build directory. If this ListEntityClassnamesMojo actually has a MavenProject installed, it will use the return value of that MavenProject's Build's getDirectory() method. Otherwise, it will return the following:

System.getProperty("maven.project.build.directory", 
                    System.getProperty("project.build.directory",
                                       String.format("%1$s%2$starget",
                                                     System.getProperty("basedir",
                                                                        System.getProperty("user.dir", ".")),
                                                     File.separator)));

This method never returns null.

Returns:

the current project's build directory name; never null

initializeOutputFile

private final File initializeOutputFile()
                                 throws FileException

Initializes the outputFile property and returns its value.

This method never returns null.

Returns:

the newly-set value of the outputFile property; never null

Throws:

FileException - if the outputFile property could not be initialized

initializeOutputFile

final File initializeOutputFile(File outputFile)
                         throws FileException

Validates and "absolutizes" the supplied File and returns the corrected version.

The return value of this method is guaranteed to be a File that is:

• non-null
• absolute
• existent and writable or non-existent and parented by a directory that is existent and writable

If the supplied File is a relative File, then it will be made absolute by prepending it with the following platform-neutral path: ${project.build.directory}/generated-test-sources/jpa-maven-plugin/

Parameters:

outputFile - the File to validate

Returns:

the "absolutized" and validated value of the outputFile parameter; never null

Throws:

FileException - if the supplied outputFile did not pass validation

validateOutputDirectory

private boolean validateOutputDirectory(File outputDirectory)
                                 throws FileException

Ensures that the supplied File, after this method is invoked, will designate a directory that exists and is writable.

Parameters:

outputDirectory - the File to validate; must not be null

Returns:

true if File.mkdirs() was invoked on outputDirectory; false otherwise

Throws:

IllegalArgumentException - if outputDirectory is null

FileException - if the supplied outputDirectory failed validation

initialize

private final void initialize()
                       throws org.apache.maven.artifact.DependencyResolutionRequiredException,
                              FileException

Called by the execute() method; initializes all fields to their defaults if for some reason they were not already set appropriately.

This method calls the following methods in order:

1. initializePropertyNames()
2. initializeURLs()
3. initializeOutputFile()

Throws:

org.apache.maven.artifact.DependencyResolutionRequiredException

FileException

initializePropertyNames

private final void initializePropertyNames()

Called by the initialize() method; sets up the propertyNames field appropriately.

getEncoding

public String getEncoding()

Returns the encoding used to write the Properties file that this mojo generates.

This method may return null.

Returns:

the encoding used to write the Properties file that this mojo generates, or null

setEncoding

public void setEncoding(String encoding)

Sets the encoding used to write the Properties file that this mojo generates.

If null is supplied to this method, then "UTF8" will be used instead.

Parameters:

encoding - the encoding to use; may be null in which case "UTF8" will be used instead; otherwise the value is trimmed and used as-is

getOutputFile

public File getOutputFile()

Returns the output File. This method does not perform any validation or initialization.

This method may return null.

Returns:

the output File, or null

See Also:

initializeOutputFile()

setOutputFile

public void setOutputFile(File file)

Sets the File to use as the output file parameter. This method does not perform any validation or initialization.

Parameters:

file - the File to use; may be null

See Also:

initializeOutputFile()

getUseOutputFile

public boolean getUseOutputFile()

Returns whether or not this ListEntityClassnamesMojo should write its properties out to the associated output file. By default this method returns true for backwards compatibility.

Returns:

whether or not this ListEntityClassnamesMojo should write its properties out to the associated output file

setUseOutputFile

public void setUseOutputFile(boolean useOutputFile)

Sets whether or not this ListEntityClassnamesMojo should write its properties out to the associated output file.

Parameters:

useOutputFile - whether or not to use the associated output file

getURLs

public Set<URL> getURLs()

Returns the Set of URLs to scan for annotations. This method does not perform any validation or initialization.

Returns:

the Set of URLs to scan, or null

See Also:

initializeURLs()

setURLs

public void setURLs(Set<URL> urls)

Sets the Set of URLs to scan for annotations. This method does not perform any validation or initialization.

Parameters:

urls - the Set of URLs to scan; may be null

See Also:

initializeURLs()

scan

private final AnnotationDB scan()
                         throws IOException,
                                MojoExecutionException,
                                MojoFailureException

Scans the Set of URLs this ListEntityClassnamesMojo has been configured with and returns the AnnotationDB that performed the scanning.

This method may return null in exceptional circumstances.

Returns:

an AnnotationDB containing the scan results, or null if an AnnotationDB could not be found

Throws:

MojoExecutionException - if this mojo could not execute

MojoFailureExcetpion - if the build should fail

IOException

MojoFailureException

execute

public void execute()
             throws MojoExecutionException,
                    MojoFailureException

Executes this mojo.

Throws:

MojoExecutionException - if this mojo could not be executed

MojoFailureException - if the build should fail

getDefaultPropertyName

public String getDefaultPropertyName()

Returns the property name to use for the names of Classes that belong to the default package.

This method may return null. However, other portions of this mojo's code may substitute a default value in such cases.

Returns:

the property name to use for the names of Classes that belong to the default package, or null

setDefaultPropertyName

public void setDefaultPropertyName(String defaultPropertyName)

Sets the property name to use for the names of Classes that belong to the default package.

Parameters:

defaultPropertyName - the property name; may be null, but this mojo may use a default value instead

determinePropertyName

public String determinePropertyName(String className)

Returns the appropriate property name given a class name.

If the supplied className is null or consists solely of whitespace, then the default property name is returned.

Otherwise, a property name is

decorate

protected String decorate(String classname,
                          String prefix,
                          String suffix)

Decorates the supplied class name with the supplied prefix and suffix parameters and returns the result.

This method may return null.

Parameters:

classname - the class name to decorate; if null then null will be returned

prefix - the prefix to decorate with; may be null

suffix - the suffix to decorate with; may be null

Returns:

the decorated class name, or null

createAnnotationDB

protected AnnotationDB createAnnotationDB()

Creates a new AnnotationDB in the (common) case where a user has not supplied this AbstractJPAMojo with a pre-configured AnnotationDB.

This method never returns null. Subclasses overriding this method must ensure that their overridden implementation never returns null.

This implementation overrides that of AbstractJPAMojo to ensure that the created AnnotationDB only scans Class-level annotations.

Overrides:

createAnnotationDB in class AbstractJPAMojo

Returns:

a new AnnotationDB; never null

See Also:

AnnotationDB, AnnotationDB