/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.apache.uima.fit.maven;
import java.io.File;
import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.OutputStreamWriter;
import java.io.PrintWriter;
import java.lang.reflect.Field;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import javassist.CannotCompileException;
import javassist.ClassPool;
import javassist.CtClass;
import javassist.CtField;
import javassist.LoaderClassPath;
import javassist.NotFoundException;
import javassist.bytecode.AnnotationsAttribute;
import javassist.bytecode.ClassFile;
import javassist.bytecode.ConstPool;
import javassist.bytecode.annotation.Annotation;
import javassist.bytecode.annotation.MemberValue;
import javassist.bytecode.annotation.StringMemberValue;
import org.apache.commons.io.IOUtils;
import org.apache.commons.io.LineIterator;
import org.apache.commons.lang.StringUtils;
import org.apache.commons.lang.exception.ExceptionUtils;
import org.apache.maven.plugin.AbstractMojo;
import org.apache.maven.plugin.MojoExecutionException;
import org.apache.maven.plugin.MojoFailureException;
import org.apache.maven.plugins.annotations.Component;
import org.apache.maven.plugins.annotations.LifecyclePhase;
import org.apache.maven.plugins.annotations.Mojo;
import org.apache.maven.plugins.annotations.Parameter;
import org.apache.maven.plugins.annotations.ResolutionScope;
import org.apache.maven.project.MavenProject;
import org.apache.uima.fit.descriptor.ResourceMetaData;
import org.apache.uima.fit.factory.ConfigurationParameterFactory;
import org.apache.uima.fit.factory.ExternalResourceFactory;
import org.apache.uima.fit.factory.ResourceMetaDataFactory;
import org.apache.uima.fit.internal.EnhancedClassFile;
import org.apache.uima.fit.maven.util.Util;
import org.codehaus.plexus.util.FileUtils;
import org.sonatype.plexus.build.incremental.BuildContext;
import com.google.common.collect.LinkedHashMultimap;
import com.google.common.collect.Multimap;
import com.thoughtworks.qdox.model.JavaSource;
/**
* Enhance UIMA components with automatically generated uimaFIT annotations.
*/
@Mojo(name = "enhance", defaultPhase = LifecyclePhase.PROCESS_CLASSES, requiresDependencyResolution = ResolutionScope.COMPILE, requiresDependencyCollection = ResolutionScope.COMPILE)
public class EnhanceMojo extends AbstractMojo {
@Component
private MavenProject project;
@Component
private BuildContext buildContext;
private ClassLoader componentLoader;
/**
* Override component description in generated descriptors.
*/
@Parameter(defaultValue = "false", required = true)
private boolean overrideComponentDescription;
/**
* Override version in generated descriptors.
*
* @see #componentVersion
*/
@Parameter(defaultValue = "false", required = true)
private boolean overrideComponentVersion;
/**
* Version to use in generated descriptors.
*/
@Parameter(defaultValue = "${project.version}", required = false)
private String componentVersion;
/**
* Override vendor in generated descriptors.
*
* @see #componentVendor
*/
@Parameter(defaultValue = "false", required = true)
private boolean overrideComponentVendor;
/**
* Vendor to use in generated descriptors.
*/
@Parameter(defaultValue = "${project.organization.name}", required = false)
private String componentVendor;
/**
* Override copyright in generated descriptors.
*
* @see #componentCopyright
*/
@Parameter(defaultValue = "false", required = true)
private boolean overrideComponentCopyright;
/**
* Copyright to use in generated descriptors.
*/
@Parameter(required = false)
private String componentCopyright;
/**
* Source file encoding.
*/
@Parameter(defaultValue = "${project.build.sourceEncoding}", required = true)
private String encoding;
/**
* Generate a report of missing meta data in {@code $ project.build.directory}
* /uimafit-missing-meta-data-report.txt}
*/
@Parameter(defaultValue = "true", required = true)
private boolean generateMissingMetaDataReport;
/**
* Fail on missing meta data. This setting has no effect unless
* {@code generateMissingMetaDataReport} is enabled.
*/
@Parameter(defaultValue = "false", required = true)
private boolean failOnMissingMetaData;
/**
* Constant name prefixes used for parameters and external resources, e.g. "PARAM_".
*/
@Parameter(required = false)
private String[] parameterNameConstantPrefixes = { "PARAM_" };
/**
* Constant name prefixes used for parameters and external resources, e.g. "KEY_", and "RES_".
*/
@Parameter(required = false)
private String[] externalResourceNameConstantPrefixes = { "KEY_", "RES_" };
/**
* Start of a line containing a class name in the missing meta data report file
*/
private static final String MARK_CLASS = "Class:";
/**
* Marker that no missing meta data report was found.
*/
private static final String MARK_NO_MISSING_META_DATA = "No missing meta data was found.";
public void execute() throws MojoExecutionException, MojoFailureException {
// Get the compiled classes from this project
String[] files = FileUtils.getFilesFromExtension(project.getBuild().getOutputDirectory(),
new String[] { "class" });
componentLoader = Util.getClassloader(project, getLog());
// Set up class pool with all the project dependencies and the project classes themselves
ClassPool classPool = new ClassPool(true);
classPool.appendClassPath(new LoaderClassPath(componentLoader));
// Set up map to keep a report per class.
Multimap<String, String> reportData = LinkedHashMultimap.create();
// Determine where to write the missing meta data report file
File reportFile = new File(project.getBuild().getDirectory(),
"uimafit-missing-meta-data-report.txt");
// Read existing report
if (generateMissingMetaDataReport) {
readMissingMetaDataReport(reportFile, reportData);
}
// Remember the names of all examined components, whether processed or not.
List<String> examinedComponents = new ArrayList<String>();
int countAlreadyEnhanced = 0;
int countEnhanced = 0;
for (String file : files) {
String clazzName = Util.getClassName(project, file);
// Check if this is a UIMA component
Class<?> clazz;
try {
clazz = componentLoader.loadClass(clazzName);
// Do not process a class twice
// UIMA-3853 workaround for IBM Java 8 beta 3
if (clazz.getAnnotation(EnhancedClassFile.class) != null) {
countAlreadyEnhanced++;
getLog().debug("Class [" + clazzName + "] already enhanced");
// Remember that class was examined
examinedComponents.add(clazzName);
continue;
}
// Only process UIMA components
if (!Util.isComponent(componentLoader, clazz)) {
continue;
}
} catch (ClassNotFoundException e) {
getLog().warn("Cannot analyze class [" + clazzName + "]", e);
continue;
}
// Remember that class was examined
examinedComponents.add(clazzName);
// Forget any previous missing meta data report we have on the class
reportData.removeAll(clazzName);
// Get the Javassist class
CtClass ctClazz;
try {
ctClazz = classPool.get(clazzName);
} catch (NotFoundException e) {
throw new MojoExecutionException("Class [" + clazzName + "] not found in class pool: "
+ ExceptionUtils.getRootCauseMessage(e), e);
}
// Get the source file
String sourceFile = getSourceFile(clazzName);
// Try to extract parameter descriptions from JavaDoc in source file
if (sourceFile != null) {
countEnhanced++;
getLog().debug("Enhancing class [" + clazzName + "]");
// Parse source file so we can extract the JavaDoc
JavaSource ast = parseSource(sourceFile);
// Enhance meta data
enhanceResourceMetaData(ast, clazz, ctClazz, reportData);
// Enhance configuration parameters
enhanceConfigurationParameter(ast, clazz, ctClazz, reportData);
// Add the EnhancedClassFile annotation.
markAsEnhanced(ctClazz);
} else {
getLog().warn("No source file found for class [" + clazzName + "]");
}
try {
if (ctClazz.isModified()) {
getLog().debug("Writing enhanced class [" + clazzName + "]");
// Trying to work around UIMA-2611, see
// http://stackoverflow.com/questions/13797919/javassist-add-method-and-invoke
ctClazz.toBytecode();
ctClazz.writeFile(project.getBuild().getOutputDirectory());
} else {
getLog().debug("No changes to class [" + clazzName + "]");
}
} catch (IOException e) {
throw new MojoExecutionException("Enhanced class [" + clazzName + "] cannot be written: "
+ ExceptionUtils.getRootCauseMessage(e), e);
} catch (CannotCompileException e) {
throw new MojoExecutionException("Enhanced class [" + clazzName + "] cannot be compiled: "
+ ExceptionUtils.getRootCauseMessage(e), e);
}
}
getLog().info(
"Enhanced " + countEnhanced + " class" + (countEnhanced != 1 ? "es" : "") + " ("
+ countAlreadyEnhanced + " already enhanced).");
if (generateMissingMetaDataReport) {
// Remove any classes from the report that are no longer part of the build
List<String> deletedClasses = new ArrayList<String>(reportData.keySet());
deletedClasses.removeAll(examinedComponents);
reportData.removeAll(deletedClasses);
// Write updated report
writeMissingMetaDataReport(reportFile, reportData);
if (failOnMissingMetaData && !reportData.isEmpty()) {
throw new MojoFailureException("Component meta data missing. A report of the missing "
+ "meta data can be found in " + reportFile);
}
}
}
/**
* Add the EnhancedClassFile annotation.
*/
private void markAsEnhanced(CtClass aCtClazz) {
ClassFile classFile = aCtClazz.getClassFile();
ConstPool constPool = classFile.getConstPool();
AnnotationsAttribute annoAttr = (AnnotationsAttribute) classFile
.getAttribute(AnnotationsAttribute.visibleTag);
// Create annotation attribute if it does not exist
if (annoAttr == null) {
annoAttr = new AnnotationsAttribute(constPool, AnnotationsAttribute.visibleTag);
}
// Create annotation if it does not exist
Annotation a = new Annotation(EnhancedClassFile.class.getName(), constPool);
// Replace annotation
annoAttr.addAnnotation(a);
// Replace annotation attribute
classFile.addAttribute(annoAttr);
}
/**
* Enhance resource meta data
*/
private void enhanceResourceMetaData(JavaSource aAST, Class<?> aClazz, CtClass aCtClazz,
Multimap<String, String> aReportData) {
ClassFile classFile = aCtClazz.getClassFile();
ConstPool constPool = classFile.getConstPool();
AnnotationsAttribute annoAttr = (AnnotationsAttribute) classFile
.getAttribute(AnnotationsAttribute.visibleTag);
// Create annotation attribute if it does not exist
if (annoAttr == null) {
annoAttr = new AnnotationsAttribute(constPool, AnnotationsAttribute.visibleTag);
}
// Create annotation if it does not exist
Annotation a = annoAttr.getAnnotation(ResourceMetaData.class.getName());
if (a == null) {
a = new Annotation(ResourceMetaData.class.getName(), constPool);
// Add a name, otherwise there will be none in the generated descriptor.
a.addMemberValue("name", new StringMemberValue(
ResourceMetaDataFactory.getDefaultName(aClazz), constPool));
}
// Update description from JavaDoc
String doc = Util.getComponentDocumentation(aAST, aClazz.getName());
enhanceMemberValue(a, "description", doc, overrideComponentDescription,
ResourceMetaDataFactory.getDefaultDescription(aClazz), constPool, aReportData, aClazz);
// Update version
enhanceMemberValue(a, "version", componentVersion, overrideComponentVersion,
ResourceMetaDataFactory.getDefaultVersion(aClazz), constPool, aReportData, aClazz);
// Update vendor
enhanceMemberValue(a, "vendor", componentVendor, overrideComponentVendor,
ResourceMetaDataFactory.getDefaultVendor(aClazz), constPool, aReportData, aClazz);
// Update copyright
enhanceMemberValue(a, "copyright", componentCopyright, overrideComponentCopyright,
ResourceMetaDataFactory.getDefaultCopyright(aClazz), constPool, aReportData, aClazz);
// Replace annotation
annoAttr.addAnnotation(a);
// Replace annotation attribute
classFile.addAttribute(annoAttr);
}
/**
* Set a annotation member value if no value is present, if the present value is the default
* generated by uimaFIT or if a override is active.
*
* @param aAnnotation
* an annotation
* @param aName
* the name of the member value
* @param aNewValue
* the value to set
* @param aOverride
* set value even if it is already set
* @param aDefault
* default value set by uimaFIT - if the member has this value, it is considered unset
*/
private void enhanceMemberValue(Annotation aAnnotation, String aName, String aNewValue,
boolean aOverride, String aDefault, ConstPool aConstPool,
Multimap<String, String> aReportData, Class<?> aClazz) {
String value = getStringMemberValue(aAnnotation, aName);
boolean isEmpty = value.length() == 0;
boolean isDefault = value.equals(aDefault);
if (isEmpty || isDefault || aOverride) {
if (aNewValue != null) {
aAnnotation.addMemberValue(aName, new StringMemberValue(aNewValue, aConstPool));
getLog().debug("Enhanced component meta data [" + aName + "]");
} else {
getLog().debug("No meta data [" + aName + "] found");
aReportData.put(aClazz.getName(), "No meta data [" + aName + "] found");
}
} else {
getLog().debug("Not overwriting component meta data [" + aName + "]");
}
}
private String getStringMemberValue(Annotation aAnnotation, String aValue) {
MemberValue v = aAnnotation.getMemberValue(aValue);
if (v == null) {
return "";
} else {
return ((StringMemberValue) v).getValue();
}
}
/**
* Enhance descriptions in configuration parameters.
*/
private void enhanceConfigurationParameter(JavaSource aAST, Class<?> aClazz, CtClass aCtClazz,
Multimap<String, String> aReportData) throws MojoExecutionException {
// Get the parameter name constants
Map<String, String> parameterNameFields = getParameterConstants(aClazz,
parameterNameConstantPrefixes);
Map<String, String> resourceNameFields = getParameterConstants(aClazz,
externalResourceNameConstantPrefixes);
// Fetch configuration parameters from the @ConfigurationParameter annotations in the
// compiled class. We only need the fields in the class itself. Superclasses should be
// enhanced by themselves.
for (Field field : aClazz.getDeclaredFields()) {
final String pname;
final String type;
final String pdesc;
// Is this a configuration parameter?
if (ConfigurationParameterFactory.isConfigurationParameterField(field)) {
type = "parameter";
// Extract configuration parameter information from the uimaFIT annotation
pname = ConfigurationParameterFactory.createPrimitiveParameter(field).getName();
// Extract JavaDoc for this resource from the source file
pdesc = Util.getParameterDocumentation(aAST, field.getName(),
parameterNameFields.get(pname));
}
// Is this an external resource?
else if (ExternalResourceFactory.isExternalResourceField(field)) {
type = "external resource";
// Extract resource key from the uimaFIT annotation
pname = ExternalResourceFactory.createExternalResourceDependency(field).getKey();
// Extract JavaDoc for this resource from the source file
pdesc = Util.getParameterDocumentation(aAST, field.getName(),
resourceNameFields.get(pname));
} else {
continue;
}
if (pdesc == null) {
String msg = "No description found for " + type + " [" + pname + "]";
getLog().debug(msg);
aReportData.put(aClazz.getName(), msg);
continue;
}
// Update the "description" field of the annotation
try {
CtField ctField = aCtClazz.getField(field.getName());
AnnotationsAttribute annoAttr = (AnnotationsAttribute) ctField.getFieldInfo().getAttribute(
AnnotationsAttribute.visibleTag);
// Locate and update annotation
if (annoAttr != null) {
Annotation[] annotations = annoAttr.getAnnotations();
// Update existing annotation
for (Annotation a : annotations) {
if (a.getTypeName().equals(
org.apache.uima.fit.descriptor.ConfigurationParameter.class.getName())
|| a.getTypeName().equals(
org.apache.uima.fit.descriptor.ExternalResource.class.getName())
|| a.getTypeName().equals("org.uimafit.descriptor.ConfigurationParameter")
|| a.getTypeName().equals("org.uimafit.descriptor.ExternalResource")) {
if (a.getMemberValue("description") == null) {
a.addMemberValue("description", new StringMemberValue(pdesc, aCtClazz
.getClassFile().getConstPool()));
getLog().debug("Enhanced description of " + type + " [" + pname + "]");
// Replace updated annotation
annoAttr.addAnnotation(a);
} else {
// Extract configuration parameter information from the uimaFIT annotation
// We only want to override if the description is not set yet.
getLog().debug("Not overwriting description of " + type + " [" + pname + "] ");
}
}
}
}
// Replace annotations
ctField.getFieldInfo().addAttribute(annoAttr);
} catch (NotFoundException e) {
throw new MojoExecutionException("Field [" + field.getName() + "] not found in byte code: "
+ ExceptionUtils.getRootCauseMessage(e), e);
}
}
}
/**
* Get a map of parameter name to parameter name constant field, e.g. ("value",
* Field("PARAM_VALUE")).
*/
private Map<String, String> getParameterConstants(Class<?> aClazz, String[] aPrefixes) {
Map<String, String> result = new HashMap<String, String>();
for (Field f : aClazz.getFields()) {
boolean hasPrefix = false;
// Check if any of the registered prefixes matches
for (String prefix : aPrefixes) {
if (f.getName().startsWith(prefix)) {
hasPrefix = true;
break;
}
}
// If none matched, continue
if (!hasPrefix) {
continue;
}
// If one matched, record the field
try {
String parameterName = (String) f.get(null);
result.put(parameterName, f.getName());
} catch (IllegalAccessException e) {
getLog().warn(
"Unable to access name constant field [" + f.getName() + "]: "
+ ExceptionUtils.getRootCauseMessage(e), e);
}
}
return result;
}
private JavaSource parseSource(String aSourceFile) throws MojoExecutionException {
try {
return Util.parseSource(aSourceFile, encoding);
} catch (IOException e) {
throw new MojoExecutionException("Unable to parse source file [" + aSourceFile + "]: "
+ ExceptionUtils.getRootCauseMessage(e), e);
}
}
/**
* Get the source file for the given class.
*
* @return The path to the source file or {@code null} if no source file was found.
*/
@SuppressWarnings("unchecked")
private String getSourceFile(String aClassName) {
String sourceName = aClassName.replace('.', '/') + ".java";
for (String root : (List<String>) project.getCompileSourceRoots()) {
File f = new File(root, sourceName);
if (f.exists()) {
return f.getPath();
}
}
return null;
}
/**
* Write a report on any meta data missing from components.
*/
private void writeMissingMetaDataReport(File aReportFile, Multimap<String, String> aReportData)
throws MojoExecutionException {
String[] classes = aReportData.keySet().toArray(new String[aReportData.keySet().size()]);
Arrays.sort(classes);
PrintWriter out = null;
FileUtils.mkdir(aReportFile.getParent());
try {
out = new PrintWriter(new OutputStreamWriter(new FileOutputStream(aReportFile), encoding));
if (classes.length > 0) {
for (String clazz : classes) {
out.printf("%s %s%n", MARK_CLASS, clazz);
Collection<String> messages = aReportData.get(clazz);
if (messages.isEmpty()) {
out.printf(" No problems");
} else {
for (String message : messages) {
out.printf(" %s%n", message);
}
}
out.printf("%n");
}
} else {
out.printf("%s%n", MARK_NO_MISSING_META_DATA);
}
} catch (IOException e) {
throw new MojoExecutionException("Unable to write missing meta data report to ["
+ aReportFile + "]" + ExceptionUtils.getRootCauseMessage(e), e);
} finally {
IOUtils.closeQuietly(out);
}
}
/**
* Read the missing meta data report from a previous run.
*/
private void readMissingMetaDataReport(File aReportFile, Multimap<String, String> aReportData)
throws MojoExecutionException {
if (!aReportFile.exists()) {
// Ignore if the file is missing
return;
}
LineIterator i = null;
try {
String clazz = null;
i = IOUtils.lineIterator(new FileInputStream(aReportFile), encoding);
while (i.hasNext()) {
String line = i.next();
// Report say there is no missing meta data
if (line.startsWith(MARK_NO_MISSING_META_DATA)) {
return;
}
// Line containing class name
if (line.startsWith(MARK_CLASS)) {
clazz = line.substring(MARK_CLASS.length()).trim();
} else if (StringUtils.isBlank(line)) {
// Empty line, ignore
} else {
// Line containing a missing meta data instance
if (clazz == null) {
throw new MojoExecutionException("Missing meta data report has invalid format.");
}
aReportData.put(clazz, line.trim());
}
}
} catch (IOException e) {
throw new MojoExecutionException("Unable to read missing meta data report: "
+ ExceptionUtils.getRootCauseMessage(e), e);
} finally {
LineIterator.closeQuietly(i);
}
}
}