001/*
002 * Copyright 2019-2021 M. Sean Gilligan.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package app.supernaut.fx;
017
018import javafx.application.Application;
019import javafx.stage.Stage;
020
021/**
022 * Interface for delegated JavaFX applications.
023 * <b>Supernaut.FX</b> applications implement this interface.
024 * <p>
025 * Supernaut.FX applications <i>implement</i> this interface instead of subclassing <b>JavaFX</b> {@link Application}. This has several
026 * advantages over directly extending {@link javafx.application.Application}:
027 * <ol>
028 *     <li>
029 *         Supports flexible construction of application object hierarchies using Dependency Injection provided
030 *         by <b>Micronaut</b> framework and possibly other D.I. frameworks in the future.
031 *     </li>
032 *     <li>
033 *       Applications {@code implement} an {@code interface} rather than {@code extend} a {@code class}.
034 *       This increases the testability and architectural flexibility of the application.
035 *     </li>
036 *     <li>
037 *         Supports faster, multi-threaded launching with the {@link FxLauncher} interface.
038 *     </li>
039 * </ol>
040 */
041public interface ApplicationDelegate {
042
043    /**
044     * Pass the JavaFX {@link Application} to the delegate. Override this method if your application
045     * needs access to {@link javafx.application.HostServices} or other functionality available through
046     * the {@code Application} object.
047     * <p>
048     * NOTE: This method will be called on the same thread as the JavaFX {@link Application}
049     * constructor.
050     *
051     * @param application A reference to the delegating JavaFX {@link Application} instance
052     */
053    default void setApplication(Application application) {}
054
055    /**
056     * The application initialization method. This method is called from the JavaFX
057     * {@link Application#init()} method after the dependency injection context is initialized and the
058     * application is constructed and dependency injected.
059     *
060     * <p>
061     * NOTE: This method is not called on the JavaFX Application Thread. An
062     * application must not construct a Scene or a Stage in this
063     * method.
064     * An application may construct other JavaFX objects in this method.
065     *
066     * @throws java.lang.Exception if something goes wrong
067     */
068    default void init() throws Exception {}
069
070    /**
071     * The main entry point for Supernaut.fx applications. Called from {@link Application#start(Stage)}.
072     * At a minimum, you must implement this method.
073     * <p>
074     * NOTE: This method is called on the JavaFX Application Thread.
075     *
076     * @param primaryStage the primary stage
077     * @throws Exception something went wrong
078     */
079    void start(Stage primaryStage) throws Exception;
080
081    /**
082     * This method is called when the application should stop, and provides a
083     * convenient place to prepare for application exit and destroy resources.
084     * Called from {@link Application#stop()}
085     * <p>
086     * NOTE: This method is called on the JavaFX Application Thread.
087     *
088     * @throws java.lang.Exception if something goes wrong
089     */
090    default void stop() throws Exception {}
091}