package de.matthias_burbach.deputy.core;
   
   import java.io.File;
   import java.util.ArrayList;
   import java.util.Collections;
   import java.util.HashMap;
   import java.util.Iterator;
   import java.util.List;
   import java.util.Map;
  
  import org.jdom.Attribute;
  import org.jdom.Document;
  import org.jdom.Element;
  import org.jdom.input.SAXBuilder;
  import org.jdom.xpath.XPath;
  
  import de.matthias_burbach.deputy.core.project.Project;
  import de.matthias_burbach.deputy.core.project.ProjectQualifier;
  import de.matthias_burbach.deputy.core.project.ProjectQualifierImpl;
  import de.matthias_burbach.deputy.core.project.VersionComparator;
  import de.matthias_burbach.deputy.core.repository.RepositoryConfig;
  import de.matthias_burbach.deputy.core.repository.VersionScanner;
  import de.matthias_burbach.deputy.core.rule.DeprecationRule;
  import de.matthias_burbach.deputy.core.rule.EnforcementRule;
  import de.matthias_burbach.deputy.core.rule.RemovalRule;
  import de.matthias_burbach.deputy.core.rule.ReplacementRule;
  import de.matthias_burbach.deputy.core.rule.RetentionRule;
  import de.matthias_burbach.deputy.core.rule.RuleSet;
  import de.matthias_burbach.deputy.core.util.Log;
  
  /***
   * Parses a project and its dependencies recursively. Applies rules to decide
   * which versions of the dependencies to follow while parsing.
   *
   * @author Matthias Burbach
   */
  public class ProjectRecursor {
      /***
       * Bundles properties that occur in a dependency declaration.
       *
       * @author Matthias Burbach
       */
      private class ProjectReference {
          /***
           * The referenced project's group id.
           */
          private String groupId;
  
          /***
           * The referenced project's artifact id.
           */
          private String artifactId;
  
          /***
           * The referenced project's version.
           */
          private String version;
  
          /***
           * The referenced project's jar file name.
           */
          private String jar;
  
          /***
           * The referenced project's type.
           */
          private String type;
  
          /***
           * The referenced project's hompage URL.
           */
          private String url;
  
          /***
           * @param groupId The referenced project's group id.
           * @param artifactId The referenced project's artifact id.
           * @param version The referenced project's version.
           * @param jar The referenced project's jar file name.
           * @param type The referenced project's type.
           * @param url The referenced project's hompage URL.
           */
          public ProjectReference(
                  final String groupId,
                  final String artifactId,
                  final String version,
                  final String jar,
                  final String type,
                  final String url) {
              this.groupId = groupId;
              this.artifactId = artifactId;
              this.version = version;
              this.jar = jar;
              this.type = type;
              this.url = url;
          }
  
          /***
           * @return Returns the artifactId.
           */
         public String getArtifactId() {
             return artifactId;
         }
 
         /***
          * @return Returns the groupId.
          */
         public String getGroupId() {
             return groupId;
         }
 
         /***
          * @return Returns the type.
          */
         public String getType() {
             return type;
         }
 
         /***
          * @return Returns the jar.
          */
         public String getJar() {
             return jar;
         }
 
         /***
          * @return Returns the url.
          */
         public String getUrl() {
             return url;
         }
 
         /***
          * @return Returns the version.
          */
         public String getVersion() {
             return version;
         }
     }
 
     /***
      * Parses the graph of dependencies recursively as is,
      * i. e. as it is literally defined by the dependencies in the project.xml
      * files.
      */
     private static final int STRATEGY_AS_IS = 0;
 
     /***
      * Parses the graph of dependencies recursively, but usually follows
      * versions according to rules instead of what is defined in the
      * dependencies of the project.xml in terms of dependency versions.
      * <p/>
      * Does not parse dependencies which contain the top property set to false.
      */
     private static final int STRATEGY_APPLY_RULES = 1;
 
     /***
      * Parses the project.xml including its dependencies but does not follow
      * dependencies recursively. This is used to parse versions of artifacts
      * which have been overruled by some other version. They still need to be
      * parsed - though only non-recursively - to have them for later conflict
      * reporting.
      */
     private static final int STRATEGY_NON_RECURSIVELY = 2;
 
     /***
      * The list of repository configs pointing to the repositories to be used.
      */
     private List repositoryConfigs = new ArrayList();
 
     /***
      * Maps virtual relative repository paths of POMs to physical paths of POMs
      * that are not in a true repository but which are scattered around anywhere
      * in the file system. These take precedence over their correspondences in
      * any of the configured repositories. This allows to process POMs which
      * have not yet been released to a repository.
      */
     private Map virtualRepositoryPoms = new HashMap();
 
     /***
      * Scans directories for all versions of a given artifact.
      */
     private VersionScanner versionScanner = new VersionScanner();
 
     /***
      * Used to sort project versions.
      */
     private VersionComparator versionComparator = new VersionComparator();
 
     /***
      * The project generator used to generate a transient XML document from
      * a top project potentially updated by the user before applying the rules.
      */
     private ProjectGenerator projectGenerator = new ProjectGenerator("");
 
     /***
      * The document representing the top project file if the strategy is
      * STRATEGY_APPLY_RULES and the document must not be loaded but used in the
      * state currently available in main memory (with potentially added and/or
      * removed dependencies).
      */
     private Document currentTopDocument = null;
 
     /***
      * The file name of the {@link #currentTopDocument}.
      */
     private String currentTopProjectFile = null;
 
     /***
      * The optional log that may be supplied by the caller.
      */
     private Log userLog;
 
     /***
      * <code>true</code> if messages are to be written to the user's log, too.
      */
     private boolean userLogEnabled = true;
 
     /***
      * Maps 'group id + "/" + artifact id' to the version that is presently
      * chosen in the current top project.
      * <p/>
      * Supports the default rule 'PRESENT_RELEASE'. What is mapped here is the
      * default version for the artifact.
      */
     private Map presentVersions = null;
 
     /***
      * @param repositoryConfigs The list of configs of type
      *                          {@link RepositoryConfig} pointing to the
      *                          repositories of Maven project
      *                          object model files (POMs) to be used.
      * @param userLog The user's log to write messages to while recursing.
      */
     public ProjectRecursor(final List repositoryConfigs, final Log userLog) {
         this.repositoryConfigs = repositoryConfigs;
         this.userLog = userLog;
     }
 
     /***
      * @param projectFile The absolute path and file name of the Maven project
      *                    to open. Must not be <code>null</code>.
      * @param virtualRepositoryActive Whether to use the virtual repository
      *                                in the dependency recursion.
      * @return The top Maven project of the dependency graph of recursively
      *         parsed Maven projects.
      * @throws Exception if anything goes unexpectedly wrong
      */
     public Project openProjectAsIs(
             final String projectFile,
             final boolean virtualRepositoryActive) throws Exception {
         return parseProject(
                 projectFile,
                 null,
                 STRATEGY_AS_IS,
                 virtualRepositoryActive);
     }
 
     /***
      * @param projectFile The absolute path and file name of the Maven project
      *                    to parse recursively. Must not be <code>null</code>.
      * @param project The project to apply the rules to. Must not be
      *                <code>null</code>.
      * @param virtualRepositoryActive Whether to use the virtual repository
      *                                in the dependency recursion.
      * @return The top Maven project of the dependency tree of recursively
      *         parsed Maven projects after applying the rules.
      * @throws Exception if anything goes unexpectedly wrong
      */
     public Project applyRulesToProject(
             final String projectFile,
             final Project project,
             final boolean virtualRepositoryActive)
             throws Exception {
         return parseProject(
                 projectFile,
                 project,
                 STRATEGY_APPLY_RULES,
                 virtualRepositoryActive);
     }
 
     /***
      * @param projectFile The absolute path and file name of the Maven project
      *                    to parse recursively. Must not be <code>null</code>.
      * @param project The project to apply the rules to if the strategy is
      *                {@link #STRATEGY_APPLY_RULES}. Must not be
      *                <code>null</code> then. Must be null if the strategy is
      *                {@link #STRATEGY_AS_IS}.
      * @param strategy Either {@link #STRATEGY_AS_IS} or
      *                 {@link #STRATEGY_APPLY_RULES}.
      * @param virtualRepositoryActive Whether to use the virtual repository
      *                                in the dependency recursion.
      * @return The top Maven project of the dependency tree of recursively
      *         parsed Maven projects.
      * @throws Exception if anything goes unexpectedly wrong
      */
     private Project parseProject(
             final String projectFile,
             final Project project,
             final int strategy,
             final boolean virtualRepositoryActive)
             throws Exception {
         if (virtualRepositoryActive) {
             loadVirtualRepository();
         } else {
             unloadVirtualRepository();
         }
         RuleSet ruleSet = null;
         Boolean isAssembly = null;
         if (project != null) {
             ruleSet = project.getRuleSet();
             isAssembly = new Boolean(project.isAssembly());
             currentTopProjectFile = projectFile;
             currentTopDocument =
                 projectGenerator.createUpdatedDocument(project, projectFile);
             presentVersions = createPresentVersionsMap(project);
         } else {
             currentTopDocument = null;
             currentTopProjectFile = null;
             presentVersions = null;
         }
         if (ruleSet == null) {
             ruleSet = new RuleSet();
         }
         if (strategy != STRATEGY_APPLY_RULES) {
             //only one parsing pass, so log now
             userLogEnabled = true;
         } else {
             //only log later during the second parsing pass
             userLogEnabled = false;
         }
 
         Project topProject =
             parseProject(
                 projectFile,
                 new ProjectReference(
                     null,
                     null,
                     null,
                     null,
                     null,
                     null),
                 new HashMap(),
                 ruleSet,
                 strategy);
 
         if (strategy == ProjectRecursor.STRATEGY_APPLY_RULES) {
             //about to parse in the second pass, only log now
             userLogEnabled = true;
             /*
              * missing POMs or dynamic SNAPSHOT enforcements for some but not
              * all paths to an artifact may have lead to duplicate artifacts
              * with different versions in the dependency graph
              */
             RuleSet extendedRuleSet =
                 createExtendedRuleSet(topProject, ruleSet);
 
             /*
              * Do the whole thing again, this time with additional enforcements
              * that will avoid duplicates
              */
             topProject =
                 parseProject(
                     projectFile,
                     new ProjectReference(
                         null,
                         null,
                         null,
                         null,
                         null,
                         null),
                     new HashMap(),
                     extendedRuleSet,
                     strategy);
         }
 
         if (strategy == ProjectRecursor.STRATEGY_AS_IS) {
             Document projectDocument = loadDocument(projectFile);
             ruleSet = parseRuleSet(projectDocument);
             isAssembly = parseIsAssembly(projectDocument);
             if (isAssembly == null) {
                 //guess the right answer from the project name or the file name
                 if (topProject.getArtifactId().startsWith("vrp-assembly")
                         || projectFile.endsWith("test.xml")) {
                     isAssembly = Boolean.TRUE;
                 } else {
                     isAssembly = Boolean.FALSE;
                 }
             }
         } // else keep old rule set and old assembly decision
         topProject.setRuleSet(ruleSet);
         topProject.setAssembly(isAssembly.booleanValue());
         if (topProject.isAssembly()) {
             info("The project is considered to be an assembly. "
                  + "Indirect dependencies will be written to the file "
                  + "when you save it.");
         } else {
             info("The project is considered to be a component. "
                  + "Indirect dependencies will **NOT** be written to the file "
                  + "when you save it.");
         }
 
         return topProject;
     }
 
     /***
      * @param project The current top project to create the map for.
      * @return A map that maps each artifactId to the versions presently chosen
      *         for the artifact in the current top project.
      */
     private Map createPresentVersionsMap(final Project project) {
         Map result = new HashMap();
         Iterator iter = project.getAllDependencies().iterator();
         while (iter.hasNext()) {
             Project dependency = (Project) iter.next();
             result.put(
                 dependency.getGroupId() + "/" + dependency.getArtifactId(),
                 dependency.getVersion());
         }
         return result;
     }
 
     /***
      * @param projectFile The Maven project object model file to parse.
      * @param projectRef The properties of the project to parse.
      * @param parsedProjects The map of projects already (being) parsed.
      * @param ruleSet The set of rules that help to determine which version to
      *                choose of which artifact.
      * @param strategy One of the STRATEGY constants defined by this class.
      *
      * @return The top Maven project of the dependency tree of recursively
      *         parsed Maven projects.
      * @throws Exception if anything goes unexpectedly wrong
      */
     private Project parseProject(
             final String projectFile,
             final ProjectReference projectRef,
             final Map parsedProjects,
             final RuleSet ruleSet,
             final int strategy)
             throws Exception {
         /*
          * Create Maven project and set basic attributes
          */
         Document xmlDocument = loadDocument(projectFile);
         Project project =
             parseProjectWithBasicAttributes(
                 xmlDocument,
                 projectFile,
                 projectRef);
         if (parsedProjects.isEmpty()) {
             /*
              * No other projects parsed yet, so this must be the root project
              */
             project.setRootProject(true);
         }
         /*
          * Keep what's already being parsed in a map to avoid multiple
          * parsings of the same file
          */
         parsedProjects.put(
             getProjectHashKey(project.getArtifactId(), project.getVersion()),
             project);
 
         if (strategy == STRATEGY_NON_RECURSIVELY) {
             /*
              * Return early and don't recurse over any kind of dependency
              */
             return project;
         }
         /*
          * Parse dependencies and recurse
          */
         if (strategy == STRATEGY_AS_IS) {
             /*
              * For this strategy it must be avoided that indirect dependencies
              * will be computed if none are present in the file,
              * so initialize with empty list to suppress potential computation.
              */
             project.setIndirectDependencies(new ArrayList());
         }
         Iterator dependencyElementIter =
                     XPath.newInstance("descendant::dependency")
                          .selectNodes(xmlDocument).iterator();
         while (dependencyElementIter.hasNext()) {
             Element dependencyElement = (Element) dependencyElementIter.next();
             String dependencyGroupId =
                 parseElementText(dependencyElement, "groupId", "id");
             String dependencyArtifactId =
                 parseElementText(dependencyElement, "artifactId", "id");
             String dependencyVersion =
                 parseElementText(dependencyElement, "version");
             String dependencyJar =
                 parseElementText(dependencyElement, "jar");
             String dependencyType =
                 parseElementText(dependencyElement, "type");
             String dependencyUrl =
                 parseElementText(dependencyElement, "url");
             boolean isTopLevelDependency =
                 !hasPropertyTopWithValueFalse(dependencyElement);
             parseDependencyPropertiesToPreserve(project, dependencyElement);
 
             boolean isRemoved =
                 ruleSet.isRemoved(
                     dependencyArtifactId,
                     dependencyVersion);
             if (strategy == STRATEGY_APPLY_RULES
                     && (!isTopLevelDependency || isRemoved)) {
                 /*
                  * Ignore this dependency, it's a derived indirect dependency
                  * or there is a removal rule that kicks it out of the game!
                  */
                 continue;
             }
             ProjectQualifierImpl literalQualifier = new ProjectQualifierImpl();
             literalQualifier.setGroupId(dependencyGroupId);
             literalQualifier.setArtifactId(dependencyArtifactId);
             literalQualifier.setVersion(dependencyVersion);
 
             ProjectQualifierImpl recursiveQualifier =
                 getNextToParseRecursively(
                     dependencyGroupId,
                     dependencyArtifactId,
                     dependencyVersion,
                     strategy,
                     ruleSet,
                     project.isRootProject());
             /*
              * Parse the literal dependency recursively if it is still valid
              * or non-recursively if it is overruled by a different one
              */
             int dependencyStrategy = strategy;
             if (strategy == STRATEGY_APPLY_RULES
                     && !literalQualifier.equals(recursiveQualifier)) {
                 dependencyStrategy = STRATEGY_NON_RECURSIVELY;
             }
             Project dependencyProject =
                 parseDependency(
                     parsedProjects,
                     new ProjectReference(
                         dependencyGroupId,
                         dependencyArtifactId,
                         dependencyVersion,
                         dependencyJar,
                         dependencyType,
                         dependencyUrl),
                     dependencyStrategy,
                     ruleSet);
             /*
              * Finally, link the literal dependency with the parent project
              */
             if (strategy == STRATEGY_APPLY_RULES
                     && !literalQualifier.equals(recursiveQualifier)) {
                 project.addDeprecatedDependency(dependencyProject);
             } else if (strategy == STRATEGY_AS_IS && !isTopLevelDependency) {
                 project.addIndirectDependency(dependencyProject);
             } else {
                 project.addDependency(dependencyProject);
             }
             dependencyProject.getClients().add(project);
             /*
              * Do we need to parse another dependency additionally
              * because the literal dependency was overruled?
              */
             if (strategy == STRATEGY_APPLY_RULES
                     && !literalQualifier.equals(recursiveQualifier)) {
                 /*
                  * Yes!
                  */
                 Project enforcedProject =
                     parseDependency(
                         parsedProjects,
                         new ProjectReference(
                             recursiveQualifier.getGroupId(),
                             recursiveQualifier.getArtifactId(),
                             recursiveQualifier.getVersion(),
                             dependencyJar,
                             dependencyType,
                             dependencyUrl),
                         STRATEGY_APPLY_RULES,
                         ruleSet);
                 linkProjectWithEnforcedDependency(
                         project, enforcedProject, literalQualifier);
             }
         }
         return project;
     }
 
     /***
      * @param project The dependee.
      * @param dependency The project the dependee is computed to depend on.
      * @param literalQualifier The qualifer of the dependency stated literally
      *                         in the project's project.xml that caused the
      *                         overriding dependency.
      */
     private void linkProjectWithEnforcedDependency(
             final Project project,
             final Project dependency,
             final ProjectQualifier literalQualifier) {
         project.addDependency(dependency);
         dependency.getClients().add(project);
         project.getDependencyCauses().put(
                 dependency, literalQualifier);
         dependency.getClientCauses().put(
                 project, literalQualifier);
     }
 
     /***
      * Evaluates the rule set to determine which group id, artifact id and
      * version to follow next in the recursion.
      *
      * @param groupId The literal group id to follow if not overruled.
      * @param artifactId The literal artifact id to follow if not overruled.
      * @param version The literal version to follow if not overruled.
      * @param strategy The current recursion strategy. Must be one of
      *                 {@link #STRATEGY_APPLY_RULES},
      *                 {@link #STRATEGY_AS_IS},
      *                 {@link #STRATEGY_NON_RECURSIVELY}.
      * @param ruleSet The rule set of the root project to evaluate.
      * @param dependeeIsRootProject <code>true</code> if the project that
      *                              depends on the next dependency to parse is
      *                              the root in the dependency graph.
      * @return The (group id, artifact id, version) triple to follow.
      */
     private ProjectQualifierImpl getNextToParseRecursively(
             final String groupId,
             final String artifactId,
             final String version,
             final int strategy,
             final RuleSet ruleSet,
             final boolean dependeeIsRootProject) {
         ProjectQualifierImpl result = new ProjectQualifierImpl();
         result.setGroupId(groupId);
         result.setArtifactId(artifactId);
         result.setVersion(version);
         if (strategy == STRATEGY_APPLY_RULES) {
             ReplacementRule replacementRule =
                 ruleSet.getReplacementRule(artifactId, version);
             if (replacementRule != null) {
                 /*
                  * Apply replacement rule to change the
                  * groupId, artifactId, and the version.
                  */
                 if (replacementRule.getGroupId() != null) {
                     result.setGroupId(
                         replacementRule.getGroupId());
                 }
                 if (replacementRule.getArtifactId() != null) {
                     result.setArtifactId(
                         replacementRule.getArtifactId());
                 }
                 if (replacementRule.getVersion() != null) {
                     result.setVersion(replacementRule.getVersion());
                 }
             }
 
             /*
              * Apply rules to determine the version to select
              */
 
             /*
              * Rule #0: Is there a retention?
              */
             if (ruleSet.isRetained(artifactId, version)) {
                 /*
                  * Yes, so return the retained result
                  */
                 return result;
             }
 
             /*
              * Rule #1: Is there an enforcement?
              */
             String enforcedVersion =
                 ruleSet.getEnforcedVersion(result.getArtifactId());
             if (enforcedVersion != null) {
                 /*
                  * Yes, so return the enforcement
                  */
                 result.setVersion(enforcedVersion);
                 return result;
             }
 
             /*
              * Determine all versions to select one from
              */
             List selectableVersions =
                 getVersionsForArtifact(
                     result.getGroupId(),
                     result.getArtifactId(),
                     ruleSet.getDefaultRule());
             if (!selectableVersions.contains(result.getVersion())) {
                 /*
                  * The version suggested by the caller must still be added
                  */
                 selectableVersions.add(result.getVersion());
             }
             Collections.sort(selectableVersions, versionComparator);
 
             if (!dependeeIsRootProject) {
                 /*
                  * Remove all versions less than the one suggested by the
                  * caller, they are too low to be selected at any rate
                  */
                 int lastGoodIndex =
                     selectableVersions.indexOf(result.getVersion());
                 selectableVersions =
                     selectableVersions.subList(0, lastGoodIndex + 1);
             } // else, the root level must not dictate the minimum version!
 
             /*
              * Rule #2: Select the SNAPSHOT or the highest released version
              *          depending on the default rule,
              *          reject deprecated versions as long as there is an
              *          alternative.
              */
             String selectedVersion = (String) selectableVersions.get(0);
             int index = 1;
             while (selectableVersions.size() > index) {
                 /*
                  * There is at least one more alternative version to take
                  * if the current selection is not exactly what we want
                  */
                 if (selectedVersion.endsWith("SNAPSHOT")
                         && !ruleSet.getDefaultRule().equals(
                                 RuleSet.DEFAULT_RULE_SNAPSHOT)) {
                     /*
                      * We don't want SNAPSHOTS if possible
                      */
                     selectedVersion = (String) selectableVersions.get(index);
                 } else if (ruleSet.isDeprecated(
                                 result.getArtifactId(),
                                 selectedVersion)) {
                     /*
                      * We don't want deprecated versions if possible
                      */
                     selectedVersion = (String) selectableVersions.get(index);
                 } else {
                     /*
                      * The selected version is already the 'best' choice
                      */
                     break;
                 }
                 index++;
             }
             result.setVersion(selectedVersion);
         }
         return result;
     }
 
     /***
      * @param groupId The group id of the artifact to find all possible versions
      *                for.
      * @param artifactId The artifact id of the artifact to find all possible
      *                   versions for.
      * @param defaultRule The default rule of the POM being updated.
      * @return The list of versions of type {@link String}.
      *         Is never <code>null</code>.
      */
     private List getVersionsForArtifact(
             final String groupId,
             final String artifactId,
             final String defaultRule) {
         List versions = new ArrayList();
         if (!defaultRule.equals(RuleSet.DEFAULT_RULE_LATEST_RELEASE_NO_SCAN)
                 && !defaultRule.equals(
                         RuleSet.DEFAULT_RULE_PRESENT_RELEASE)) {
             versions = scanRepositoriesForAllVersions(groupId, artifactId);
         } else if (defaultRule.equals(RuleSet.DEFAULT_RULE_PRESENT_RELEASE)) {
             String presentVersion = null;
             if (presentVersions != null) {
                 presentVersion =
                     (String) presentVersions.get(groupId + "/" + artifactId);
             }
             if (presentVersion != null
                     && presentVersion.indexOf("SNAPSHOT") == -1) {
                 versions.add(presentVersion);
             } else {
                 versions = scanRepositoriesForAllVersions(groupId, artifactId);
             }
         }
         return versions;
     }
 
     /***
      * @param groupId The group id of the artifact to find all possible versions
      *                for.
      * @param artifactId The artifact id of the artifact to find all possible
      *                   versions for.
      * @return The list of versions of type {@link String}.
      *         Is never <code>null</code>.
      */
     private List scanRepositoriesForAllVersions(
             final String groupId,
             final String artifactId) {
         List versions = new ArrayList();
         /*
          * Construct relative path of poms directory
          */
         String relativePath =
             File.separator
             + groupId
             + File.separator
             + "poms"
             + File.separator;
         /*
          * Try repository paths one after another until one contains the group.
          * Exclude repositories which must not be scanned for versions.
          */
 
         for (Iterator iter = repositoryConfigs.iterator(); iter.hasNext();) {
             RepositoryConfig config = (RepositoryConfig) iter.next();
             if (config.isToBeScannedForVersions()) {
                 String repositoryPath = config.getPath();
                 String fullPath = repositoryPath + relativePath;
                 File dir = new File(fullPath);
                 if (dir.exists()) {
                     // found the correct path
                     versions =
                         versionScanner.getAllVersions(
                             dir.getAbsolutePath(),
                             artifactId);
                     break;
                 }
             }
         }
         return versions;
     }
 
     /***
      * Creates a rule set which contains all the rules of <code>ruleSet</code>
      * plus further enforcement rules that allow unique choices where there are
      * still artifact duplicates in the direct and indirect dependencies of the
      * <code>topProject</code> after the first recursion pass.<br/>
      * These additional rules will enforce the highest version in each of those
      * artifact duplication lists when being applied in the second recursion
      * pass.
      *
      * @param topProject The top project to parse.
      * @param ruleSet The original rule set associated with the top project.
      * @return The extended rule set.
      */
     private RuleSet createExtendedRuleSet(
             final Project topProject,
             final RuleSet ruleSet) {
         RuleSet result = new RuleSet();
         result.setDefaultRule(ruleSet.getDefaultRule());
         /*
          * - Get all direct and indirect dependencies
          *   (ordered by artifact id and version),
          *
          * - group dependencies by artifact id
          *
          * - create an enforcement rule for each group having more than one
          *   element. The first element in each such group is the highest
          *   version which must be enforced in the upcoming second recursion
          *   pass.
          *
          * Note, that for each such artifact group with more than one element
          * the following is true:
          *
          * - All replacement rules that may apply have been applied in the first
          *   recursion pass already and thus need not be considered here
          *   explicitly in the choice of the version to enforce.
          *
          * - There is no enforcement rule that applies for such an artifact
          *   group because otherwise the group would not have more than one
          *   element.
          *
          * - All deprecation rules that may apply have been applied in the first
          *   recursion pass already and thus need not be considered here
          *   explicitly in the choice of the version to enforce.
          */
         List allDependencies = topProject.getAllDependencies();
         String currentArtifactId = null;
         List currentGroup = new ArrayList();
         for (Iterator iter = allDependencies.iterator(); iter.hasNext();) {
             Project project = (Project) iter.next();
             if (currentArtifactId == null
                     || currentArtifactId.equals(project.getArtifactId())) {
                 /*
                  * Add to the existing group (which is empty or non-empty)
                  */
                 currentArtifactId = project.getArtifactId();
                 currentGroup.add(project);
             } else {
                 /*
                  * Perform a change of groups. Create an enforcement rule for
                  * the old group if it has more than one element.
                  */
                 if (currentGroup.size() > 1) {
                     Project firstOfGroup = (Project) currentGroup.get(0);
                     EnforcementRule rule = createEnforcementRule(firstOfGroup);
                     result.add(rule);
                 }
                 currentArtifactId = project.getArtifactId();
                 currentGroup = new ArrayList();
                 currentGroup.add(project);
             }
         }
         /*
          * Handle the last group
          */
         if (currentGroup.size() > 1) {
             Project firstOfGroup = (Project) currentGroup.get(0);
             EnforcementRule rule = createEnforcementRule(firstOfGroup);
             result.add(rule);
         }
         /*
          * Merge the new rule set with the existing one to get the extended one.
          */
         result.add(ruleSet);
         return result;
     }
 
     /***
      * Creates an enforcement rule for the project. Is used for the extended
      * rule set that eliminates duplicates in the second pass of the recursion.
      *
      * @param project The project to create the rule for.
      * @return The rule created.
      */
     private EnforcementRule createEnforcementRule(final Project project) {
         EnforcementRule rule = new EnforcementRule();
         rule.setGroupId(project.getGroupId());
         rule.setArtifactId(project.getArtifactId());
         rule.setVersion(project.getVersion());
         return rule;
     }
 
     /***
      * Parses the 'isAssembly' attribute of the deputy element in the project's
      * properties.
      *
      * @param xmlDocument The project object model document to parse.
      * @return <code>true</code> if the project is flagged to be an assembly.
      * @throws Exception if anything goes unexpectedly wrong
      */
     private Boolean parseIsAssembly(
             final Document xmlDocument) throws Exception {
         Boolean result = null;
         String path = "project/properties/deputy";
 
         /*
          * Parse the deputy element
          */
         Element deputyElement =
             (Element) XPath.newInstance(path).selectSingleNode(xmlDocument);
         if (deputyElement != null) {
             Attribute attribute = deputyElement.getAttribute("isAssembly");
             if (attribute != null) {
                 String value = attribute.getValue();
                 if ("true".equalsIgnoreCase(value)) {
                     result = Boolean.TRUE;
                 } else if ("false".equalsIgnoreCase(value)) {
                     result = Boolean.FALSE;
                 }
             }
         }
         return result;
     }
 
     /***
      * Parses the rule set properties of the <code>projectFile</code>.
      *
      * @param xmlDocument The project object model document to parse.
      * @return The rule set defined in the <code>projectFile</code> or a default
      *         rule set.
      * @throws Exception if anything goes unexpectedly wrong
      */
     private RuleSet parseRuleSet(
             final Document xmlDocument) throws Exception {
         RuleSet result = new RuleSet();
         String rootPath = "project/properties/deputy/rules/";
 
         String path = rootPath + "default";
         /*
          * Parse the default rule
          */
         Element defaultRuleElement =
             (Element) XPath.newInstance(path).selectSingleNode(xmlDocument);
         if (defaultRuleElement != null) {
             String value = defaultRuleElement.getAttribute("value").getValue();
             if (RuleSet.DEFAULT_RULE_SNAPSHOT.equals(value)) {
                 result.setDefaultRule(RuleSet.DEFAULT_RULE_SNAPSHOT);
             } else if (RuleSet.DEFAULT_RULE_LATEST_RELEASE_NO_SCAN.equals(
                             value)) {
                 result.setDefaultRule(
                         RuleSet.DEFAULT_RULE_LATEST_RELEASE_NO_SCAN);
             } else if (RuleSet.DEFAULT_RULE_PRESENT_RELEASE.equals(value)) {
                 result.setDefaultRule(RuleSet.DEFAULT_RULE_PRESENT_RELEASE);
             }
         }
 
         /*
          * Parse the enforcement rules
          */
         path = rootPath + "enforcements/enforcement";
         Iterator elementIter =
             XPath.newInstance(path).selectNodes(xmlDocument).iterator();
         while (elementIter.hasNext()) {
             Element element = (Element) elementIter.next();
             String groupId = parseElementText(element, "groupId");
             String artifactId = parseElementText(element, "artifactId");
             String version = parseElementText(element, "version");
             String derivedAsString = parseElementText(element, "derived");
 
             EnforcementRule rule = new EnforcementRule();
             rule.setGroupId(groupId);
             rule.setArtifactId(artifactId);
             rule.setVersion(version);
             if (derivedAsString != null) {
                 boolean derived = derivedAsString.equalsIgnoreCase("true");
                 rule.setDerived(derived);
             }
             result.add(rule);
         }
 
         /*
          * Parse the deprecation rules
          */
         path = rootPath + "deprecations/deprecation";
         elementIter =
             XPath.newInstance(path).selectNodes(xmlDocument).iterator();
         while (elementIter.hasNext()) {
             Element element = (Element) elementIter.next();
             String groupId = parseElementText(element, "groupId");
             String artifactId = parseElementText(element, "artifactId");
             String version = parseElementText(element, "version");
 
             DeprecationRule rule = new DeprecationRule();
             rule.setGroupId(groupId);
             rule.setArtifactId(artifactId);
             rule.setVersion(version);
             result.add(rule);
         }
 
         /*
          * Parse the replacement rules
          */
         path = rootPath + "replacements/replacement";
         elementIter =
             XPath.newInstance(path).selectNodes(xmlDocument).iterator();
         while (elementIter.hasNext()) {
             Element element = (Element) elementIter.next();
             Element displacementElement =
                 (Element) XPath.newInstance("displacement").selectSingleNode(
                     element);
             String displacedGroupId =
                 parseElementText(displacementElement, "groupId");
             String displacedArtifactId =
                 parseElementText(displacementElement, "artifactId");
             String displacedVersion =
                 parseElementText(displacementElement, "version");
 
             Element placementElement =
                 (Element) XPath.newInstance("placement").selectSingleNode(
                     element);
             String placedGroupId =
                 parseElementText(placementElement, "groupId");
             String placedArtifactId =
                 parseElementText(placementElement, "artifactId");
             String placedVersion =
                 parseElementText(placementElement, "version");
 
             ReplacementRule rule = new ReplacementRule();
             rule.setGroupId(placedGroupId);
             rule.setArtifactId(placedArtifactId);
             rule.setVersion(placedVersion);
 
             rule.setDisplacedGroupId(displacedGroupId);
             rule.setDisplacedArtifactId(displacedArtifactId);
             rule.setDisplacedVersion(displacedVersion);
 
             result.add(rule);
         }
 
         /*
          * Parse the removal rules
          */
         path = rootPath + "removals/removal";
         elementIter =
             XPath.newInstance(path).selectNodes(xmlDocument).iterator();
         while (elementIter.hasNext()) {
             Element element = (Element) elementIter.next();
             String groupId = parseElementText(element, "groupId");
             String artifactId = parseElementText(element, "artifactId");
             String version = parseElementText(element, "version");
 
             RemovalRule rule = new RemovalRule();
             rule.setGroupId(groupId);
             rule.setArtifactId(artifactId);
             rule.setVersion(version);
             result.add(rule);
         }
 
         /*
          * Parse the retention rules
          */
         path = rootPath + "retentions/retention";
         elementIter =
             XPath.newInstance(path).selectNodes(xmlDocument).iterator();
         while (elementIter.hasNext()) {
             Element element = (Element) elementIter.next();
             String groupId = parseElementText(element, "groupId");
             String artifactId = parseElementText(element, "artifactId");
             String version = parseElementText(element, "version");
 
             RetentionRule rule = new RetentionRule();
             rule.setGroupId(groupId);
             rule.setArtifactId(artifactId);
             rule.setVersion(version);
             result.add(rule);
         }
 
         return result;
     }
 
     /***
      * @param project The project defining the dependency. The parsed properties
      *                will be stored in the project for later reconstruction.
      * @param dependencyElement The dependency element to parse the child
      *                          properties from
      * @throws Exception if anything goes unexpectedly wrong
      */
     private void parseDependencyPropertiesToPreserve(
             final Project project,
             final Element dependencyElement)
             throws Exception {
         Iterator propertyElementIter =
                     XPath.newInstance("properties/child::*")
                          .selectNodes(dependencyElement).iterator();
         List result = new ArrayList();
         while (propertyElementIter.hasNext()) {
             Element propertyElement = (Element) propertyElementIter.next();
             if (!propertyElement.getName().equals("top")) {
                 result.add(propertyElement);
             }
         }
         if (result.size() > 0) {
             String artifactId =
                 parseElementText(dependencyElement, "artifactId", "id");
             project.addDependencyPropertyList(artifactId, result);
         }
     }
 
     /***
      * Parses all the needed basic elements describing a project.
      *
      * @param xmlDocument The document to parse.
      * @param projectFile The file path and name of the document to parse.
      * @param projectRef The properties of the project to parse.
      * @return The project created from the parsed information.
      * @throws Exception if anything goes unexpectedly wrong
      */
     private Project parseProjectWithBasicAttributes(
             final Document xmlDocument,
             final String projectFile,
             final ProjectReference projectRef)
             throws Exception {
         Project project = new Project();
 
         project.setGroupId(
             parseElementText(xmlDocument, "project/groupId", "project/id"));
         if (projectRef.getGroupId() != null
                 && !projectRef.getGroupId().equals(project.getGroupId())) {
             //group id is inconsistent with directory or
             //missing in the project file
             project.setGroupId(projectRef.getGroupId());
         }
 
         project.setArtifactId(
             parseElementText(xmlDocument, "project/artifactId", "project/id"));
 
         if (project.getGroupId() == null
                 && project.getArtifactId() != null
                 && (project.getArtifactId().startsWith("vrp-")
                         || project.getArtifactId().startsWith("test-vrp-"))) {
             project.setGroupId("vrp");
             info(
                 "Automatically set missing group id of "
                     + project.getArtifactId()
                     + " to '"
                     + project.getGroupId()
                     + "'");
         }
 
         project.setName(
             parseElementText(xmlDocument, "project/name", "project/name"));
 
         project.setVersion(
             parseElementText(xmlDocument, "project/currentVersion"));
         if (projectRef.getVersion() != null
                 && !projectRef.getVersion().equals(project.getVersion())) {
             //version part of file name is inconsistent
             //with value of field 'currentVersion',
             //this may occur for SNAPSHOT files
             project.setVersion(projectRef.getVersion());
         }
 
         project.setJar(
             parseElementText(xmlDocument, "project/jar"));
         if (project.getJar() == null) {
             //jar is not defined in the project file,
             //use the jar possibly learnt from a dependency
             project.setJar(projectRef.getJar());
         }
 
         project.setType(
             parseElementText(xmlDocument, "project/type"));
         if (project.getType() == null) {
             //type is not defined in the project file,
             //use the type possibly learnt from a dependency
             project.setType(projectRef.getType());
         }
 
         project.setUrl(parseElementText(xmlDocument, "project/url"));
         if (project.getUrl() == null) {
             //url is not defined in the project file,
             //use the url possibly learnt from a dependency
             project.setUrl(projectRef.getUrl());
         }
 
         /*
          * Do a sanity check and report missing attributes
          */
         if (project.getGroupId() == null) {
              error("No group id defined in file " + projectFile);
         }
         if (project.getArtifactId() == null) {
              error("No artifact id defined in file " + projectFile);
         }
         if (project.getVersion() == null) {
             error("No current version defined in file " + projectFile);
         }
 
         return project;
     }
 
     /***
      * Parses a dependency and creates a project representing it.
      *
      * @param parsedProjects The map of projects parsed already. Keys are
      *                       created by
      *                       {@link #getProjectHashKey(String, String)}.
      * @param dependencyRef The properties of the dependency to parse.
      * @param dependencyStrategy Must be one of
      *                           {@link #STRATEGY_APPLY_RULES},
      *                           {@link #STRATEGY_AS_IS},
      *                           {@link #STRATEGY_NON_RECURSIVELY}.
      * @param ruleSet The rule set of the root project.
      * @return The dependency project parsed.
      * @throws Exception if anything goes unexpectedly wrong
      */
     private Project parseDependency(
             final Map parsedProjects,
             final ProjectReference dependencyRef,
             final int dependencyStrategy,
             final RuleSet ruleSet) throws Exception {
         /*
          * Check if the dependency project is already (being) parsed
          */
         Project dependencyProject =
             (Project) parsedProjects.get(
                     getProjectHashKey(
                         dependencyRef.getArtifactId(),
                         dependencyRef.getVersion()));
         if (dependencyProject == null) {
             /*
              * Not yet parsed, so start it now
              */
             String dependencyProjectFile =
                 getAbsolutePathAndFileNameForPom(
                     dependencyRef.getGroupId(),
                     dependencyRef.getArtifactId(),
                     dependencyRef.getVersion());
             if (dependencyProjectFile != null) {
                 dependencyProject =
                     parseProject(
                         dependencyProjectFile,
                         dependencyRef,
                         parsedProjects,
                         ruleSet,
                         dependencyStrategy);
             } else {
                 /*
                  *  There is no POM for the dependency.
                  *  Inform and assume its a leaf in the tree.
                  */
                 info(
                     "Did not find POM file for "
                     + "groupId = '" + dependencyRef.getGroupId() + "' "
                     + "artifactId = '" + dependencyRef.getArtifactId() + "' "
                     + "version = '" + dependencyRef.getVersion() + "'. "
                     + "Assuming the artifact has no dependencies.");
                 dependencyProject = new Project();
                 dependencyProject.setGroupId(dependencyRef.getGroupId());
                 dependencyProject.setArtifactId(dependencyRef.getArtifactId());
                 dependencyProject.setVersion(dependencyRef.getVersion());
                 dependencyProject.setUrl(dependencyRef.getUrl());
                 dependencyProject.setJar(dependencyRef.getJar());
                 parsedProjects.put(
                     getProjectHashKey(
                         dependencyRef.getArtifactId(),
                         dependencyRef.getVersion()),
                     dependencyProject);
             }
         }
         if (dependencyProject.getUrl() == null
                 && dependencyRef.getUrl() != null) {
             /*
              * The dependency project may have been found in the parsedProjects
              * map because it was parsed earlier already. The URL, however,
              * may still be null, so set it now (again) to the (newly) learnt
              * value learnt from the current dependency reference.
              */
             dependencyProject.setUrl(dependencyRef.getUrl());
         }
         return dependencyProject;
     }
 
     /***
      * @param dependencyElement The dependency element to check the property
      *                          for.
      * @return <code>true</code> if the dependency owns a property 'top'
      *         indicating that it is a direct (or: top level) dependency of the
      *         defining project.
      * @throws Exception if anything goes unexpectedly wrong
      */
     private boolean hasPropertyTopWithValueFalse(
             final Element dependencyElement) throws Exception {
         boolean result = false;
         Element topElement =
             (Element) XPath.newInstance("properties/top")
                  .selectSingleNode(dependencyElement);
         if (topElement != null
                 && "false".equalsIgnoreCase(topElement.getText())) {
             result = true;
         }
         return result;
     }
 
     /***
      * Tries to parse the element named <code>elementName.</code>. If such an
      * element does not exist, it tries to parse an element with name
      * <code>fallbackElementName</code>.
      *
      * @param xmlNode The XML node to that contains the element to parse.
      * @param elementName The name of the element to try first.
      * @param fallbackElementName The name of the element to try as a fallback.
      * @return The contents of the parsed element or of the fallback element or
      *         <code>null</code>.
      * @throws Exception if anything goes unexpectedly wrong
      */
     private String parseElementText(
             final Object xmlNode,
             final String elementName,
             final String fallbackElementName)
             throws Exception {
         String result = parseElementText(xmlNode, elementName);
         if (result == null) {
             result = parseElementText(xmlNode, fallbackElementName);
         }
         return result;
     }
 
     /***
      * Tries to parse the element named <code>elementName.</code>.
      *
      * @param xmlNode The XML node to that contains the element to parse.
      * @param elementName The name of the element to parse.
      * @return The contents of the element to parse or <code>null</code>.
      * @throws Exception if anything goes unexpectedly wrong
      */
     private String parseElementText(
             final Object xmlNode,
             final String elementName)
             throws Exception {
         Element element =
             (Element) XPath.newInstance(elementName).selectSingleNode(xmlNode);
         String result = null;
         if (element != null) {
             result = element.getText();
         }
         return result;
     }
 
     /***
      * @param artifactId The artifact id of the project to create a hash key
      *                   for.
      * @param version The version of the project to create a hash key for.
      * @return The key of the project to be uses for hashing.
      */
     private String getProjectHashKey(
             final String artifactId,
             final String version) {
         return artifactId + "-" + version;
     }
 
     /***
      * Constructs a valid absolute path and file name of the POM specified by
      * the parameters passed in and the known repository paths.
      *
      * @param groupId The group id of the POM.
      * @param artifactId The artifact id of the POM.
      * @param version The version of the POM.
      * @return The absolute path and name of the POM file or null if it does not
      *         exist under any of the known repository paths.
      */
     private String getAbsolutePathAndFileNameForPom(
             final String groupId,
             final String artifactId,
             final String version) {
         /*
          * Try to find the POM in the virtual repository
          */
         String key =
             createVirtualRepositoryPomKey(groupId, artifactId, version);
         String result = (String) virtualRepositoryPoms.get(key);
         if (result == null) {
             /*
              * It is not in the virtual repository,
              * so try the real ones
              */
             String relativePath =
                 getRelativePathAndFileNameForPom(groupId, artifactId, version);
             /*
              * Try repository paths one after another until one yields the file
              */
             for (Iterator iter = repositoryConfigs.iterator();
                     iter.hasNext();) {
                 RepositoryConfig config = (RepositoryConfig) iter.next();
                 String repositoryPath = config.getPath();
                 String candidate = repositoryPath + relativePath;
                 if ((new File(candidate)).exists()) {
                     // found the correct path
                     result = candidate;
                     break;
                 }
             }
         }
         return result;
     }
 
     /***
      * Constructs a relative path and file name of the POM specified by
      * the parameters passed.
      *
      * @param groupId The group id of the POM.
      * @param artifactId The artifact id of the POM.
      * @param version The version of the POM.
      * @return The relative path and name of the POM file.
      */
     private String getRelativePathAndFileNameForPom(
             final String groupId,
             final String artifactId,
             final String version) {
         String relativePath =
             File.separator
             + groupId
             + File.separator
             + "poms"
             + File.separator
             + artifactId
             + "-"
             + version
             + ".pom";
         return relativePath;
     }
 
     /***
      * @param projectFile The file name and path of the XML document to load.
      * @return The document loaded.
      * @throws Exception if anything goes unexpectedly wrong
      */
     private Document loadDocument(final String projectFile) throws Exception {
         Document result = null;
         if (currentTopDocument != null
                 && projectFile.equals(currentTopProjectFile)) {
             result = currentTopDocument;
         } else {
             SAXBuilder builder = new SAXBuilder();
             result = builder.build(projectFile);
         }
         return result;
     }
 
     /***
      * Loads the list of POMs which are not in a true repository but which are
      * scattered around in the file system and puts them into the map
      * {@link #virtualRepositoryPoms}.
      */
     private void loadVirtualRepository() {
         try {
             final String path =
                 System.getProperty("user.home")
                 + File.separator
                 + "deputy-virtual-repository.xml";
             if ((new File(path)).exists()) {
                 Document virtualRepositoryDocument = loadDocument(path);
                 virtualRepositoryPoms =
                     createVirtualRepositoryPomsMap(virtualRepositoryDocument);
             } else {
                 warn("Did not find the optional file " + path);
                 warn("So POMs of dependencies will only be read "
                         + "from the configured repositories.");
             }
         } catch (Exception e) {
             error("Failed to read the virtual repository: " + e.getMessage());
         }
     }
 
     /***
      * Unloads, i. e. clears the the map {@link #virtualRepositoryPoms},
      * so that the virtual repository will not be used in effect.
      */
     private void unloadVirtualRepository() {
         virtualRepositoryPoms = new HashMap();
     }
 
     /***
      * @param document The document loaded from /deputy-virtual-repository.xml
      * @return The map mapping a POM key to the absolute path of the POM.
      * @throws Exception if anything goes unexpectedly wrong
      */
     private Map createVirtualRepositoryPomsMap(
             final Document document)
             throws Exception {
         Map result = new HashMap();
         Iterator pomElementIter =
             XPath.newInstance("poms/pom")
                  .selectNodes(document).iterator();
         while (pomElementIter.hasNext()) {
             Element pomElement = (Element) pomElementIter.next();
             String path = pomElement.getAttributeValue("path");
             String key = createVirtualRepositoryPomKey(path);
             result.put(key, path);
             info("The virtual repository contains the file " + path);
             info("It overrides the repository file " + key + ".");
         }
         return result;
     }
 
     /***
      * @param path The absolute path of a POM file anywhere in the file system.
      * @return They key to use for the hash map {@link #virtualRepositoryPoms}.
      * @throws Exception if anything goes unexpectedly wrong
      */
     private String createVirtualRepositoryPomKey(
             final String path) throws Exception {
         Document xmlDocument = loadDocument(path);
         String groupId =
             parseElementText(xmlDocument, "project/groupId", "project/id");
         String artifactId =
             parseElementText(xmlDocument, "project/artifactId", "project/id");
 
         if (groupId == null
                 && artifactId != null
                 && (artifactId.startsWith("vrp-")
                         || artifactId.startsWith("test-vrp-"))) {
             groupId = "vrp";
             info(
                 "Automatically set missing group id of "
                     + path
                     + " to '"
                     + groupId
                     + "'");
         }
         String version =
             parseElementText(xmlDocument, "project/currentVersion");
         String result =
             createVirtualRepositoryPomKey(groupId, artifactId, version);
         return result;
     }
 
     /***
      * @param groupId The group id of the pom.
      * @param artifactId The artifact id of the pom.
      * @param version The version of the pom.
      * @return They key to use for the hash map {@link #virtualRepositoryPoms}.
      */
     private String createVirtualRepositoryPomKey(
             final String groupId,
             final String artifactId,
             final String version) {
         String result =
             getRelativePathAndFileNameForPom(groupId, artifactId, version);
         return result;
     }
 
     /***
      * @param message The info message to log.
      */
     private void info(final String message) {
         log(Log.SEVERITY_INFO, message);
     }
 
     /***
      * @param message The warning message to log.
      */
     private void warn(final String message) {
         log(Log.SEVERITY_WARNING, message);
     }
 
     /***
      * @param message The error message to log.
      */
     private void error(final String message) {
         log(Log.SEVERITY_ERROR, message);
     }
 
     /***
      * @param severity The severity of the message. Must be one of
      *                 {@link Log#SEVERITY_INFO},
      *                 {@link Log#SEVERITY_WARNING},
      *                 {@link Log#SEVERITY_ERROR}.
      * @param message The message to log.
      */
     private void log(final String severity, final String message) {
         if (severity == Log.SEVERITY_ERROR) {
             System.err.println(message);
         } else {
             System.out.println(message);
         }
         if (userLog != null && userLogEnabled) {
             userLog.log(severity, message);
         }
     }
 }