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}