michael@0: /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #ifndef nsXULTemplateBuilder_h__
michael@0: #define nsXULTemplateBuilder_h__
michael@0: 
michael@0: #include "nsStubDocumentObserver.h"
michael@0: #include "nsIScriptSecurityManager.h"
michael@0: #include "nsIObserver.h"
michael@0: #include "nsIRDFCompositeDataSource.h"
michael@0: #include "nsIRDFContainer.h"
michael@0: #include "nsIRDFContainerUtils.h"
michael@0: #include "nsIRDFDataSource.h"
michael@0: #include "nsIRDFObserver.h"
michael@0: #include "nsIRDFService.h"
michael@0: #include "nsIXULTemplateBuilder.h"
michael@0: 
michael@0: #include "nsCOMArray.h"
michael@0: #include "nsTArray.h"
michael@0: #include "nsDataHashtable.h"
michael@0: #include "nsTemplateRule.h"
michael@0: #include "nsTemplateMatch.h"
michael@0: #include "nsIXULTemplateQueryProcessor.h"
michael@0: #include "nsCycleCollectionParticipant.h"
michael@0: 
michael@0: #include "prlog.h"
michael@0: #ifdef PR_LOGGING
michael@0: extern PRLogModuleInfo* gXULTemplateLog;
michael@0: #endif
michael@0: 
michael@0: class nsIContent;
michael@0: class nsIObserverService;
michael@0: class nsIRDFCompositeDataSource;
michael@0: class nsIXULDocument;
michael@0: 
michael@0: /**
michael@0:  * An object that translates an RDF graph into a presentation using a
michael@0:  * set of rules.
michael@0:  */
michael@0: class nsXULTemplateBuilder : public nsIXULTemplateBuilder,
michael@0:                              public nsIObserver,
michael@0:                              public nsStubDocumentObserver
michael@0: {
michael@0:     void CleanUp(bool aIsFinal);
michael@0: 
michael@0: public:
michael@0:     nsXULTemplateBuilder();
michael@0:     virtual ~nsXULTemplateBuilder();
michael@0: 
michael@0:     nsresult InitGlobals();
michael@0: 
michael@0:     /**
michael@0:      * Clear the template builder structures. The aIsFinal flag is set to true
michael@0:      * when the template is going away.
michael@0:      */
michael@0:     virtual void Uninit(bool aIsFinal);
michael@0: 
michael@0:     // nsISupports interface
michael@0:     NS_DECL_CYCLE_COLLECTING_ISUPPORTS
michael@0:     NS_DECL_CYCLE_COLLECTION_CLASS_AMBIGUOUS(nsXULTemplateBuilder,
michael@0:                                              nsIXULTemplateBuilder)
michael@0: 
michael@0:     // nsIXULTemplateBuilder interface
michael@0:     NS_DECL_NSIXULTEMPLATEBUILDER
michael@0: 
michael@0:     // nsIObserver Interface
michael@0:     NS_DECL_NSIOBSERVER
michael@0: 
michael@0:     // nsIMutationObserver
michael@0:     NS_DECL_NSIMUTATIONOBSERVER_ATTRIBUTECHANGED
michael@0:     NS_DECL_NSIMUTATIONOBSERVER_CONTENTREMOVED
michael@0:     NS_DECL_NSIMUTATIONOBSERVER_NODEWILLBEDESTROYED
michael@0: 
michael@0:     /**
michael@0:      * Remove an old result and/or add a new result. This method will retrieve
michael@0:      * the set of containers where the result could be inserted and either add
michael@0:      * the new result to those containers, or remove the result from those
michael@0:      * containers. UpdateResultInContainer is called for each container.
michael@0:      *
michael@0:      * @param aOldResult result to remove
michael@0:      * @param aNewResult result to add
michael@0:      * @param aQueryNode query node for new result
michael@0:      */
michael@0:     nsresult
michael@0:     UpdateResult(nsIXULTemplateResult* aOldResult,
michael@0:                  nsIXULTemplateResult* aNewResult,
michael@0:                  nsIDOMNode* aQueryNode);
michael@0: 
michael@0:     /**
michael@0:      * Remove an old result and/or add a new result from a specific container.
michael@0:      *
michael@0:      * @param aOldResult result to remove
michael@0:      * @param aNewResult result to add
michael@0:      * @param aQueryNode queryset for the new result
michael@0:      * @param aOldId id of old result
michael@0:      * @param aNewId id of new result
michael@0:      * @param aInsertionPoint container to remove or add result inside
michael@0:      */
michael@0:     nsresult
michael@0:     UpdateResultInContainer(nsIXULTemplateResult* aOldResult,
michael@0:                             nsIXULTemplateResult* aNewResult,
michael@0:                             nsTemplateQuerySet* aQuerySet,
michael@0:                             nsIRDFResource* aOldId,
michael@0:                             nsIRDFResource* aNewId,
michael@0:                             nsIContent* aInsertionPoint);
michael@0: 
michael@0:     nsresult
michael@0:     ComputeContainmentProperties();
michael@0: 
michael@0:     static bool
michael@0:     IsTemplateElement(nsIContent* aContent);
michael@0: 
michael@0:     virtual nsresult
michael@0:     RebuildAll() = 0; // must be implemented by subclasses
michael@0: 
michael@0:     void RunnableRebuild() { Rebuild(); }
michael@0:     void RunnableLoadAndRebuild() {
michael@0:       Uninit(false);  // Reset results
michael@0: 
michael@0:       nsCOMPtr<nsIDocument> doc = mRoot ? mRoot->GetDocument() : nullptr;
michael@0:       if (doc) {
michael@0:         bool shouldDelay;
michael@0:         LoadDataSources(doc, &shouldDelay);
michael@0:         if (!shouldDelay) {
michael@0:           Rebuild();
michael@0:         }
michael@0:       }
michael@0:     }
michael@0: 
michael@0:     // mRoot should not be cleared until after Uninit is finished so that
michael@0:     // generated content can be removed during uninitialization.
michael@0:     void UninitFalse() { Uninit(false); mRoot = nullptr; }
michael@0:     void UninitTrue() { Uninit(true); mRoot = nullptr; }
michael@0: 
michael@0:     /**
michael@0:      * Find the <template> tag that applies for this builder
michael@0:      */
michael@0:     nsresult
michael@0:     GetTemplateRoot(nsIContent** aResult);
michael@0: 
michael@0:     /**
michael@0:      * Compile the template's queries
michael@0:      */
michael@0:     nsresult
michael@0:     CompileQueries();
michael@0: 
michael@0:     /**
michael@0:      * Compile the template given a <template> in aTemplate. This function
michael@0:      * is called recursively to handle queries inside a queryset. For the
michael@0:      * outer pass, aIsQuerySet will be false, while the inner pass this will
michael@0:      * be true.
michael@0:      *
michael@0:      * aCanUseTemplate will be set to true if the template's queries could be
michael@0:      * compiled, and false otherwise. If false, the entire template is
michael@0:      * invalid.
michael@0:      *
michael@0:      * @param aTemplate <template> to compile
michael@0:      * @param aQuerySet first queryset
michael@0:      * @param aIsQuerySet true if 
michael@0:      * @param aPriority the queryset index, incremented when a new one is added
michael@0:      * @param aCanUseTemplate true if template is valid
michael@0:      */
michael@0:     nsresult
michael@0:     CompileTemplate(nsIContent* aTemplate,
michael@0:                     nsTemplateQuerySet* aQuerySet,
michael@0:                     bool aIsQuerySet,
michael@0:                     int32_t* aPriority,
michael@0:                     bool* aCanUseTemplate);
michael@0: 
michael@0:     /**
michael@0:      * Compile a query using the extended syntax. For backwards compatible RDF
michael@0:      * syntax where there is no <query>, the <conditions> becomes the query.
michael@0:      *
michael@0:      * @param aRuleElement <rule> element
michael@0:      * @param aActionElement <action> element
michael@0:      * @param aMemberVariable member variable for the query
michael@0:      * @param aQuerySet the queryset
michael@0:      */
michael@0:     nsresult 
michael@0:     CompileExtendedQuery(nsIContent* aRuleElement,
michael@0:                          nsIContent* aActionElement,
michael@0:                          nsIAtom* aMemberVariable,
michael@0:                          nsTemplateQuerySet* aQuerySet);
michael@0: 
michael@0:     /**
michael@0:      * Determine the ref variable and tag from inside a RDF query.
michael@0:      */
michael@0:     void DetermineRDFQueryRef(nsIContent* aQueryElement, nsIAtom** tag);
michael@0: 
michael@0:     /**
michael@0:      * Determine the member variable from inside an action body. It will be
michael@0:      * the value of the uri attribute on a node.
michael@0:      */
michael@0:     already_AddRefed<nsIAtom> DetermineMemberVariable(nsIContent* aElement);
michael@0: 
michael@0:     /**
michael@0:      * Compile a simple query. A simple query is one that doesn't have a
michael@0:      * <query> and should use a default query which would normally just return
michael@0:      * a list of children of the reference point.
michael@0:      *
michael@0:      * @param aRuleElement the <rule>
michael@0:      * @param aQuerySet the query set
michael@0:      * @param aCanUseTemplate true if the query is valid
michael@0:      */
michael@0:     nsresult 
michael@0:     CompileSimpleQuery(nsIContent* aRuleElement,
michael@0:                        nsTemplateQuerySet* aQuerySet,
michael@0:                        bool* aCanUseTemplate);
michael@0: 
michael@0:     /**
michael@0:      * Compile the <conditions> tag in a rule
michael@0:      *
michael@0:      * @param aRule template rule
michael@0:      * @param aConditions <conditions> element
michael@0:      */
michael@0:     nsresult
michael@0:     CompileConditions(nsTemplateRule* aRule, nsIContent* aConditions);
michael@0: 
michael@0:     /**
michael@0:      * Compile a <where> tag in a condition. The caller should set
michael@0:      * *aCurrentCondition to null for the first condition. This value will be
michael@0:      * updated to point to the new condition before returning. The conditions
michael@0:      * will be added to the rule aRule by this method.
michael@0:      *
michael@0:      * @param aRule template rule
michael@0:      * @param aCondition <where> element
michael@0:      * @param aCurrentCondition compiled condition
michael@0:      */
michael@0:     nsresult
michael@0:     CompileWhereCondition(nsTemplateRule* aRule,
michael@0:                           nsIContent* aCondition,
michael@0:                           nsTemplateCondition** aCurrentCondition);
michael@0: 
michael@0:     /**
michael@0:      * Compile the <bindings> for an extended template syntax rule.
michael@0:      */
michael@0:     nsresult
michael@0:     CompileBindings(nsTemplateRule* aRule, nsIContent* aBindings);
michael@0: 
michael@0:     /**
michael@0:      * Compile a single binding for an extended template syntax rule.
michael@0:      */
michael@0:     nsresult
michael@0:     CompileBinding(nsTemplateRule* aRule, nsIContent* aBinding);
michael@0: 
michael@0:     /**
michael@0:      * Add automatic bindings for simple rules
michael@0:      */
michael@0:     nsresult
michael@0:     AddSimpleRuleBindings(nsTemplateRule* aRule, nsIContent* aElement);
michael@0: 
michael@0:     static void
michael@0:     AddBindingsFor(nsXULTemplateBuilder* aSelf,
michael@0:                    const nsAString& aVariable,
michael@0:                    void* aClosure);
michael@0: 
michael@0:     /**
michael@0:      * Load the datasources for the template. shouldDelayBuilding is an out
michael@0:      * parameter which will be set to true to indicate that content building
michael@0:      * should not be performed yet as the datasource has not yet loaded. If
michael@0:      * false, the datasource has already loaded so building can proceed
michael@0:      * immediately. In the former case, the datasource or query processor
michael@0:      * should either rebuild the template or update results when the
michael@0:      * datasource is loaded as needed.
michael@0:      */
michael@0:     nsresult
michael@0:     LoadDataSources(nsIDocument* aDoc, bool* shouldDelayBuilding);
michael@0: 
michael@0:     /**
michael@0:      * Called by LoadDataSources to load a datasource given a uri list
michael@0:      * in aDataSource. The list is a set of uris separated by spaces.
michael@0:      * If aIsRDFQuery is true, then this is for an RDF datasource which
michael@0:      * causes the method to check for additional flags specific to the
michael@0:      * RDF processor.
michael@0:      */
michael@0:     nsresult
michael@0:     LoadDataSourceUrls(nsIDocument* aDocument,
michael@0:                        const nsAString& aDataSources,
michael@0:                        bool aIsRDFQuery,
michael@0:                        bool* aShouldDelayBuilding);
michael@0: 
michael@0:     nsresult
michael@0:     InitHTMLTemplateRoot();
michael@0: 
michael@0:     /**
michael@0:      * Determine which rule matches a given result. aContainer is used for
michael@0:      * tag matching and is optional for non-content generating builders.
michael@0:      * The returned matched rule is always one of the rules owned by the
michael@0:      * query set aQuerySet.
michael@0:      *
michael@0:      * @param aContainer parent where generated content will be inserted
michael@0:      * @param aResult result to match
michael@0:      * @param aQuerySet query set to examine the rules of
michael@0:      * @param aMatchedRule [out] rule that has matched, or null if any.
michael@0:      * @param aRuleIndex [out] index of the rule
michael@0:      */
michael@0:     nsresult
michael@0:     DetermineMatchedRule(nsIContent* aContainer,
michael@0:                          nsIXULTemplateResult* aResult,
michael@0:                          nsTemplateQuerySet* aQuerySet,
michael@0:                          nsTemplateRule** aMatchedRule,
michael@0:                          int16_t *aRuleIndex);
michael@0: 
michael@0:     // XXX sigh, the string template foo doesn't mix with
michael@0:     // operator->*() on egcs-1.1.2, so we'll need to explicitly pass
michael@0:     // "this" and use good ol' fashioned static callbacks.
michael@0:     void
michael@0:     ParseAttribute(const nsAString& aAttributeValue,
michael@0:                    void (*aVariableCallback)(nsXULTemplateBuilder* aThis, const nsAString&, void*),
michael@0:                    void (*aTextCallback)(nsXULTemplateBuilder* aThis, const nsAString&, void*),
michael@0:                    void* aClosure);
michael@0: 
michael@0:     nsresult
michael@0:     SubstituteText(nsIXULTemplateResult* aMatch,
michael@0:                    const nsAString& aAttributeValue,
michael@0:                    nsAString& aResult);
michael@0: 
michael@0:     static void
michael@0:     SubstituteTextAppendText(nsXULTemplateBuilder* aThis, const nsAString& aText, void* aClosure);
michael@0: 
michael@0:     static void
michael@0:     SubstituteTextReplaceVariable(nsXULTemplateBuilder* aThis, const nsAString& aVariable, void* aClosure);    
michael@0: 
michael@0:     nsresult 
michael@0:     IsSystemPrincipal(nsIPrincipal *principal, bool *result);
michael@0: 
michael@0:     /**
michael@0:      * Convenience method which gets a resource for a result. If a result
michael@0:      * doesn't have a resource set, it will create one from the result's id.
michael@0:      */
michael@0:     nsresult GetResultResource(nsIXULTemplateResult* aResult,
michael@0:                                nsIRDFResource** aResource);
michael@0: 
michael@0: protected:
michael@0:     nsCOMPtr<nsISupports> mDataSource;
michael@0:     nsCOMPtr<nsIRDFDataSource> mDB;
michael@0:     nsCOMPtr<nsIRDFCompositeDataSource> mCompDB;
michael@0: 
michael@0:     /**
michael@0:      * Circular reference, broken when the document is destroyed.
michael@0:      */
michael@0:     nsCOMPtr<nsIContent> mRoot;
michael@0: 
michael@0:     /**
michael@0:      * The root result, translated from the root element's ref
michael@0:      */
michael@0:     nsCOMPtr<nsIXULTemplateResult> mRootResult;
michael@0: 
michael@0:     nsCOMArray<nsIXULBuilderListener> mListeners;
michael@0: 
michael@0:     /**
michael@0:      * The query processor which generates results
michael@0:      */
michael@0:     nsCOMPtr<nsIXULTemplateQueryProcessor> mQueryProcessor;
michael@0: 
michael@0:     /**
michael@0:      * The list of querysets
michael@0:      */
michael@0:     nsTArray<nsTemplateQuerySet *> mQuerySets;
michael@0: 
michael@0:     /**
michael@0:      * Set to true if the rules have already been compiled
michael@0:      */
michael@0:     bool          mQueriesCompiled;
michael@0: 
michael@0:     /**
michael@0:      * The default reference and member variables.
michael@0:      */
michael@0:     nsCOMPtr<nsIAtom> mRefVariable;
michael@0:     nsCOMPtr<nsIAtom> mMemberVariable;
michael@0: 
michael@0:     /**
michael@0:      * The match map contains nsTemplateMatch objects, one for each unique
michael@0:      * match found, keyed by the resource for that match. A particular match
michael@0:      * will contain a linked list of all of the matches for that unique result
michael@0:      * id. Only one is active at a time. When a match is retracted, look in
michael@0:      * the match map, remove it, and apply the next valid match in sequence to
michael@0:      * make active.
michael@0:      */
michael@0:     nsDataHashtable<nsISupportsHashKey, nsTemplateMatch*> mMatchMap;
michael@0: 
michael@0:     // pseudo-constants
michael@0:     static nsrefcnt gRefCnt;
michael@0:     static nsIRDFService*            gRDFService;
michael@0:     static nsIRDFContainerUtils*     gRDFContainerUtils;
michael@0:     static nsIScriptSecurityManager* gScriptSecurityManager;
michael@0:     static nsIPrincipal*             gSystemPrincipal;
michael@0:     static nsIObserverService*       gObserverService;
michael@0: 
michael@0:     enum {
michael@0:         eDontTestEmpty = (1 << 0),
michael@0:         eDontRecurse = (1 << 1),
michael@0:         eLoggingEnabled = (1 << 2)
michael@0:     };
michael@0: 
michael@0:     int32_t mFlags;
michael@0: 
michael@0:     /**
michael@0:      * Stack-based helper class to maintain a list of ``activated''
michael@0:      * resources; i.e., resources for which we are currently building
michael@0:      * content.
michael@0:      */
michael@0:     class ActivationEntry {
michael@0:     public:
michael@0:         nsIRDFResource   *mResource;
michael@0:         ActivationEntry  *mPrevious;
michael@0:         ActivationEntry **mLink;
michael@0: 
michael@0:         ActivationEntry(nsIRDFResource *aResource, ActivationEntry **aLink)
michael@0:             : mResource(aResource),
michael@0:               mPrevious(*aLink),
michael@0:               mLink(aLink) { *mLink = this; }
michael@0: 
michael@0:         ~ActivationEntry() { *mLink = mPrevious; }
michael@0:     };
michael@0: 
michael@0:     /**
michael@0:      * The top of the stack of resources that we're currently building
michael@0:      * content for.
michael@0:      */
michael@0:     ActivationEntry *mTop;
michael@0: 
michael@0:     /**
michael@0:      * Determine if a resource is currently on the activation stack.
michael@0:      */
michael@0:     bool
michael@0:     IsActivated(nsIRDFResource *aResource);
michael@0: 
michael@0:     /**
michael@0:      * Returns true if content may be generated for a result, or false if it
michael@0:      * cannot, for example, if it would be created inside a closed container.
michael@0:      * Those results will be generated when the container is opened.
michael@0:      * If false is returned, no content should be generated. Possible 
michael@0:      * insertion locations may optionally be set for new content, depending on
michael@0:      * the builder being used. Note that *aLocations or some items within
michael@0:      * aLocations may be null.
michael@0:      */
michael@0:     virtual bool
michael@0:     GetInsertionLocations(nsIXULTemplateResult* aResult,
michael@0:                           nsCOMArray<nsIContent>** aLocations) = 0;
michael@0: 
michael@0:     /**
michael@0:      * Must be implemented by subclasses. Handle removing the generated
michael@0:      * output for aOldMatch and adding new output for aNewMatch. Either
michael@0:      * aOldMatch or aNewMatch may be null. aContext is the location returned
michael@0:      * from the call to MayGenerateResult.
michael@0:      */
michael@0:     virtual nsresult
michael@0:     ReplaceMatch(nsIXULTemplateResult* aOldResult,
michael@0:                  nsTemplateMatch* aNewMatch,
michael@0:                  nsTemplateRule* aNewMatchRule,
michael@0:                  void *aContext) = 0;
michael@0: 
michael@0:     /**
michael@0:      * Must be implemented by subclasses. Handle change in bound
michael@0:      * variable values for aResult. aModifiedVars contains the set
michael@0:      * of variables that have changed.
michael@0:      * @param aResult the ersult for which variable bindings has changed.
michael@0:      * @param aModifiedVars the set of variables for which the bindings
michael@0:      * have changed.
michael@0:      */
michael@0:     virtual nsresult
michael@0:     SynchronizeResult(nsIXULTemplateResult* aResult) = 0;
michael@0: 
michael@0:     /**
michael@0:      * Output a new match or removed match to the console.
michael@0:      *
michael@0:      * @param aId id of the result
michael@0:      * @param aMatch new or removed match
michael@0:      * @param aIsNew true for new matched, false for removed matches
michael@0:      */
michael@0:     void
michael@0:     OutputMatchToLog(nsIRDFResource* aId,
michael@0:                      nsTemplateMatch* aMatch,
michael@0:                      bool aIsNew);
michael@0: 
michael@0:     virtual void Traverse(nsCycleCollectionTraversalCallback &cb) const
michael@0:     {
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Start observing events from the observer service and the given
michael@0:      * document.
michael@0:      *
michael@0:      * @param aDocument the document to observe
michael@0:      */
michael@0:     void StartObserving(nsIDocument* aDocument);
michael@0: 
michael@0:     /**
michael@0:      * Stop observing events from the observer service and any associated
michael@0:      * document.
michael@0:      */
michael@0:     void StopObserving();
michael@0: 
michael@0:     /**
michael@0:      * Document that we're observing. Weak ref!
michael@0:      */
michael@0:     nsIDocument* mObservedDocument;
michael@0: };
michael@0: 
michael@0: #endif // nsXULTemplateBuilder_h__