< prev index next >

modules/javafx.graphics/src/main/java/javafx/application/Application.java

Print this page
rev 10404 : 8178015: Clarify requirement for app modules to export/open packages to javafx modules
Reviewed-by:


   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javafx.application;
  27 
  28 import java.security.AccessController;
  29 import java.security.PrivilegedAction;
  30 import java.util.List;
  31 import java.util.Map;
  32 
  33 import javafx.application.Preloader.PreloaderNotification;
  34 import javafx.scene.Scene;
  35 import javafx.stage.Stage;
  36 
  37 import com.sun.javafx.application.LauncherImpl;
  38 import com.sun.javafx.application.ParametersImpl;
  39 import com.sun.javafx.application.PlatformImpl;
  40 import com.sun.javafx.css.StyleManager;
  41 
  42 /**
  43  * Application class from which JavaFX applications extend.
  44  *
  45  * <p><b>Life-cycle</b></p>
  46  * <p>
  47  * The entry point for JavaFX applications is the Application class. The
  48  * JavaFX runtime does the following, in order, whenever an application is
  49  * launched:
  50  * </p>
  51  * <ol>
  52  * <li>Starts the JavaFX runtime, if not already started
  53  * (see {@link Platform#startup(Runnable)} for more information)</li>
  54  * <li>Constructs an instance of the specified Application class</li>
  55  * <li>Calls the {@link #init} method</li>
  56  * <li>Calls the {@link #start} method</li>
  57  * <li>Waits for the application to finish, which happens when either of
  58  * the following occur:
  59  * <ul>
  60  * <li>the application calls {@link Platform#exit}</li>
  61  * <li>the last window has been closed and the {@code implicitExit}
  62  * attribute on {@code Platform} is true</li>
  63  * </ul></li>
  64  * <li>Calls the {@link #stop} method</li>
  65  * </ol>
  66  * <p>Note that the {@code start} method is abstract and must be overridden.
  67  * The {@code init} and {@code stop} methods have concrete implementations
  68  * that do nothing.</p>
  69  * <p>The {@code Application} subclass must be declared public, must have a
  70  * public no-argument constructor, and the
  71  * containing package must be exported (see {@code Module.isExported(String,Module)})
  72  * to the {@code javafx.graphics} module.</p>
  73  *
  74  * <p>Calling {@link Platform#exit} is the preferred way to explicitly terminate
  75  * a JavaFX Application. Directly calling {@link System#exit} is
  76  * an acceptable alternative, but doesn't allow the Application {@link #stop}
  77  * method to run.
  78  * </p>
  79  *
  80  * <p>A JavaFX Application should not attempt to use JavaFX after the
  81  * FX toolkit has terminated or from a ShutdownHook, that is, after the
  82  * {@link #stop} method returns or {@link System#exit} is called.
  83  * </p>
  84  *


















  85  * <p><b>Parameters</b></p>
  86  * <p>
  87  * Application parameters are available by calling the {@link #getParameters}
  88  * method from the {@link #init} method, or any time after the {@code init}
  89  * method has been called.
  90  * </p>
  91  *
  92  * <p><b>Threading</b></p>
  93  * <p>
  94  * JavaFX creates an application thread for running the application start
  95  * method, processing input events, and running animation timelines. Creation
  96  * of JavaFX {@link Scene} and {@link Stage} objects as well as modification of
  97  * scene graph operations to <em>live</em> objects (those objects already
  98  * attached to a scene) must be done on the JavaFX application thread.
  99  * </p>
 100  *
 101  * <p>
 102  * The Java launcher loads and initializes the specified Application class
 103  * on the JavaFX Application Thread. If there is no main method in the
 104  * Application class, or if the main method calls Application.launch(), then


 194      * @throws IllegalStateException if this method is called more than once.
 195      * @throws IllegalArgumentException if <code>appClass</code> is not a
 196      *         subclass of <code>Application</code>.
 197      * @throws RuntimeException if there is an error launching the
 198      * JavaFX runtime, or if the application class cannot be constructed
 199      * (e.g., if the class is not public or is not in an exported package), or
 200      * if an Exception or Error is thrown by the Application constructor, init
 201      * method, start method, or stop method.
 202      */
 203     public static void launch(Class<? extends Application> appClass, String... args) {
 204         LauncherImpl.launchApplication(appClass, args);
 205     }
 206 
 207     /**
 208      * Launch a standalone application. This method is typically called
 209      * from the main method(). It must not be called more than once or an
 210      * exception will be thrown.
 211      * This is equivalent to launch(TheClass.class, args) where TheClass is the
 212      * immediately enclosing class of the method that called launch. It must
 213      * be a public subclass of Application with a public no-argument
 214      * constructor, in a package that is exported
 215      * (see {@code Module.isExported(String,Module)}) to at least the

 216      * {@code javafx.graphics} module, or a RuntimeException will be thrown.
 217      *
 218      * <p>
 219      * The launch method does not return until the application has exited,
 220      * either via a call to Platform.exit or all of the application windows
 221      * have been closed.
 222      *
 223      * <p>
 224      * Typical usage is:
 225      * <pre>
 226      *     public static void main(String[] args) {
 227      *         Application.launch(args);
 228      *     }
 229      * </pre>
 230      *
 231      * @param args the command line arguments passed to the application.
 232      *             An application may get these parameters using the
 233      *             {@link #getParameters()} method.
 234      *
 235      * @throws IllegalStateException if this method is called more than once.




   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javafx.application;
  27 
  28 import java.lang.module.ModuleDescriptor;

  29 import java.util.List;
  30 import java.util.Map;
  31 
  32 import javafx.application.Preloader.PreloaderNotification;
  33 import javafx.scene.Scene;
  34 import javafx.stage.Stage;
  35 
  36 import com.sun.javafx.application.LauncherImpl;
  37 import com.sun.javafx.application.ParametersImpl;
  38 import com.sun.javafx.application.PlatformImpl;
  39 import com.sun.javafx.css.StyleManager;
  40 
  41 /**
  42  * Application class from which JavaFX applications extend.
  43  *
  44  * <p><b>Life-cycle</b></p>
  45  * <p>
  46  * The entry point for JavaFX applications is the Application class. The
  47  * JavaFX runtime does the following, in order, whenever an application is
  48  * launched:
  49  * </p>
  50  * <ol>
  51  * <li>Starts the JavaFX runtime, if not already started
  52  * (see {@link Platform#startup(Runnable)} for more information)</li>
  53  * <li>Constructs an instance of the specified Application class</li>
  54  * <li>Calls the {@link #init} method</li>
  55  * <li>Calls the {@link #start} method</li>
  56  * <li>Waits for the application to finish, which happens when either of
  57  * the following occur:
  58  * <ul>
  59  * <li>the application calls {@link Platform#exit}</li>
  60  * <li>the last window has been closed and the {@code implicitExit}
  61  * attribute on {@code Platform} is true</li>
  62  * </ul></li>
  63  * <li>Calls the {@link #stop} method</li>
  64  * </ol>
  65  * <p>Note that the {@code start} method is abstract and must be overridden.
  66  * The {@code init} and {@code stop} methods have concrete implementations
  67  * that do nothing.</p>
  68  * <p>The {@code Application} subclass must be declared public and must have a
  69  * public no-argument constructor.</p>


  70  *
  71  * <p>Calling {@link Platform#exit} is the preferred way to explicitly terminate
  72  * a JavaFX Application. Directly calling {@link System#exit} is
  73  * an acceptable alternative, but doesn't allow the Application {@link #stop}
  74  * method to run.
  75  * </p>
  76  *
  77  * <p>A JavaFX Application should not attempt to use JavaFX after the
  78  * FX toolkit has terminated or from a ShutdownHook, that is, after the
  79  * {@link #stop} method returns or {@link System#exit} is called.
  80  * </p>
  81  *
  82  * <p><b>Applications in a Module</b></p>
  83  * <p>
  84  * If the {@code Application} subclass is in a named module then that class
  85  * must be accessible by the {@code javafx.graphics} module. This means that
  86  * in addition to the class itself being public, the module must
  87  * {@link Module#isExported(String,Module) export} the containing package to
  88  * at least the {@code javafx.graphics} module, either in its
  89  * {@link ModuleDescriptor} (e.g., in its module-info.class) or by calling
  90  * {@link Module#addExports}. Alternatively, the module can
  91  * {@link Module#isOpen(String,Module) open} the containing package to the
  92  * {@code javafx.graphics} module.
  93  * </p>
  94  * <p>
  95  * If the class is not accessible by
  96  * the {@code javafx.graphics} module, then an exception will be thrown when
  97  * the application is launched.
  98  * </p>
  99  *
 100  * <p><b>Parameters</b></p>
 101  * <p>
 102  * Application parameters are available by calling the {@link #getParameters}
 103  * method from the {@link #init} method, or any time after the {@code init}
 104  * method has been called.
 105  * </p>
 106  *
 107  * <p><b>Threading</b></p>
 108  * <p>
 109  * JavaFX creates an application thread for running the application start
 110  * method, processing input events, and running animation timelines. Creation
 111  * of JavaFX {@link Scene} and {@link Stage} objects as well as modification of
 112  * scene graph operations to <em>live</em> objects (those objects already
 113  * attached to a scene) must be done on the JavaFX application thread.
 114  * </p>
 115  *
 116  * <p>
 117  * The Java launcher loads and initializes the specified Application class
 118  * on the JavaFX Application Thread. If there is no main method in the
 119  * Application class, or if the main method calls Application.launch(), then


 209      * @throws IllegalStateException if this method is called more than once.
 210      * @throws IllegalArgumentException if <code>appClass</code> is not a
 211      *         subclass of <code>Application</code>.
 212      * @throws RuntimeException if there is an error launching the
 213      * JavaFX runtime, or if the application class cannot be constructed
 214      * (e.g., if the class is not public or is not in an exported package), or
 215      * if an Exception or Error is thrown by the Application constructor, init
 216      * method, start method, or stop method.
 217      */
 218     public static void launch(Class<? extends Application> appClass, String... args) {
 219         LauncherImpl.launchApplication(appClass, args);
 220     }
 221 
 222     /**
 223      * Launch a standalone application. This method is typically called
 224      * from the main method(). It must not be called more than once or an
 225      * exception will be thrown.
 226      * This is equivalent to launch(TheClass.class, args) where TheClass is the
 227      * immediately enclosing class of the method that called launch. It must
 228      * be a public subclass of Application with a public no-argument
 229      * constructor, in a package that is
 230      * {@link Module#isExported(String,Module) exported}
 231      * (or {@link Module#isOpen(String,Module) opened}) to at least the
 232      * {@code javafx.graphics} module, or a RuntimeException will be thrown.
 233      *
 234      * <p>
 235      * The launch method does not return until the application has exited,
 236      * either via a call to Platform.exit or all of the application windows
 237      * have been closed.
 238      *
 239      * <p>
 240      * Typical usage is:
 241      * <pre>
 242      *     public static void main(String[] args) {
 243      *         Application.launch(args);
 244      *     }
 245      * </pre>
 246      *
 247      * @param args the command line arguments passed to the application.
 248      *             An application may get these parameters using the
 249      *             {@link #getParameters()} method.
 250      *
 251      * @throws IllegalStateException if this method is called more than once.


< prev index next >