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 "platform/heap/Handle.h"
  36 #include "wtf/TreeNode.h"
  37
  38 namespace blink {
  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 HTMLImportTreeRoot.
  55 //
  56 // * The HTMLImportTreeRoot is owned HTMLImportsController, which is owned by the master
  57 //   document as a DocumentSupplement.
  58 //
  59 // * The non-root nodes are HTMLImportChild. They are all owned by HTMLImporTreeRoot.
  60 //   LinkStyle is wired into HTMLImportChild by implementing HTMLImportChildClient interface
  61 //
  62 // * Both HTMLImportTreeRoot and HTMLImportChild are derived from HTMLImport superclass
  63 //   that models the tree data structure using WTF::TreeNode and provides a set of
  64 //   virtual functions.
  65 //
  66 // HTMLImportsController also owns all loaders in the tree and manages their lifetime through it.
  67 // One assumption is that the tree is append-only and nodes are never inserted in the middle of the tree nor removed.
  68 //
  69 // Full diagram is here:
  70 // https://docs.google.com/drawings/d/1jFQrO0IupWrlykTNzQ3Nv2SdiBiSz4UE9-V3-vDgBb0/
  71 //
  72 // # Import Sharing and HTMLImportLoader
  73 //
  74 // The HTML Imports spec calls for de-dup mechanism to share already loaded imports.
  75 // To implement this, the actual loading machinery is split out from HTMLImportChild to
  76 // HTMLImportLoader, and each loader shares HTMLImportLoader with other loader if the URL is same.
  77 // Check around HTMLImportsController::findLink() for more detail.
  78 //
  79 // HTMLImportLoader can be shared by multiple imports.
  80 //
  81 //    HTMLImportChild (1)-->(*) HTMLImportLoader
  82 //
  83 //
  84 // # Script Blocking
  85 //
  86 // - An import blocks the HTML parser of its own imported document from running <script>
  87 //   until all of its children are loaded.
  88 //   Note that dynamically added import won't block the parser.
  89 //
  90 // - An import under loading also blocks imported documents that follow from being created.
  91 //   This is because an import can include another import that has same URLs of following ones.
  92 //   In such case, the preceding import should be loaded and following ones should be de-duped.
  93 //
  94
  95 // The superclass of HTMLImportTreeRoot and HTMLImportChild
  96 // This represents the import tree data structure.
  97 class HTMLImport : public NoBaseWillBeGarbageCollectedFinalized<HTMLImport>, public TreeNode<HTMLImport> {
  98 public:
  99     enum SyncMode {
 100         Sync  = 0,
 101         Async = 1
 102     };
 103
 104     virtual ~HTMLImport() { }
 105
 106     // FIXME: Consider returning HTMLImportTreeRoot.
 107     HTMLImport* root();
 108     bool precedes(HTMLImport*);
 109     bool isRoot() const { return !parent(); }
 110     bool isSync() const { return SyncMode(m_sync) == Sync; }
 111     bool formsCycle() const;
 112     const HTMLImportState& state() const { return m_state; }
 113
 114     void appendImport(HTMLImport*);
 115
 116     virtual Document* document() const = 0;
 117     virtual bool isDone() const = 0; // FIXME: Should be renamed to haveFinishedLoading()
 118     virtual HTMLImportLoader* loader() const { return 0; }
 119     virtual void stateWillChange() { }
 120     virtual void stateDidChange();
 121
 122     virtual void trace(Visitor*) { }
 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 blink
 145
 146 #endif // HTMLImport_h