    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    /**
    100     * Preloads the page classloader contexts.
    101     * @since 5.8.7
    102     */
    103    void preloadContexts();
    104
    105}