dom/openapi/src/com/intellij/util/xml/package.html

   1 <!--
   2   ~ Copyright 2000-2007 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
  17 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  18 <html><body bgcolor="white">
  19 {@link com.intellij.util.xml.DomElement} interface is used to represent Schema- or DTD-based XML trees. It is more consistent,
  20 than the standard XML PSI tree. The concrete code dealing with XML is generated at runtime, based
  21 on your interfaces structure. For every needed XML type one should create subinterface of
  22 DomElement. This subinterface may have XML methods, that are used for getting children of tag,
  23 corresponding to current instance of the interface. Methods (getters and setters) may have the
  24 following annotations:
  25 <p>
  26 <li>@{@link com.intellij.util.xml.TagValue} - method will deal (get or set) with tag text contents.</li>
  27 <li>@{@link com.intellij.util.xml.Attribute} - gets attribute value. Attribute name is specified in "value" property.</li>
  28 <li>@{@link com.intellij.util.xml.SubTag} - method (getter only) will deal with subtag. Should return instance of DomElement (the child DomElement type
  29   is inferred from return type of
  30   method). The subtag name
  31   is specified in "value" property. If there are several (fixed count) of same-named subtags,
  32   "index" property can specify, which subtag value should be returned. Sometimes the tag's existence
  33   is itself a value (a boolean one), then set property "indicator" to "true" (cannot be used with "index")
  34 </li>
  35 <li>@{@link com.intellij.util.xml.SubTagList} - method will deal with subtag collection. Should return Collection of DomElements. The
  36   subtag name is specified in "value" property. The resulting Collection is immutable. There can be no
  37   setters annotated with it. Instead of them one may have "addition" methods: "MyDomElement addCollectionElement()".
  38   These addition methods may have "index" argument, specifying, where in collection to insert. One may not have
  39   one subtag name for both fixed-count children and collections.
  40 </li>
  41 <li>@{@link com.intellij.util.xml.SubTagsList} - If you have several @{@link com.intellij.util.xml.SubTagList}
  42   collections and you need to access them all at once, this
  43   annotation will help. "value" property will hold the array of possible subtag names. One should have different
  44   addition methods for each subtag name, each returning its own DomElement type, each may have an "index" parameter.
  45   The element will be inserted in proper place in the "merged" collection, allowing you to mix elements of different
  46   types (if Schema or DTD allows).
  47 </li>
  48 <p>
  49   One may annotate not every method, then the corresponding property classes and values are inferred from
  50   the method name, method return type and parameter types. For non-indicator subtag values with index 0 it's
  51   "SomeType getSomeName()", for collections - "{@link java.util.Collection}&lt;SomeType> getSomeNames()" and "SomeType addSomeName()".
  52   (SomeType should extend {@link com.intellij.util.xml.DomElement}). For tag value the default methods are "getValue" and "setValue". The
  53   name
  54   is inferred using {@link com.intellij.util.xml.DomNameStrategy} subclasses. The default is {@link com.intellij.util.xml.HyphenNameStrategy}, which splits the
  55   camelhump name and joins the resulting words with "-". Another standard strategy is {@link com.intellij.util.xml.JavaNameStrategy},
  56   that preserves the camel humps. Name strategy can be specified by @{@link com.intellij.util.xml.NameStrategy} annotation.
  57 <p>
  58   {@link com.intellij.util.xml.DomElement}'s may have implementation for some methods, that are not directly connected with XML structure.
  59   An implementation class should be abstract class implementing this interface with only needed methods.
  60   Implementation classes can be specified via @{@link com.intellij.util.xml.Implementation} annotation, or in {@link com.intellij.util.xml.DomFileDescription}.
  61 <p>
  62   DomElement's are created in {@link com.intellij.util.xml.DomManager}. One should register {@link com.intellij.util.xml.DomFileDescription} in
  63   {@link com.intellij.util.xml.DomManager}
  64   and provide root tag name and root {@link com.intellij.util.xml.DomElement} class.
  65   Also one can create mock DOM elements ({@link com.intellij.util.xml.DomManager#createMockElement(Class, com.intellij.openapi.module.Module, boolean)},
  66   that are not connected with any disk XML file. One can copy contents
  67   from one DOM element to another using {@link com.intellij.util.xml.DomElement#copyFrom(com.intellij.util.xml.DomElement)} method.
  68 <p>
  69   {@link com.intellij.util.xml.DomElementVisitor} subclasses can have methods like "visitTypeName(TypeName element)" where TypeName is
  70   some {@link com.intellij.util.xml.DomElement} subclass. Then such methods will be called in
  71   {@link com.intellij.util.xml.DomElement#accept(com.intellij.util.xml.DomElementVisitor)}.
  72 <p>
  73   There's some kind of reflection, getting information about supported fixed and collection children.
  74   It's obtained via {@link com.intellij.util.xml.DomManager#getGenericInfo(java.lang.reflect.Type)} or {@link com.intellij.util.xml.DomElement#getGenericInfo()}.
  75 <p>
  76   Standard way of representing children with tag value only is using {@link com.intellij.util.xml.GenericDomValue}&lt;T>, which has method
  77   T getValue().
  78 <p>
  79   If one has simple accessor method returning non-standard type, or GenericDomValue parameterized by non-standard type
  80   (standard types are {@link String}, {@link com.intellij.psi.PsiClass}, {@link com.intellij.psi.PsiType}, {@link Integer},
  81   {@link Boolean}, enums),
  82   one should specify {@link com.intellij.util.xml.Converter} by @{@link com.intellij.util.xml.Convert} annotation near
  83   the method that gets this type or {@link com.intellij.util.xml.GenericDomValue}.
  84 <p>
  85   See our Java EE and Weblogic models for examples.
  86 </body></html>