src/third_party/WebKit/Source/core/html/imports/HTMLImport.h

   1 /*
   2  * Copyright (C) 2013 Google Inc. All rights reserved.
   3  *
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions are
   6  * met:
   7  *
   8  *     * Redistributions of source code must retain the above copyright
   9  * notice, this list of conditions and the following disclaimer.
  10  *     * Redistributions in binary form must reproduce the above
  11  * copyright notice, this list of conditions and the following disclaimer
  12  * in the documentation and/or other materials provided with the
  13  * distribution.
  14  *     * Neither the name of Google Inc. nor the names of its
  15  * contributors may be used to endorse or promote products derived from
  16  * this software without specific prior written permission.
  17  *
  18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  21  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  22  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  23  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  24  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  25  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  26  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  27  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  28  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29  */
  30
  31 #ifndef HTMLImport_h
  32 #define HTMLImport_h
  33
  34 #include "core/html/imports/HTMLImportState.h"
  35 #include "wtf/TreeNode.h"
  36 #include "wtf/Vector.h"
  37
  38 namespace WebCore {
  39
  40 class Document;
  41 class LocalFrame;
  42 class HTMLImportChild;
  43 class HTMLImportLoader;
  44 class HTMLImportsController;
  45 class KURL;
  46
  47 //
  48 // # Basic Data Structure and Algorithms of HTML Imports implemenation.
  49 //
  50 // ## The Import Tree
  51 //
  52 // HTML Imports form a tree:
  53 //
  54 // * The root of the tree is HTMLImportsController, which is owned by the master
  55 //   document as a DocumentSupplement.
  56 //
  57 // * The non-root nodes are HTMLImportChild, which is owned by LinkStyle, that is owned by HTMLLinkElement.
  58 //   LinkStyle is wired into HTMLImportChild by implementing HTMLImportChildClient interface
  59 //
  60 // * Both HTMLImportsController and HTMLImportChild are derived from HTMLImport superclass
  61 //   that models the tree data structure using WTF::TreeNode and provides a set of
  62 //   virtual functions.
  63 //
  64 // HTMLImportsController also owns all loaders in the tree and manages their lifetime through it.
  65 // One assumption is that the tree is append-only and nodes are never inserted in the middle of the tree nor removed.
  66 //
  67 //
  68 //    HTMLImport <|- HTMLImportsController <- Document
  69 //                   *
  70 //                   |
  71 //               <|- HTMLImportChild <- LinkStyle <- HTMLLinkElement
  72 //
  73 //
  74 // # Import Sharing and HTMLImportLoader
  75 //
  76 // The HTML Imports spec calls for de-dup mechanism to share already loaded imports.
  77 // To implement this, the actual loading machinery is split out from HTMLImportChild to
  78 // HTMLImportLoader, and each loader shares HTMLImportLoader with other loader if the URL is same.
  79 // Check around HTMLImportsController::findLink() for more detail.
  80 //
  81 // HTMLImportLoader can be shared by multiple imports.
  82 //
  83 //    HTMLImportChild (1)-->(*) HTMLImportLoader
  84 //
  85 //
  86 // # Script Blocking
  87 //
  88 // - An import blocks the HTML parser of its own imported document from running <script>
  89 //   until all of its children are loaded.
  90 //   Note that dynamically added import won't block the parser.
  91 //
  92 // - An import under loading also blocks imported documents that follow from being created.
  93 //   This is because an import can include another import that has same URLs of following ones.
  94 //   In such case, the preceding import should be loaded and following ones should be de-duped.
  95 //
  96
  97 // The superclass of HTMLImportsController and HTMLImportChild
  98 // This represents the import tree data structure.
  99 class HTMLImport : public TreeNode<HTMLImport> {
 100 public:
 101     enum SyncMode {
 102         Sync  = 0,
 103         Async = 1
 104     };
 105
 106     virtual ~HTMLImport() { }
 107
 108     HTMLImport* root();
 109     bool precedes(HTMLImport*);
 110     bool isRoot() const { return !isChild(); }
 111     bool isSync() const { return SyncMode(m_sync) == Sync; }
 112     bool formsCycle() const;
 113     const HTMLImportState& state() const { return m_state; }
 114
 115     void appendImport(HTMLImport*);
 116
 117     virtual bool isChild() const { return false; }
 118     virtual Document* document() const = 0;
 119     virtual bool isDone() const = 0; // FIXME: Should be renamed to haveFinishedLoading()
 120     virtual HTMLImportLoader* loader() const { return 0; }
 121     virtual void stateWillChange() { }
 122     virtual void stateDidChange();
 123
 124 protected:
 125     // Stating from most conservative state.
 126     // It will be corrected through state update flow.
 127     explicit HTMLImport(SyncMode sync)
 128         : m_sync(sync)
 129     { }
 130
 131     static void recalcTreeState(HTMLImport* root);
 132
 133 #if !defined(NDEBUG)
 134     void show();
 135     void showTree(HTMLImport* highlight, unsigned depth);
 136     virtual void showThis();
 137 #endif
 138
 139 private:
 140     HTMLImportState m_state;
 141     unsigned m_sync : 1;
 142 };
 143
 144 } // namespace WebCore
 145
 146 #endif // HTMLImport_h