    001/*
    002    Licensed to the Apache Software Foundation (ASF) under one
    003    or more contributor license agreements.  See the NOTICE file
    004    distributed with this work for additional information
    005    regarding copyright ownership.  The ASF licenses this file
    006    to you under the Apache License, Version 2.0 (the
    007    "License"); you may not use this file except in compliance
    008    with the License.  You may obtain a copy of the License at
    009
    010       http://www.apache.org/licenses/LICENSE-2.0
    011
    012    Unless required by applicable law or agreed to in writing,
    013    software distributed under the License is distributed on an
    014    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    015    KIND, either express or implied.  See the License for the
    016    specific language governing permissions and limitations
    017    under the License.
    018 */
    019package org.apache.wiki.api.engine;
    020
    021import org.apache.wiki.api.core.Engine;
    022
    023import java.util.Properties;
    024
    025/**
    026 * <p>SPI used to notify JSPWiki extensions about {@link Engine}'s initialization & shutdown, without having to deep
    027 * dive on {@link Engine}'s internals.</p>
    028 *
    029 * <p>Examples of {@code EngineLifecycleExtension}'s use cases:
    030 * <ul>
    031 *   <li>Appending a plugin's classpath to {@code jspwiki.plugin.searchPath}, so it can be used as a drop-in, without further configuration.</li>
    032 *   <li>Providing default parameters for a custom extension.</li>
    033 *   <li>Setting up that expensive singleton, or disposing resources, without having to use or register a {@link org.apache.wiki.event.WikiEventListener WikiEventListener}.</li>
    034 * </ul>
    035 * </p>
    036 *
    037 * <p>As a concrete example, the markdown module uses an {@code EngineLifecycleExtension} to set up all the required properties
    038 * if {@code jspwiki.syntax=markdown} is provided on the {@code jspwiki[-custom].properties file}.</p>
    039 *
    040 * <p>All methods are provided with a {@code default}, do-nothing implementation, so specific EngineLifecycleExtensions only have
    041 * to provide implementations for the methods they're really interested in.</p>
    042 */
    043public interface EngineLifecycleExtension {
    044
    045    /**
    046     * Called before {@link Engine} initialization, after the wiki properties have been sought out.
    047     *
    048     * @param properties wiki configuration properties.
    049     */
    050    default void onInit( final Properties properties ) {}
    051
    052    /**
    053     * Called after {@link Engine} initialization.
    054     *
    055     * @param properties wiki configuration properties.
    056     * @param e JSPWiki's ready to be used {@link Engine}.
    057     */
    058    default void onStart( final Engine e, final Properties properties ) {}
    059
    060    /**
    061     * Called before {@link Engine} shutdown.
    062     * @param e JSPWiki's running {@link Engine}.
    063     * @param properties wiki configuration properties.
    064     */
    065    default void onShutdown( final Engine e, final Properties properties ) {}
    066
    067}