001// Copyright 2022 The Apache Software Foundation
002//
003// Licensed under the Apache License, Version 2.0 (the "License");
004// you may not use this file except in compliance with the License.
005// You may obtain a copy of the License at
006//
007//     http://www.apache.org/licenses/LICENSE-2.0
008//
009// Unless required by applicable law or agreed to in writing, software
010// distributed under the License is distributed on an "AS IS" BASIS,
011// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012// See the License for the specific language governing permissions and
013// limitations under the License.
014
015package org.apache.tapestry5.internal.services;
016
017import java.util.Set;
018
019import org.apache.tapestry5.annotations.Component;
020import org.apache.tapestry5.annotations.InjectComponent;
021import org.apache.tapestry5.annotations.InjectPage;
022import org.apache.tapestry5.commons.services.InvalidationEventHub;
023import org.apache.tapestry5.internal.structure.ComponentPageElement;
024import org.apache.tapestry5.model.MutableComponentModel;
025import org.apache.tapestry5.plastic.PlasticField;
026
027
028/**
029 * Internal service that registers direct dependencies between components (including components, pages and
030 * base classes). Even though methods receive {@link ComponentPageElement} parameters, dependencies
031 * are tracked using their fully qualified classs names.
032 *
033 * @since 5.8.3
034 */
035public interface ComponentDependencyRegistry {
036
037    /**
038     * Enum class defining the types of dependency components, pages and mixins can
039     * have among them.
040     */
041    public static enum DependencyType
042    {
043        
044        /**
045         * Simple usage of components and mixins in components and pages
046         */
047        USAGE,
048        
049        /**
050         * Superclass/subclass dependency.
051         */
052        SUPERCLASS,
053        
054        /**
055         * Dependency by usage of the {@linkplain InjectPage} annotation.
056         */
057        INJECT_PAGE;
058    }
059
060    /**
061     * Default file where the dependency information is stored between webapp runs.
062     */
063    String FILENAME = "tapestryComponentDependencies.json";
064
065    /**
066     * Register all the dependencies of a given class.
067     */
068    void register(Class<?> clasz);
069
070    /**
071     * Register all the dependencies of a given class and uses a given
072     * classloader to load other classes if needed.
073     * @since 5.8.7
074     */
075    void register(Class<?> clasz, ClassLoader classLoader);
076
077    /**
078     * Register all the dependencies of a given component.
079     */
080    void register(ComponentPageElement componentPageElement);
081    
082    /**
083     * Register a dependency of a component class with another through annotations
084     * such as {@link InjectPage}, {@link InjectComponent} and {@link Component}.
085     */
086    void register(PlasticField plasticField, MutableComponentModel componentModel);
087    
088    /**
089     * Clears all dependency information for a given component.
090     */
091    void clear(String className);
092    
093    /**
094     * Clears all dependency information for a given component.
095     */
096    void clear(ComponentPageElement componentPageElement);
097    
098    /**
099     * Clears all dependency information.
100     */
101    void clear();
102
103    /**
104     * Returns the fully qualified names of the direct dependencies of a given component.
105     */
106    Set<String> getDependents(String className);
107    
108    /**
109     * Returns the fully qualified names of the direct dependencies of a given component
110     * and a given dependency type.
111     * @see DependencyType
112     */
113    Set<String> getDependencies(String className, DependencyType type);
114    
115    /**
116     * Returns all dependencies of a given class, direct and indirect.
117     * @param className a class name.
118     */
119    Set<String> getAllNonPageDependencies(String className);
120    
121    /**
122     * Signs up this registry to invalidation events from a given hub.
123     */
124    void listen(InvalidationEventHub invalidationEventHub);
125
126    /**
127     * Writes the current component dependency data to a file so it can be reused in a new run later.
128     * @see #FILENAME
129     */
130    void writeFile();
131    
132    /**
133     * Tells whether this registry already contans a given class name.
134     */
135    boolean contains(String className);
136    
137    /**
138     * Returns the set of all class names in the registry.
139     */
140    Set<String> getClassNames();
141    
142    /**
143     * Returns the set of all root classes (i.e. ones with no dependencies).
144     */
145    Set<String> getRootClasses();
146    
147    /**
148     * Returns whether stored dependency information is present.
149     */
150    boolean isStoredDependencyInformationPresent();
151    
152    /**
153     * Tells this service to ignore invalidations in this thread.
154     */
155    void disableInvalidations();
156    
157    /**
158     * Tells this service to stop ignoring invalidations in this thread.
159     */
160    void enableInvalidations();
161
162}