platform/projectModel-api/src/com/intellij/openapi/module/ModuleManager.java

   1 /*
   2  * Copyright 2000-2017 JetBrains s.r.o.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16 package com.intellij.openapi.module;
  17
  18 import com.intellij.openapi.project.Project;
  19 import com.intellij.openapi.util.InvalidDataException;
  20 import com.intellij.openapi.util.SimpleModificationTracker;
  21 import com.intellij.util.graph.Graph;
  22 import org.jdom.JDOMException;
  23 import org.jetbrains.annotations.ApiStatus;
  24 import org.jetbrains.annotations.NonNls;
  25 import org.jetbrains.annotations.NotNull;
  26 import org.jetbrains.annotations.Nullable;
  27
  28 import java.io.IOException;
  29 import java.util.Collection;
  30 import java.util.Comparator;
  31 import java.util.List;
  32
  33 /**
  34  * Provides services for working with the modules of a project.
  35  */
  36 public abstract class ModuleManager extends SimpleModificationTracker {
  37   /**
  38    * Returns the module manager instance for the current project.
  39    *
  40    * @param project the project for which the module manager is requested.
  41    * @return the module manager instance.
  42    */
  43   public static ModuleManager getInstance(@NotNull Project project) {
  44     return project.getComponent(ModuleManager.class);
  45   }
  46
  47   /**
  48    * Creates a module of the specified type at the specified path and adds it to the project
  49    * to which the module manager is related.
  50    *
  51    * @param filePath     the path at which the module is created.
  52    * @param moduleTypeId the ID of the module type to create.
  53    * @return the module instance.
  54    */
  55   @NotNull
  56   public abstract Module newModule(@NotNull @NonNls String filePath, final String moduleTypeId);
  57
  58   /**
  59    * Loads a module from an .iml file with the specified path and adds it to the project.
  60    *
  61    * @param filePath the path to load the module from.
  62    * @return the module instance.
  63    * @throws InvalidDataException        if the data in the .iml file is semantically incorrect.
  64    * @throws IOException                 if an I/O error occurred when loading the module file.
  65    * @throws JDOMException               if the file contains invalid XML data.
  66    * @throws ModuleWithNameAlreadyExists if a module with such a name already exists in the project.
  67    */
  68   @NotNull
  69   public abstract Module loadModule(@NotNull String filePath) throws IOException, JDOMException, ModuleWithNameAlreadyExists;
  70
  71   /**
  72    * Disposes of the specified module and removes it from the project.
  73    *
  74    * @param module the module to remove.
  75    */
  76   public abstract void disposeModule(@NotNull Module module);
  77
  78   /**
  79    * Returns the list of all modules in the project.
  80    *
  81    * @return the array of modules.
  82    */
  83   @NotNull
  84   public abstract Module[] getModules();
  85
  86   /**
  87    * Returns the project module with the specified name.
  88    *
  89    * @param name the name of the module to find.
  90    * @return the module instance, or null if no module with such name exists.
  91    */
  92   @Nullable
  93   public abstract Module findModuleByName(@NonNls @NotNull String name);
  94
  95   /**
  96    * Returns the list of modules sorted by dependency (the modules which do not depend
  97    * on anything are in the beginning of the list, a module which depends on another module
  98    * follows it in the list).
  99    *
 100    * @return the sorted array of modules.
 101    */
 102   @NotNull
 103   public abstract Module[] getSortedModules();
 104
 105   /**
 106    * Returns the module comparator which can be used for sorting modules by dependency
 107    * (the modules which do not depend on anything are in the beginning of the list,
 108    * a module which depends on another module follows it in the list).
 109    *
 110    * @return the module comparator instance.
 111    */
 112   @NotNull
 113   public abstract Comparator<Module> moduleDependencyComparator();
 114
 115   /**
 116    * Returns the list of modules which directly depend on the specified module.
 117    *
 118    * @param module the module for which the list of dependent modules is requested.
 119    * @return list of <i>modules that depend on</i> given module.
 120    * @see ModuleUtilCore#getAllDependentModules(Module)
 121    */
 122   @NotNull
 123   public abstract List<Module> getModuleDependentModules(@NotNull Module module);
 124
 125   /**
 126    * Checks if one of the specified modules directly depends on the other module.
 127    *
 128    * @param module   the module to check the dependency for.
 129    * @param onModule the module on which <code>module</code> may depend.
 130    * @return true if <code>module</code> directly depends on <code>onModule</code>, false otherwise.
 131    */
 132   public abstract boolean isModuleDependent(@NotNull Module module, @NotNull Module onModule);
 133
 134   /**
 135    * Returns the graph of dependencies between modules in the project.
 136    *
 137    * @return the module dependency graph.
 138    */
 139   @NotNull
 140   public abstract Graph<Module> moduleGraph();
 141
 142   /**
 143    * Returns the graph of dependencies between modules in the project.
 144    *
 145    * @param includeTests whether test-only dependencies should be included
 146    * @return the module dependency graph.
 147    * @since 11.0
 148    */
 149   @NotNull
 150   public abstract Graph<Module> moduleGraph(boolean includeTests);
 151
 152   /**
 153    * Returns the model for the list of modules in the project, which can be used to add,
 154    * remove or modify modules.
 155    *
 156    * @return the modifiable model instance.
 157    */
 158   @NotNull
 159   public abstract ModifiableModuleModel getModifiableModel();
 160
 161
 162   /**
 163    * Returns the path to the group to which the specified module belongs, as an array of group names starting from the project root.
 164    * <p>
 165    * <strong>Use {@link com.intellij.openapi.module.ModuleGrouper#getGroupPath()} instead.</strong> Exlicit module groups will be replaced
 166    * by automatical module grouping accordingly to qualified names of modules, see https://youtrack.jetbrains.com/issue/IDEA-166061 for details.
 167    * </p>
 168    * @param module the module for which the path is requested.
 169    * @return the path to the group for the module, or null if the module does not belong to any group.
 170    */
 171   @Nullable
 172   public abstract String[] getModuleGroupPath(@NotNull Module module);
 173
 174   public abstract boolean hasModuleGroups();
 175
 176   /**
 177    * @return description of all modules in the project including unloaded
 178    */
 179   @ApiStatus.Experimental
 180   public abstract Collection<ModuleDescription> getAllModuleDescriptions();
 181
 182   @ApiStatus.Experimental
 183   public abstract Collection<UnloadedModuleDescription> getUnloadedModuleDescriptions();
 184
 185   @ApiStatus.Experimental
 186   @Nullable
 187   public abstract UnloadedModuleDescription getUnloadedModuleDescription(@NotNull String moduleName);
 188
 189   /**
 190    * Specify list of modules which will be unloaded from the project.
 191    * @see UnloadedModuleDescription
 192    */
 193   @ApiStatus.Experimental
 194   public abstract void setUnloadedModules(@NotNull List<String> unloadedModuleNames);
 195 }