/*
    * 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.maven.tools.plugin.extractor.javadoc;
  
  import javax.inject.Named;
  import javax.inject.Singleton;
  
  import java.io.File;
  import java.net.MalformedURLException;
  import java.net.URL;
  import java.net.URLClassLoader;
  import java.util.ArrayList;
  import java.util.Collection;
  import java.util.List;
  import java.util.Map;
  import java.util.TreeMap;
  
  import com.thoughtworks.qdox.JavaProjectBuilder;
  import com.thoughtworks.qdox.library.SortedClassLibraryBuilder;
  import com.thoughtworks.qdox.model.DocletTag;
  import com.thoughtworks.qdox.model.JavaClass;
  import com.thoughtworks.qdox.model.JavaField;
  import com.thoughtworks.qdox.model.JavaType;
  import org.apache.maven.artifact.Artifact;
  import org.apache.maven.plugin.descriptor.InvalidParameterException;
  import org.apache.maven.plugin.descriptor.InvalidPluginDescriptorException;
  import org.apache.maven.plugin.descriptor.MojoDescriptor;
  import org.apache.maven.plugin.descriptor.Parameter;
  import org.apache.maven.plugin.descriptor.Requirement;
  import org.apache.maven.project.MavenProject;
  import org.apache.maven.tools.plugin.ExtendedMojoDescriptor;
  import org.apache.maven.tools.plugin.PluginToolsRequest;
  import org.apache.maven.tools.plugin.extractor.ExtractionException;
  import org.apache.maven.tools.plugin.extractor.GroupKey;
  import org.apache.maven.tools.plugin.extractor.MojoDescriptorExtractor;
  import org.apache.maven.tools.plugin.util.PluginUtils;
  import org.codehaus.plexus.logging.AbstractLogEnabled;
  
  /**
   * <p>
   * Extracts Mojo descriptors from <a href="https://www.oracle.com/java/technologies//">Java</a> source
   * javadoc comments only. New mojos should rather rely on annotations and comments which are evaluated
   * by extractor named {@code java}.
   * </p>
   * For more information about the usage tag, have a look to:
   * <a href="https://maven.apache.org/developers/mojo-api-specification.html">
   * https://maven.apache.org/developers/mojo-api-specification.html</a>
   *
   * @see org.apache.maven.plugin.descriptor.MojoDescriptor
   */
  @Named(JavaJavadocMojoDescriptorExtractor.NAME)
  @Singleton
  public class JavaJavadocMojoDescriptorExtractor extends AbstractLogEnabled
          implements MojoDescriptorExtractor, JavadocMojoAnnotation {
      public static final String NAME = "java-javadoc";
  
      private static final GroupKey GROUP_KEY = new GroupKey(GroupKey.JAVA_GROUP, 200);
  
      @Override
      public String getName() {
          return NAME;
      }
  
      @Override
      public boolean isDeprecated() {
          return true; // one should use Java5 annotations instead
      }
  
      @Override
      public GroupKey getGroupKey() {
          return GROUP_KEY;
      }
  
      /**
       * @param parameter not null
       * @param i positive number
       * @throws InvalidParameterException if any
       */
      protected void validateParameter(Parameter parameter, int i) throws InvalidParameterException {
          // TODO: remove when backward compatibility is no longer an issue.
          String name = parameter.getName();
  
          if (name == null) {
             throw new InvalidParameterException("name", i);
         }
 
         // TODO: remove when backward compatibility is no longer an issue.
         String type = parameter.getType();
 
         if (type == null) {
             throw new InvalidParameterException("type", i);
         }
 
         // TODO: remove when backward compatibility is no longer an issue.
         String description = parameter.getDescription();
 
         if (description == null) {
             throw new InvalidParameterException("description", i);
         }
     }
 
     // ----------------------------------------------------------------------
     // Mojo descriptor creation from @tags
     // ----------------------------------------------------------------------
 
     /**
      * @param javaClass not null
      * @return a mojo descriptor
      * @throws InvalidPluginDescriptorException if any
      */
     protected MojoDescriptor createMojoDescriptor(JavaClass javaClass) throws InvalidPluginDescriptorException {
         ExtendedMojoDescriptor mojoDescriptor = new ExtendedMojoDescriptor();
         mojoDescriptor.setLanguage("java");
         mojoDescriptor.setImplementation(javaClass.getFullyQualifiedName());
         mojoDescriptor.setDescription(javaClass.getComment());
 
         // ----------------------------------------------------------------------
         // Mojo annotations in alphabetical order
         // ----------------------------------------------------------------------
 
         // Aggregator flag
         DocletTag aggregator = findInClassHierarchy(javaClass, JavadocMojoAnnotation.AGGREGATOR);
         if (aggregator != null) {
             mojoDescriptor.setAggregator(true);
         }
 
         // Configurator hint
         DocletTag configurator = findInClassHierarchy(javaClass, JavadocMojoAnnotation.CONFIGURATOR);
         if (configurator != null) {
             mojoDescriptor.setComponentConfigurator(configurator.getValue());
         }
 
         // Additional phase to execute first
         DocletTag execute = findInClassHierarchy(javaClass, JavadocMojoAnnotation.EXECUTE);
         if (execute != null) {
             String executePhase = execute.getNamedParameter(JavadocMojoAnnotation.EXECUTE_PHASE);
             String executeGoal = execute.getNamedParameter(JavadocMojoAnnotation.EXECUTE_GOAL);
 
             if (executePhase == null && executeGoal == null) {
                 throw new InvalidPluginDescriptorException(javaClass.getFullyQualifiedName()
                         + ": @execute tag requires either a 'phase' or 'goal' parameter");
             } else if (executePhase != null && executeGoal != null) {
                 throw new InvalidPluginDescriptorException(javaClass.getFullyQualifiedName()
                         + ": @execute tag can have only one of a 'phase' or 'goal' parameter");
             }
             mojoDescriptor.setExecutePhase(executePhase);
             mojoDescriptor.setExecuteGoal(executeGoal);
 
             String lifecycle = execute.getNamedParameter(JavadocMojoAnnotation.EXECUTE_LIFECYCLE);
             if (lifecycle != null) {
                 mojoDescriptor.setExecuteLifecycle(lifecycle);
                 if (mojoDescriptor.getExecuteGoal() != null) {
                     throw new InvalidPluginDescriptorException(javaClass.getFullyQualifiedName()
                             + ": @execute lifecycle requires a phase instead of a goal");
                 }
             }
         }
 
         // Goal name
         DocletTag goal = findInClassHierarchy(javaClass, JavadocMojoAnnotation.GOAL);
         if (goal != null) {
             mojoDescriptor.setGoal(goal.getValue());
         }
 
         // inheritByDefault flag
         boolean value = getBooleanTagValue(
                 javaClass, JavadocMojoAnnotation.INHERIT_BY_DEFAULT, mojoDescriptor.isInheritedByDefault());
         mojoDescriptor.setInheritedByDefault(value);
 
         // instantiationStrategy
         DocletTag tag = findInClassHierarchy(javaClass, JavadocMojoAnnotation.INSTANTIATION_STRATEGY);
         if (tag != null) {
             mojoDescriptor.setInstantiationStrategy(tag.getValue());
         }
 
         // executionStrategy (and deprecated @attainAlways)
         tag = findInClassHierarchy(javaClass, JavadocMojoAnnotation.MULTI_EXECUTION_STRATEGY);
         if (tag != null) {
             getLogger()
                     .warn("@" + JavadocMojoAnnotation.MULTI_EXECUTION_STRATEGY + " in "
                             + javaClass.getFullyQualifiedName() + " is deprecated: please use '@"
                             + JavadocMojoAnnotation.EXECUTION_STATEGY + " always' instead.");
             mojoDescriptor.setExecutionStrategy(MojoDescriptor.MULTI_PASS_EXEC_STRATEGY);
         } else {
             mojoDescriptor.setExecutionStrategy(MojoDescriptor.SINGLE_PASS_EXEC_STRATEGY);
         }
         tag = findInClassHierarchy(javaClass, JavadocMojoAnnotation.EXECUTION_STATEGY);
         if (tag != null) {
             mojoDescriptor.setExecutionStrategy(tag.getValue());
         }
 
         // Phase name
         DocletTag phase = findInClassHierarchy(javaClass, JavadocMojoAnnotation.PHASE);
         if (phase != null) {
             mojoDescriptor.setPhase(phase.getValue());
         }
 
         // Dependency resolution flag
         DocletTag requiresDependencyResolution =
                 findInClassHierarchy(javaClass, JavadocMojoAnnotation.REQUIRES_DEPENDENCY_RESOLUTION);
         if (requiresDependencyResolution != null) {
             String v = requiresDependencyResolution.getValue();
 
             if (v == null || v.isEmpty()) {
                 v = "runtime";
             }
 
             mojoDescriptor.setDependencyResolutionRequired(v);
         }
 
         // Dependency collection flag
         DocletTag requiresDependencyCollection =
                 findInClassHierarchy(javaClass, JavadocMojoAnnotation.REQUIRES_DEPENDENCY_COLLECTION);
         if (requiresDependencyCollection != null) {
             String v = requiresDependencyCollection.getValue();
 
             if (v == null || v.isEmpty()) {
                 v = "runtime";
             }
 
             mojoDescriptor.setDependencyCollectionRequired(v);
         }
 
         // requiresDirectInvocation flag
         value = getBooleanTagValue(
                 javaClass, JavadocMojoAnnotation.REQUIRES_DIRECT_INVOCATION, mojoDescriptor.isDirectInvocationOnly());
         mojoDescriptor.setDirectInvocationOnly(value);
 
         // Online flag
         value = getBooleanTagValue(javaClass, JavadocMojoAnnotation.REQUIRES_ONLINE, mojoDescriptor.isOnlineRequired());
         mojoDescriptor.setOnlineRequired(value);
 
         // Project flag
         value = getBooleanTagValue(
                 javaClass, JavadocMojoAnnotation.REQUIRES_PROJECT, mojoDescriptor.isProjectRequired());
         mojoDescriptor.setProjectRequired(value);
 
         // requiresReports flag
         value = getBooleanTagValue(
                 javaClass, JavadocMojoAnnotation.REQUIRES_REPORTS, mojoDescriptor.isRequiresReports());
         mojoDescriptor.setRequiresReports(value);
 
         // ----------------------------------------------------------------------
         // Javadoc annotations in alphabetical order
         // ----------------------------------------------------------------------
 
         // Deprecation hint
         DocletTag deprecated = javaClass.getTagByName(JavadocMojoAnnotation.DEPRECATED);
         if (deprecated != null) {
             mojoDescriptor.setDeprecated(deprecated.getValue());
         }
 
         // What version it was introduced in
         DocletTag since = findInClassHierarchy(javaClass, JavadocMojoAnnotation.SINCE);
         if (since != null) {
             mojoDescriptor.setSince(since.getValue());
         }
 
         // Thread-safe mojo
 
         value = getBooleanTagValue(javaClass, JavadocMojoAnnotation.THREAD_SAFE, true, mojoDescriptor.isThreadSafe());
         mojoDescriptor.setThreadSafe(value);
 
         extractParameters(mojoDescriptor, javaClass);
 
         return mojoDescriptor;
     }
 
     /**
      * @param javaClass not null
      * @param tagName not null
      * @param defaultValue the wanted default value
      * @return the boolean value of the given tagName
      * @see #findInClassHierarchy(JavaClass, String)
      */
     private static boolean getBooleanTagValue(JavaClass javaClass, String tagName, boolean defaultValue) {
         DocletTag tag = findInClassHierarchy(javaClass, tagName);
 
         if (tag != null) {
             String value = tag.getValue();
 
             if (value != null && !value.isEmpty()) {
                 defaultValue = Boolean.valueOf(value).booleanValue();
             }
         }
         return defaultValue;
     }
 
     /**
      * @param javaClass     not null
      * @param tagName       not null
      * @param defaultForTag The wanted default value when only the tagname is present
      * @param defaultValue  the wanted default value when the tag is not specified
      * @return the boolean value of the given tagName
      * @see #findInClassHierarchy(JavaClass, String)
      */
     private static boolean getBooleanTagValue(
             JavaClass javaClass, String tagName, boolean defaultForTag, boolean defaultValue) {
         DocletTag tag = findInClassHierarchy(javaClass, tagName);
 
         if (tag != null) {
             String value = tag.getValue();
 
             if (value != null && !value.isEmpty()) {
                 return Boolean.valueOf(value).booleanValue();
             } else {
                 return defaultForTag;
             }
         }
         return defaultValue;
     }
 
     /**
      * @param javaClass not null
      * @param tagName not null
      * @return docletTag instance
      */
     private static DocletTag findInClassHierarchy(JavaClass javaClass, String tagName) {
         DocletTag tag = javaClass.getTagByName(tagName);
 
         if (tag == null) {
             JavaClass superClass = javaClass.getSuperJavaClass();
 
             if (superClass != null) {
                 tag = findInClassHierarchy(superClass, tagName);
             }
         }
 
         return tag;
     }
 
     /**
      * @param mojoDescriptor not null
      * @param javaClass not null
      * @throws InvalidPluginDescriptorException if any
      */
     private void extractParameters(MojoDescriptor mojoDescriptor, JavaClass javaClass)
             throws InvalidPluginDescriptorException {
         // ---------------------------------------------------------------------------------
         // We're resolving class-level, ancestor-class-field, local-class-field order here.
         // ---------------------------------------------------------------------------------
 
         Map<String, JavaField> rawParams = extractFieldParameterTags(javaClass);
 
         for (Map.Entry<String, JavaField> entry : rawParams.entrySet()) {
             JavaField field = entry.getValue();
 
             JavaType type = field.getType();
 
             Parameter pd = new Parameter();
 
             pd.setName(entry.getKey());
 
             pd.setType(type.getFullyQualifiedName());
 
             pd.setDescription(field.getComment());
 
             DocletTag deprecationTag = field.getTagByName(JavadocMojoAnnotation.DEPRECATED);
 
             if (deprecationTag != null) {
                 pd.setDeprecated(deprecationTag.getValue());
             }
 
             DocletTag sinceTag = field.getTagByName(JavadocMojoAnnotation.SINCE);
             if (sinceTag != null) {
                 pd.setSince(sinceTag.getValue());
             }
 
             DocletTag componentTag = field.getTagByName(JavadocMojoAnnotation.COMPONENT);
 
             if (componentTag != null) {
                 // Component tag
                 String role = componentTag.getNamedParameter(JavadocMojoAnnotation.COMPONENT_ROLE);
 
                 if (role == null) {
                     role = field.getType().toString();
                 }
 
                 String roleHint = componentTag.getNamedParameter(JavadocMojoAnnotation.COMPONENT_ROLEHINT);
 
                 if (roleHint == null) {
                     // support alternate syntax for better compatibility with the Plexus CDC.
                     roleHint = componentTag.getNamedParameter("role-hint");
                 }
 
                 // recognize Maven-injected objects as components annotations instead of parameters
                 // Note: the expressions we are looking for, i.e. "${project}", are in the values of the Map,
                 // so the lookup mechanism is different here than in maven-plugin-tools-annotations
                 boolean isDeprecated = PluginUtils.MAVEN_COMPONENTS.containsValue(role);
 
                 if (!isDeprecated) {
                     // normal component
                     pd.setRequirement(new Requirement(role, roleHint));
                 } else {
                     // not a component but a Maven object to be transformed into an expression/property
                     getLogger()
                             .warn("Deprecated @component Javadoc tag for '" + pd.getName() + "' field in "
                                     + javaClass.getFullyQualifiedName()
                                     + ": replace with @Parameter( defaultValue = \"" + role
                                     + "\", readonly = true )");
                     pd.setDefaultValue(role);
                     pd.setRequired(true);
                 }
 
                 pd.setEditable(false);
                 /* TODO: or better like this? Need @component fields be editable for the user?
                 pd.setEditable( field.getTagByName( READONLY ) == null );
                 */
             } else {
                 // Parameter tag
                 DocletTag parameter = field.getTagByName(JavadocMojoAnnotation.PARAMETER);
 
                 pd.setRequired(field.getTagByName(JavadocMojoAnnotation.REQUIRED) != null);
 
                 pd.setEditable(field.getTagByName(JavadocMojoAnnotation.READONLY) == null);
 
                 String name = parameter.getNamedParameter(JavadocMojoAnnotation.PARAMETER_NAME);
 
                 if (!(name == null || name.isEmpty())) {
                     pd.setName(name);
                 }
 
                 String alias = parameter.getNamedParameter(JavadocMojoAnnotation.PARAMETER_ALIAS);
 
                 if (!(alias == null || alias.isEmpty())) {
                     pd.setAlias(alias);
                 }
 
                 String expression = parameter.getNamedParameter(JavadocMojoAnnotation.PARAMETER_EXPRESSION);
                 String property = parameter.getNamedParameter(JavadocMojoAnnotation.PARAMETER_PROPERTY);
 
                 if ((expression != null && !expression.isEmpty()) && (property != null && !property.isEmpty())) {
                     getLogger().error(javaClass.getFullyQualifiedName() + "#" + field.getName() + ":");
                     getLogger().error("  Cannot use both:");
                     getLogger().error("    @parameter expression=\"${property}\"");
                     getLogger().error("  and");
                     getLogger().error("    @parameter property=\"property\"");
                     getLogger().error("  Second syntax is preferred.");
                     throw new InvalidParameterException(
                             javaClass.getFullyQualifiedName() + "#" + field.getName() + ": cannot"
                                     + " use both @parameter expression and property",
                             null);
                 }
 
                 if (expression != null && !expression.isEmpty()) {
                     getLogger().warn(javaClass.getFullyQualifiedName() + "#" + field.getName() + ":");
                     getLogger().warn("  The syntax");
                     getLogger().warn("    @parameter expression=\"${property}\"");
                     getLogger().warn("  is deprecated, please use");
                     getLogger().warn("    @parameter property=\"property\"");
                     getLogger().warn("  instead.");
 
                 } else if (property != null && !property.isEmpty()) {
                     expression = "${" + property + "}";
                 }
 
                 pd.setExpression(expression);
 
                 if ((expression != null && !expression.isEmpty()) && expression.startsWith("${component.")) {
                     getLogger().warn(javaClass.getFullyQualifiedName() + "#" + field.getName() + ":");
                     getLogger().warn("  The syntax");
                     getLogger().warn("    @parameter expression=\"${component.<role>#<roleHint>}\"");
                     getLogger().warn("  is deprecated, please use");
                     getLogger().warn("    @component role=\"<role>\" roleHint=\"<roleHint>\"");
                     getLogger().warn("  instead.");
                 }
 
                 if ("${reports}".equals(pd.getExpression())) {
                     mojoDescriptor.setRequiresReports(true);
                 }
 
                 pd.setDefaultValue(parameter.getNamedParameter(JavadocMojoAnnotation.PARAMETER_DEFAULT_VALUE));
 
                 pd.setImplementation(parameter.getNamedParameter(JavadocMojoAnnotation.PARAMETER_IMPLEMENTATION));
             }
 
             mojoDescriptor.addParameter(pd);
         }
     }
 
     /**
      * extract fields that are either parameters or components.
      *
      * @param javaClass not null
      * @return map with Mojo parameters names as keys
      */
     private Map<String, JavaField> extractFieldParameterTags(JavaClass javaClass) {
         Map<String, JavaField> rawParams;
 
         // we have to add the parent fields first, so that they will be overwritten by the local fields if
         // that actually happens...
         JavaClass superClass = javaClass.getSuperJavaClass();
 
         if (superClass != null) {
             rawParams = extractFieldParameterTags(superClass);
         } else {
             rawParams = new TreeMap<String, JavaField>();
         }
 
         for (JavaField field : javaClass.getFields()) {
             if (field.getTagByName(JavadocMojoAnnotation.PARAMETER) != null
                     || field.getTagByName(JavadocMojoAnnotation.COMPONENT) != null) {
                 rawParams.put(field.getName(), field);
             }
         }
         return rawParams;
     }
 
     @Override
     public List<MojoDescriptor> execute(PluginToolsRequest request)
             throws ExtractionException, InvalidPluginDescriptorException {
         Collection<JavaClass> javaClasses = discoverClasses(request);
 
         List<MojoDescriptor> descriptors = new ArrayList<>();
 
         for (JavaClass javaClass : javaClasses) {
             DocletTag tag = javaClass.getTagByName(GOAL);
 
             if (tag != null) {
                 MojoDescriptor mojoDescriptor = createMojoDescriptor(javaClass);
                 mojoDescriptor.setPluginDescriptor(request.getPluginDescriptor());
 
                 // Validate the descriptor as best we can before allowing it to be processed.
                 validate(mojoDescriptor);
 
                 descriptors.add(mojoDescriptor);
             }
         }
 
         return descriptors;
     }
 
     /**
      * @param request The plugin request.
      * @return an array of java class
      */
     protected Collection<JavaClass> discoverClasses(final PluginToolsRequest request) {
         JavaProjectBuilder builder = new JavaProjectBuilder(new SortedClassLibraryBuilder());
         builder.setEncoding(request.getEncoding());
 
         // Build isolated Classloader with only the artifacts of the project (none of this plugin)
         List<URL> urls = new ArrayList<>(request.getDependencies().size());
         for (Artifact artifact : request.getDependencies()) {
             try {
                 urls.add(artifact.getFile().toURI().toURL());
             } catch (MalformedURLException e) {
                 // noop
             }
         }
         builder.addClassLoader(new URLClassLoader(urls.toArray(new URL[0]), ClassLoader.getSystemClassLoader()));
 
         MavenProject project = request.getProject();
 
         for (String source : project.getCompileSourceRoots()) {
             builder.addSourceTree(new File(source));
         }
 
         // TODO be more dynamic
         File generatedPlugin = new File(project.getBasedir(), "target/generated-sources/plugin");
         if (!project.getCompileSourceRoots().contains(generatedPlugin.getAbsolutePath())) {
             builder.addSourceTree(generatedPlugin);
         }
 
         return builder.getClasses();
     }
 
     /**
      * @param mojoDescriptor not null
      * @throws InvalidParameterException if any
      */
     protected void validate(MojoDescriptor mojoDescriptor) throws InvalidParameterException {
         List<Parameter> parameters = mojoDescriptor.getParameters();
 
         if (parameters != null) {
             for (int j = 0; j < parameters.size(); j++) {
                 validateParameter(parameters.get(j), j);
             }
         }
     }
 }