001// Copyright 2023 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.
014package org.apache.tapestry5.services.pageload;
015
016import java.util.Set;
017import java.util.function.Function;
018
019import org.apache.tapestry5.commons.services.PlasticProxyFactory;
020import org.apache.tapestry5.internal.services.ComponentInstantiatorSource;
021
022/**
023 * Service that creates {@linkplain PageClassLoaderContext} instances (except the root one)
024 * when a class in a controlled page is first used in the Tapestry page pool. Existing 
025 * contexts may be reused for a given class, specially when in production mode.
026 * 
027 * @see ComponentInstantiatorSource
028 * @since 5.8.3
029 */
030public interface PageClassLoaderContextManager 
031{
032
033    /**
034     * Processes a class, given its class name and the root context.
035     * @param className the class fully qualified name.
036     * {@linkplain} ClassLoader} and returns a new {@linkplain PlasticProxyFactory}.
037     * @return the {@link PageClassLoaderContext} associated with that class.
038     */
039    PageClassLoaderContext get(String className);
040    
041    /**
042     * Invalidates page classloader contexts and returns a set containing the names
043     * of all classes that should be invalidated.
044     */
045    Set<String> invalidate(PageClassLoaderContext... contexts);
046    
047    /**
048     * Invalidates page classloader contexts and invalidates the classes in the context as well.
049     */
050    void invalidateAndFireInvalidationEvents(PageClassLoaderContext... contexts);
051    
052    /**
053     * Returns the root context.
054     */
055    PageClassLoaderContext getRoot();
056    
057    /**
058     * Clears any state held by this manager.
059     */
060    void clear();
061    
062    /**
063     * Returns whether contexts are being merged.
064     */
065    boolean isMerging();
066
067    /**
068     * Removes one specific class from this manager, invalidating the context where
069     * it is.
070     */
071    void clear(String className);
072
073    /**
074     * Initializes this service with the root context and a Plastic proxy factory provider.
075     * Method can only be called once. None of the parameters may be null.
076     */
077    void initialize(PageClassLoaderContext root, Function<ClassLoader, PlasticProxyFactory> plasticProxyFactoryProvider);
078    
079    /**
080     * Returns the Class instance appropriate for a given component given a page name.
081     * @param clasz the class instance.
082     * @param pageName the page name.
083     * @return a Class instance.
084     */
085    Class<?> getClassInstance(Class<?> clasz, String pageName);
086
087    /**
088     * Invalidates the "unknown" page classloader context context.
089     */
090    void invalidateUnknownContext();
091    
092    /**
093     * Preloads all data, first by collecting dependency data for all existing pages
094     * and the components, mixins and superclasses they use, then creating the
095     * page classloader contexts.
096     */
097    void preload();
098
099}