xml/dom-openapi/src/com/intellij/util/xml/DomManager.java

   1 /*
   2  * Copyright 2000-2009 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.util.xml;
  17
  18 import com.intellij.openapi.Disposable;
  19 import com.intellij.openapi.components.ServiceManager;
  20 import com.intellij.openapi.module.Module;
  21 import com.intellij.openapi.project.Project;
  22 import com.intellij.openapi.util.Factory;
  23 import com.intellij.openapi.util.Key;
  24 import com.intellij.openapi.util.ModificationTracker;
  25 import com.intellij.psi.PsiReferenceFactory;
  26 import com.intellij.psi.xml.XmlAttribute;
  27 import com.intellij.psi.xml.XmlFile;
  28 import com.intellij.psi.xml.XmlTag;
  29 import com.intellij.util.xml.reflect.AbstractDomChildrenDescription;
  30 import com.intellij.util.xml.reflect.DomGenericInfo;
  31 import org.jetbrains.annotations.NonNls;
  32 import org.jetbrains.annotations.NotNull;
  33 import org.jetbrains.annotations.Nullable;
  34
  35 import java.lang.reflect.Type;
  36
  37 /**
  38  * @author peter
  39  */
  40 public abstract class DomManager implements ModificationTracker {
  41   public static final Key<Module> MOCK_ELEMENT_MODULE = Key.create("MockElementModule");
  42
  43   public static DomManager getDomManager(Project project) {
  44     return ServiceManager.getService(project, DomManager.class);
  45   }
  46
  47   public abstract Project getProject();
  48
  49   /**
  50    * @param file XML file
  51    * @param domClass desired DOM element class
  52    * @return New or cached DOM file element for the given file. All registered {@link com.intellij.util.xml.DomFileDescription}s are
  53    * asked if they are responsible for the file {@link com.intellij.util.xml.DomFileDescription#isMyFile(com.intellij.psi.xml.XmlFile, com.intellij.openapi.module.Module)}.
  54    * If there is a {@link com.intellij.util.xml.DomFileDescription} that is responsible for the file, but its {@link DomFileDescription#getRootElementClass()}
  55    * result is incompatible with domClass parameter, null is returned
  56    */
  57   @Nullable
  58   public abstract <T extends DomElement> DomFileElement<T> getFileElement(XmlFile file, Class<T> domClass);
  59
  60   @Nullable
  61   @Deprecated
  62   /**
  63    * @deprecated use {@link #getFileElement(XmlFile, Class)}
  64    */
  65   public abstract <T extends DomElement> DomFileElement<T> getFileElement(XmlFile file);
  66
  67   @NotNull
  68   @Deprecated
  69   /**
  70    * @deprecated use {@link #getFileElement(XmlFile, Class)}
  71    */
  72   public abstract <T extends DomElement> DomFileElement<T> getFileElement(XmlFile file, Class<T> aClass, @NonNls String rootTagName);
  73
  74   public abstract void addDomEventListener(DomEventListener listener, Disposable parentDisposable);
  75
  76   /**
  77    * @param type Type. Only {@link Class} and {@link java.lang.reflect.ParameterizedType} are allowed
  78    * @return {@link com.intellij.util.xml.reflect.DomGenericInfo} instance for the desired type
  79    */
  80   public abstract DomGenericInfo getGenericInfo(Type type);
  81
  82   /**
  83    * @param element tag
  84    * @return DOM element for the given tag. If DOM isn't initialized for the containing file, it will be initialized
  85    */
  86   @Nullable
  87   public abstract DomElement getDomElement(@Nullable final XmlTag element);
  88
  89   /**
  90    * @param element attribute
  91    * @return DOM element for the given XML attribute. If DOM isn't initialized for the containing file, it will be initialized
  92    */
  93   @Nullable
  94   public abstract GenericAttributeValue getDomElement(final XmlAttribute element);
  95
  96   /**
  97    * @param aClass Desired DOM element class
  98    * @param module One may wish the result to think that it is in a particular module
  99    * @param physical see {@link com.intellij.psi.PsiFile#isPhysical()}
 100    * @return DOM element which doesn't have any real file under itself. A mock file is created for it. See
 101    * {@link com.intellij.psi.PsiFileFactory#createFileFromText(String, com.intellij.openapi.fileTypes.FileType, CharSequence, long, boolean, boolean)}
 102    */
 103   public abstract <T extends DomElement> T createMockElement(Class<T> aClass, final Module module, final boolean physical);
 104
 105   /**
 106    * @param element DOM element
 107    * @return true if this element was created by {@link #createMockElement(Class, com.intellij.openapi.module.Module, boolean)} method
 108    */
 109   public abstract boolean isMockElement(DomElement element);
 110
 111   /**
 112    * Creates DOM element of needed type, that is wrapper around real DOM element. Once the wrapped element
 113    * becomes invalid, a new value is requested from provider parameter, so there's a possibility to
 114    * restore the functionality. The resulting element will also implement StableElement interface.
 115    *
 116    * @param provider provides values to be wrapped
 117    * @return stable DOM element
 118    */
 119   public abstract <T extends DomElement> T createStableValue(Factory<T> provider);
 120
 121   /**
 122    * Registers a new {@link com.intellij.util.xml.DomFileDescription} within the manager. The description parameter describes some DOM
 123    * parameters and restrictions to the particular XML files, that need DOM support. Should be called on
 124    * {@link com.intellij.openapi.components.ProjectComponent} loading.
 125    * @param description The description in question
 126    * @deprecated Make your file description an extension (see {@link com.intellij.util.xml.DomFileDescription#EP_NAME})
 127    */
 128   public abstract void registerFileDescription(DomFileDescription description);
 129
 130   /**
 131    * @return {@link com.intellij.util.xml.ConverterManager} instance
 132    */
 133   public abstract ConverterManager getConverterManager();
 134
 135   @Deprecated
 136   public abstract void addPsiReferenceFactoryForClass(Class clazz, PsiReferenceFactory psiReferenceFactory);
 137
 138   public abstract ModelMerger createModelMerger();
 139
 140
 141   /**
 142    * @param element reference element
 143    * @return element that represents the resolve scope for the given reference. {@link com.intellij.util.xml.DomResolveConverter} uses
 144    * this method to resolve DOM references. This result's subtree will be traversed recursively searching for the reference target. See
 145    * {@link com.intellij.util.xml.Resolve} annotaion.
 146    */
 147   @NotNull
 148   public abstract DomElement getResolvingScope(GenericDomValue element);
 149
 150   /**
 151    * @param element Named DOM element
 152    * @return The scope within which the element's name identity will be checked by
 153    * {@link com.intellij.util.xml.highlighting.DomHighlightingHelper#checkNameIdentity(DomElement, com.intellij.util.xml.highlighting.DomElementAnnotationHolder)}
 154    */
 155   @Nullable
 156   public abstract DomElement getIdentityScope(DomElement element);
 157
 158   /**
 159    * @return {@link com.intellij.util.xml.TypeChooserManager} instance
 160    */
 161   public abstract TypeChooserManager getTypeChooserManager();
 162
 163   @Nullable
 164   public abstract AbstractDomChildrenDescription findChildrenDescription(@NotNull XmlTag templateChildTag, @NotNull DomElement parent);
 165 }