package DTDDoc;
   
   import java.io.File;
   import java.io.IOException;
   import java.util.Collection;
   import java.util.Collections;
   import java.util.HashMap;
   import java.util.HashSet;
   import java.util.Iterator;
  import java.util.List;
  import java.util.Map;
  import java.util.Set;
  
  import com.wutka.dtd.DTD;
  import com.wutka.dtd.DTDAttlist;
  import com.wutka.dtd.DTDAttribute;
  import com.wutka.dtd.DTDComment;
  import com.wutka.dtd.DTDContainer;
  import com.wutka.dtd.DTDElement;
  import com.wutka.dtd.DTDEntity;
  import com.wutka.dtd.DTDItem;
  import com.wutka.dtd.DTDName;
  import com.wutka.dtd.DTDParser;
  
  /** An object of this class represents a full DTD. That is, the result of
   * interpretation of a DTD file and all the other files it includes.
   * A DTD defines a bunch of elements and attributes (and small other things
   * as well). A DTD file can includes other DTD's file. Therefore some
   * pieces, although defined in some other files, are defined in the
   * DTD represented by <code>this</code>. We call such pieces "external".
   *
   * One of the goals of this class is to improve over Mark Wutka's DTD class so
   * that one can know if an element/attribute is "external" or not.
   *
   * @author Stefan Champailler
   */
  
  public class ExtendedDTD {
  
      private Logger log;
      private boolean getAroundNetBeanComments;
  
      private DefinitionsMap definitionsMap;
  
      /** Full path to the original DTD. */
      private File systemPath;
  
      /** The DTD, as parsed by Wutka's DTD parser. */
      private DTD dtd;
  
      /** Title of the DTD. See the @title tag.*/
      private String title = null;
  
      /** Doctype of the DTD. See the @doctype tag.*/
      private String doctype = null;
  
      /** Root tag of the DTD as declared by @root tag.*/
      private DTDElement rootElement = null;
  
      /** Encoding of the file if specified. For example, ISO-8859-1. This is dictated
       *  by the &lt;? ... encoding="" ?&gt; processing instruction.
       */
  
      private String encoding = null;
  
      /** Get the encoding specified in the file, if any. For example, ISO-8859-1. This is dictated
       *  by the &lt;? ... encoding="" ?&gt; processing instruction.
       *  @return the encoding, or <code>null</code> if no encoding was set
       *  @see #getEffectiveEncoding()
       */
  
      public String getEncoding() {
          return encoding;
      }
  
      /** Get the effective encoding of the file: either the encoding specified in the file,
       * or the default encoding (UTF-8) if not specified
       *  @return the effective encoding (not <code>null</code>)
       */
  
      // FIXME Is UTF-8 the default encoding when nothing is specified in the DTD
      // ? Is it in the DTD spec ? Anyway, we should put a reference to the spec
      // here so I don't ask that myself again.
  
      public String getEffectiveEncoding() {
          return (encoding == null) ? "UTF-8" : encoding;
      }
  
      /** Mapping between each element of the DTD and its parent (as long as
       *  the parent is defined in this DTD). key = String: element's name,
       *  value = (Set of DTDElement) its parent elements (most of the time, only one parent) */
      private Map parents = null;
  
      /** Returns the title of the DTD (see the @title tag).
       *  @return the title of the DTD. */
      public String getTitle() {
          return title;
      }
  
     /** Returns the doctype of the DTD (see the doctype tag).
      *  @return the doctype of the DTD. */
     public String getDoctype() {
         return doctype;
     }
 
     /** Return all the DTDItems of the DTD (a transparent wrapper around
      *  the same function in Wutka's library).
      * @return The DTD Items of the DTD. */
     public List getItems() {
         return dtd.items;
     }
 
     /** Return all the DTDElements of the DTD (a transparent wrapper around
      *  the same function in Wutka's library).
      * @return A mapping from the name of the elements to their instance. */
     public Map getElements() {
         return dtd.elements;
     }
 
     public Collection getElementsCollection() {
         return dtd.elements.values();
     }
 
     public DTDElement getElementByName( String name) {
         Object o = getElements().get( name);
         if (o == null) {
             log.warn("Invalid name or the element doesn't exist (" + name + ").");
         }
         return (DTDElement) o;
     }
 
     public DTDElement getElementByName( DTDName name) {
         return getElementByName( name.getValue());
     }
 
     /** Return all the DTDEntities of the DTD (a transparent wrapper around
      *  the same function in Wutka's library).
      * @return A mapping from the name of the entities to their instance. */
     public Map getEntities() {
         return dtd.entities;
     }
 
     /** Returns the root elements of the DTD, as defined by the \@root tag.
       * @return the root element. */
     public DTDElement getRootElement() {
         return rootElement;
     }
 
     /** Setter for the root elements of the DTD.
       * @param element The root element.*/
     public void setRootElement(DTDElement element) {
         rootElement = element;
     }
 
     /** Returns the full path to the original DTD.
      *  @return Full path to the original DTD.. */
     public File getSystemPath() {
         return systemPath;
     }
 
     /** Tells if an element is declared in a DTD outside the one represented in
      * <code>this</code>.
      *
      * @param element element to be checked for externality
      * @return true if external, false if not (or element not part of the DTD's
      *     elements. */
 
     public boolean isExternal(DTDElement element) {
         String elementPath = definitionsMap.getLocation(element);
         return !elementPath.equals(getSystemPath().getPath());
     }
 
     /** Determine if an attributes list is defined in this DTD.
      *  @param attList attributes list to look for.
      *  @return true if the list is defined outside this DTD (therefore
      *      in another one. */
 
     public boolean isExternal(DTDAttlist attList) {
         return isExternal(getElementByName(attList.getName()));
     }
 
     /** Gives the file name of the DTD where a given element is defined.
      *
      * @param element element to be checked
      * @return the file name or <code>null</code> if the element is
      *     not part of the DTD. */
 
     public String getElementOrigin(DTDElement element) {
         String elementPath = definitionsMap.getLocation(element);
 
         if (elementPath == null)
             log.warn(
                 "Requesting info about a non existing element: "
                     + element.name);
         return elementPath;
     }
 
     /** Build all the information needed to make a ExtendedDTD out of
      *  a "normal" DTD. The original DTD will be read with Mark Wutka's
      *  powerful DTD parser.
      *
      *  @param dtdFilePath Path to the original DTD. */
 
     public ExtendedDTD(File dtdFilePath, Logger log, boolean
         getAroundNetBeanComments) throws IOException {
 
         this.log = log;
         this.getAroundNetBeanComments = getAroundNetBeanComments;
         this.systemPath = dtdFilePath;
 
         if (!getSystemPath().canRead())
             throw new IOException(
                 "Can't read " + getSystemPath()
                     + ". Be prepared to get tons of errors !");
 
         DTDParser dtdParser = new DTDParser(getSystemPath());
         dtd = dtdParser.parse(true);
         encoding = dtdParser.getDTDEncoding();
 
         definitionsMap = locateElements(getSystemPath().getPath(), dtd);
 
         findDeclaredRootElement();
         attributesListMap = makeAttributesListsMap(dtd.items);
         parents = findParents(dtd);
     }
 
     /** For a given DTD, this function will build a map
      *  associating each of its elements (included those defined in
      *  its children) to the system-name of the DTDs in which those elements
      *  are defined. This function is necessary because Wutka's code
      *  doesn't do that correctly.
      *
      *  This function is VERY INEFFICIENT !
      *
      *  @param filePath where the DTD file is located.
      */
 
     private DefinitionsMap locateElements(String filePath, DTD dtd) throws IOException {
 
         // Read the DTD
         // Very inefficient stuff here ...
 
         if (dtd == null) {
             File f = new File(filePath);
 
             try {
                 DTDParser dtdParser = new DTDParser(f);
                 dtd = dtdParser.parse(true);
             } catch (Exception ex) {
                 log.warn("locateElements():can't read " + filePath);
                 return null;
             }
         }
 
         // Analysing...
 
         DefinitionsMap defMap = new DefinitionsMap();
 
         // First, collect the position of elements defined in children DTDs.
         // Children DTD are enumerated in the entities.
 
         Iterator items = dtd.entities.values().iterator();
         while (items.hasNext()) {
 
             DTDEntity entity = (DTDEntity) items.next();
 
             // We're only interested in the *external DTD files*. Therefore
             // we have the following tests.
 
             String nextFile = null;
 
             if (entity.getExternalID() != null)
                 nextFile = entity.getExternalID().getSystem();
 
             // We work only with files that are on the current filesystem
             // FIXME: break this limitation please !
 
             if (nextFile != null
                 && !(nextFile.startsWith("http:")
                     || nextFile.startsWith("file:"))) {
 
                 // FIXME: We're not sure if this is gonna work for files
                 // that are placed in different directories. This depends
                 // on the nature of externalID.system (which we don't know
                 // for sure yet).
 
                 nextFile =
                     filePath.substring(
                         0,
                         filePath.lastIndexOf(File.separatorChar) + 1)
                         + nextFile;
 
                 // log.debug( "///// diving in "+nextFile);
                 defMap.merge(locateElements(nextFile, null));
             }
         }
 
         // Now that we know which elements are defined in the children,
         // we can find out those which are defined in the present DTD.
         // The idea is simple, an element is defined in this DTD (and not
         // in its children) if and only if it's not defined in its
         // children. Sometimes we work on obvious things...
 
         items = dtd.elements.values().iterator();
         while (items.hasNext()) {
             DTDElement element = (DTDElement) items.next();
             defMap.add(element, filePath);
         }
 
         return defMap;
     }
 
     /** Tag starting a root element defintion (@root) */
     private static final String ROOT_TAG = DTDCommenter.ROOT_TAG;
 
     /** Tag starting a DTD title defintion (@title) */
     private static final String TITLE_TAG = DTDCommenter.TITLE_TAG;
 
     /** Tag starting a DTD doctype defintion (@doctype) */
     private static final String DOCTYPE_TAG = DTDCommenter.DOCTYPE_TAG;
 
     /** This function will locate the "@root" element in the comments
       * in a given DTD.
       * With that information, it will determine the root of the
       * DTD and update the necessary member (i.e. rootElement).
       *
       * @return the value of the first "@root" doc-tag found.
       */
 
     private String findRootTagValue() {
 
         String rootName = null;
         Iterator elements = getItems().iterator();
 
         while (elements.hasNext()) {
 
             Object obj = elements.next();
 
             // Are we on a comment ?
             if (obj instanceof DTDComment) {
 
                 DTDComment comment = (DTDComment) obj;
 
                 // Since all the comments from the included files also
                 // appear in the DTD, we have to make sure we only look
                 // at the relevant one.
 
                 // Then, we parse it...
                 CommentParser cp = new CommentParser( comment, log,
                     getAroundNetBeanComments);
                 String rn = cp.getUniqueTagValue(ROOT_TAG);
 
                 // So, if we found the @root tag, it's cool but we have to
                 // make sure that this one is related to the DTD and not one
                 // of its children.
 
                 if (rn != null) {
                     DTDElement rnElmt = getElementByName(rn);
                     if ((rnElmt != null) && (!isExternal(rnElmt))) {
                         rootName = rn;
                     } else
                         log.warn(
                             "The root element you specified with \""
                                 + ROOT_TAG + ' ' + rn
                                 + "\" doesn't exist in the DTD !");
                 }
 
                 // Now we figure out the title
                 String t = cp.getUniqueTagValue(TITLE_TAG);
                 if (t != null) {
                     title = t;
                 }
 
                 t = cp.getUniqueTagValue(DOCTYPE_TAG);
                 if (t != null) {
                     doctype = t;
                 }
             } else if ((obj instanceof DTDElement) || (obj instanceof DTDEntity)) {
                 // root tag, title and doctype definitions are valid in first comment only
                 // then we stop when we find the first element or entoty definition (= heuristics)
                 break;
             }
         }
 
         if (title == null) {
             title = Tools.getFilename(systemPath.getName());
         }
 
         return rootName;
     }
 
     /** This function will set the rootElement member in the dtd
       * according to the value to be found in the "@root" doc-tag. */
 
     private void findDeclaredRootElement() {
 
         String rootName = findRootTagValue();
 
         // Did we find the @root doc-tag.
         if (rootName != null) {
             DTDElement rootNameElement = getElementByName(rootName);
 
             // Yes, make sure that this root really exists
             if (rootNameElement != null) {
                 // It does ! Now we can update the DTD.
                 setRootElement(rootNameElement);
             } else
                 // It doesn't. Therefore...
                 log.warn(
                     "The provided root element ("
                         + ROOT_TAG + " " + rootName
                         + ") is nowhere to be found in the DTD!");
 
         }
     }
 
     /** Gives a unique id for an attribute in a DTD. The id construction
      *  relies on the fact that an attribute is always related to a element.
      *  That is each (element, attribute) pair is unique in a DTD.
      *
      * @param attList The attributes list the attibute is part of.
      * @param attribute The attribute for which we seek the id.
      * @return The id of the attribute.
      */
 
     public static String getUniqueId( DTDAttlist attList, DTDAttribute attribute) {
         // attList.name is the element's name.
         return attList.name + '_' + attribute.getName();
     }
 
     /** Gives a unique id for an attribute in a DTD.
      *
      * @param element The element to which the attribute belongs.
      * @param attribute The attribute to get the id for.
      * @return The id of the attribute.
      * @see #getUniqueId( DTDAttlist attList, DTDAttribute attribute)
      */
     public static String getUniqueId( DTDElement element, DTDAttribute attribute) {
         return element.name + '_' + attribute.getName();
     }
 
     /** Gives a unique id for an element of a DTD.
      *
      * @param element The element.
      * @return The id of the element.
      */
 
     public static String getUniqueId( DTDElement element) {
         return element.getName();
     }
 
     /**
      * key = DTDAttribute , value = DTDAttList
      * @see #makeAttributesListsMap
      */
     private final Map attributesListMap;
 
     public DTDAttlist locateAttributesList(DTDAttribute attribute) {
         return (DTDAttlist) attributesListMap.get(attribute);
     }
 
     private static Map makeAttributesListsMap(List dtdItems) {
 
         Map hash = new HashMap();
 
         for (Iterator iter = dtdItems.iterator(); iter.hasNext(); ) {
                 Object item = iter.next();
 
             if (item instanceof DTDAttlist) {
                 DTDAttlist attList = (DTDAttlist) item;
 
                 for (Iterator iter2 = attList.attributes.iterator(); iter2.hasNext(); )
                     hash.put(iter2.next(), attList);
             }
         }
 
         return hash;
     }
 
     /** Builds an map associating each descendant of an element to its parent
      *  (the element itself :)). All the elements of the given DTD are
      *  examined.
      *
      *  @param dtd A DTD where to look for the elements
      *  @return A map associating the names (string) of each element
      *      to a Set of its parents (most of the time, only one parent). */
 
     private static Map findParents(DTD dtd) {
         Map parents = new HashMap();
 
         Iterator i = dtd.elements.values().iterator();
 
         // We scan all the elements of the DTD
         while(i.hasNext()) {
 
             DTDElement element = (DTDElement) i.next();
 
             // We make sure that each element appears in the map.
 
             String k = element.getName();
 
             if( !parents.containsKey( k))
                 parents.put( k, null);
 
             // Now we set each element's child parent to the element.
 
             // Not all elements have children (for example, an
             // element can be EMPTY)
             Set children = collectDeclaredChildren( element);
 
             if( children != null) {
                 for ( Iterator j = children.iterator(); j.hasNext();) {
                     Object o = j.next();
 
                     if (o instanceof DTDName) {
 
                         String cName = ((DTDName) o).getValue();
 
                         // Each child of e has e as parent.
                         // Except that an element can't be his
                         // own parent.
 
                         if( !element.getName().equals( cName)) {
                             Set parentElements = (Set) parents.get(cName);
 
                             if (parentElements == null)
                                 parentElements = new HashSet();
 
                             parentElements.add(element);
 
                             parents.put(cName, parentElements);
                         }
                         // log.debug(children[j].toString()+"("+ ((DTDName)children[j]).getValue() +")" + " --> "+ e+ "("+((DTDElement)e).getName()+")");
                     }
                 }
             }
         }
 
         return parents;
     }
 
     /** Gets the parents of an element.
      *
      * @param sonName The name of the element to look for.
      * @return Null if the element doesn't exist or it has no parent.
      */
 
     public Set getParents(String sonName) {
         return (Set) parents.get(sonName);
     }
 
     /** Check if an element is root, that is, if it has no parent.
      *
      * @param element The element to check.
      * @return True if its is root, false else.
      */
 
     public boolean isRoot( DTDElement element) {
         Set parents = getParents( element.getName());
         return parents == null || parents.size() == 0;
     }
 
     /** Collects the elements that appear in the definition of
      * a given element (its "children").
      *
      * <p>Special definitions such as ANY, EMPTY and PCDATA are ignored.</p>
      *
      * @param element The element.
      * @return The set of children or null if there ain't any child.
      */
 
     public static Set collectDeclaredChildren( DTDElement element) {
         return collectDeclaredChildrenHelper( element.getContent());
     }
 
     private static Set collectDeclaredChildrenHelper( DTDItem item) {
 
         if (item instanceof DTDContainer) {
 
             Iterator items = ((DTDContainer) item).getItemsVec().iterator();
 
             Set children = null;
 
             while (items.hasNext()) {
                 Set s = collectDeclaredChildrenHelper( (DTDItem)items.next());
                 if (s != null) {
                     if( children == null) children = new HashSet();
                     children.addAll(s);
                 }
             }
 
             return children;
 
         } else if (item instanceof DTDName)
 
             return Collections.singleton( item);
 
         else
             // ANY, PCDATA and EMPTY are not considered as children, they
             // are not named.
             return null;
     }
 
 }