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;
017
018import java.util.concurrent.CompletableFuture;
019
020/**
021 * Asynchronous two-phase application launcher. This interface is <b>currently unused for JavaFX applications</b>.
022 * It is logically-compatible with {@code FxLauncher} which in earlier versions of Supernaut.FX was a subclass.
023 * <p>
024 * It uses threads to start a background app as quickly as possible and
025 * possibly before the foreground app is started. This background app can make network
026 * requests while the foreground app is starting up, so that views in
027 * the foreground app can be updated with live data as soon as possible.
028 */
029public interface Launcher {
030    /**
031     * Launch and run the application on the current thread.
032     * Does not return until after foreground app closes.
033     * @param args command-line args
034     * @param foregroundApp class object for ForegroundApp
035     * @param backgroundApp class object for BackgroundApp
036     */
037    void launch(String[] args, Class<? extends ForegroundApp> foregroundApp, Class<? extends BackgroundApp> backgroundApp);
038
039    /**
040     * Launch and run the application on the current thread. Uses default/no-op background application.
041     * Does not return until after foreground app closes.
042     * @param args command-line args
043     * @param foregroundApp class object for ForegroundApp
044     */
045    void launch(String[] args, Class<? extends ForegroundApp> foregroundApp);
046
047    /**
048     * Launch and run the application on a newly created thread.
049     * This method is useful for testing and possibly for other
050     * application startup scenarios.
051     *
052     * @param args command-line args
053     * @param foregroundApp class object for ForegroundApp
054     * @param backgroundApp class object for BackgroundApp
055     * @return A future that is completed when Foreground app is initialized
056     */
057    CompletableFuture<ForegroundApp> launchAsync(String[] args, Class<? extends ForegroundApp> foregroundApp, Class<? extends BackgroundApp> backgroundApp);
058
059    /**
060     * Get a future that will be completed when the Foreground app
061     * is initialized.
062     *
063     * @return A future that is completed when Foreground app is initialized
064     */
065    CompletableFuture<ForegroundApp> getForegroundApp();
066
067    /**
068     * Get a future that will be completed when the Background app
069     * is initialized.
070     *
071     * @return A future that is completed when Background app is initialized
072     */
073    CompletableFuture<BackgroundApp> getBackgroundApp();
074}