xml/dom-openapi/src/com/intellij/util/xml/DomElement.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.psi.xml.XmlElement;
  19 import com.intellij.psi.xml.XmlTag;
  20 import com.intellij.psi.search.GlobalSearchScope;
  21 import com.intellij.util.xml.reflect.DomGenericInfo;
  22 import com.intellij.util.xml.reflect.AbstractDomChildrenDescription;
  23 import com.intellij.openapi.module.Module;
  24 import com.intellij.openapi.util.UserDataHolder;
  25 import org.jetbrains.annotations.NotNull;
  26 import org.jetbrains.annotations.Nullable;
  27 import org.jetbrains.annotations.NonNls;
  28
  29 import java.lang.reflect.Type;
  30
  31 /**
  32  * Base interface for DOM elements. Every DOM interface should extend this one.
  33  *
  34  * @author peter
  35  */
  36 public interface DomElement extends AnnotatedElement, UserDataHolder {
  37   DomElement[] EMPTY_ARRAY = new DomElement[0];
  38
  39   XmlTag getXmlTag();
  40
  41   /**
  42    * Returns the underlying XML element/file.
  43    *
  44    * @return {@link com.intellij.psi.xml.XmlFile}, {@link com.intellij.psi.xml.XmlTag} or {@link com.intellij.psi.xml.XmlAttribute}
  45    */
  46   @Nullable
  47   XmlElement getXmlElement();
  48
  49   @Nullable
  50   DomElement getParent();
  51
  52   XmlTag ensureTagExists();
  53
  54   XmlElement ensureXmlElementExists();
  55
  56   /**
  57    * Removes all corresponding XML content. In case of being collection member, invalidates the element.
  58    */
  59   void undefine();
  60
  61   boolean isValid();
  62
  63   @NotNull
  64   DomGenericInfo getGenericInfo();
  65
  66   @NotNull @NonNls String getXmlElementName();
  67
  68   @NotNull @NonNls String getXmlElementNamespace();
  69
  70   /**
  71    * @return namespace key if this element or one of its ancestors is annotated with
  72    * {@link Namespace}, or null otherwise, which means that namespace should be equal
  73    * to that of the element's parent
  74    */
  75   @Nullable @NonNls String getXmlElementNamespaceKey();
  76
  77   void accept(final DomElementVisitor visitor);
  78
  79   void acceptChildren(DomElementVisitor visitor);
  80
  81   @NotNull
  82   DomManager getManager();
  83
  84   @NotNull
  85   Type getDomElementType();
  86
  87   AbstractDomChildrenDescription getChildDescription();
  88
  89   @NotNull
  90   DomNameStrategy getNameStrategy();
  91
  92   @NotNull
  93   ElementPresentation getPresentation();
  94
  95   GlobalSearchScope getResolveScope();
  96
  97   /**
  98    * Walk up the DOM tree searching for element of requiredClass type
  99    * @param requiredClass parent element's type
 100    * @param strict
 101    * <ul>
 102    * <li>strict = false: if the current element is already of the correct type, then it is returned.</li>
 103    * <li>strict = true: the returned element must be higher in the hierarchy.</li>
 104    * </ul>
 105    * @return the parent of requiredClass type
 106    */
 107   @Nullable
 108   <T extends DomElement> T getParentOfType(Class<T> requiredClass, boolean strict);
 109
 110   @Nullable
 111   Module getModule();
 112
 113   void copyFrom(DomElement other);
 114
 115   <T extends DomElement> T createMockCopy(final boolean physical);
 116
 117   /**
 118    * @return stable element (see {@link DomManager#createStableValue(com.intellij.openapi.util.Factory)}}),
 119    * that holds the complete 'XPath' to this element in XML. If this element is in collection, and something
 120    * is inserted before it, the stable copy behaviour may be unexpected. So use this method only when you
 121    * are sure that nothing serious will happen during the lifetime of the stable copy. The most usual use
 122    * case is when one creates something inside {@link com.intellij.openapi.command.WriteCommandAction} and
 123    * wants to use it outside the action. Due to formatting done on the command finish the element may become
 124    * invalidated, but the stable copy will survive, because nothing in fact has changed in its 'XPath'.
 125    */
 126   <T extends DomElement> T createStableCopy();
 127
 128 }