< prev index next >

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

Print this page
rev 10358 : 8170702: Document that javafx.graphics needs explicit access to application main class
Reviewed-by:
   1 /*
   2  * Copyright (c) 2010, 2015, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   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>Constructs an instance of the specified Application class</li>
  53  * <li>Calls the {@link #init} method</li>
  54  * <li>Calls the {@link #start} method</li>
  55  * <li>Waits for the application to finish, which happens when either of
  56  * the following occur:
  57  * <ul>
  58  * <li>the application calls {@link Platform#exit}</li>
  59  * <li>the last window has been closed and the {@code implicitExit}
  60  * attribute on {@code Platform} is true</li>
  61  * </ul></li>
  62  * <li>Calls the {@link #stop} method</li>
  63  * </ol>
  64  * <p>Note that the {@code start} method is abstract and must be overridden.
  65  * The {@code init} and {@code stop} methods have concrete implementations
  66  * that do nothing.</p>



  67  *
  68  * <p>Calling {@link Platform#exit} is the preferred way to explicitly terminate
  69  * a JavaFX Application. Directly calling {@link System#exit} is
  70  * an acceptable alternative, but doesn't allow the Application {@link #stop}
  71  * method to run.
  72  * </p>
  73  *
  74  * <p>A JavaFX Application should not attempt to use JavaFX after the
  75  * FX toolkit has terminated or from a ShutdownHook, that is, after the
  76  * {@link #stop} method returns or {@link System#exit} is called.
  77  * </p>
  78  *
  79  * <p><b>Parameters</b></p>
  80  * <p>
  81  * Application parameters are available by calling the {@link #getParameters}
  82  * method from the {@link #init} method, or any time after the {@code init}
  83  * method has been called.
  84  * </p>
  85  *
  86  * <p><b>Threading</b></p>


 169      * <p>
 170      * Typical usage is:
 171      * <ul>
 172      * <pre>
 173      * public static void main(String[] args) {
 174      *     Application.launch(MyApp.class, args);
 175      * }
 176      * </pre>
 177      * </ul>
 178      * where <code>MyApp</code> is a subclass of Application.
 179      *
 180      * @param appClass the application class that is constructed and executed
 181      *        by the launcher.
 182      * @param args the command line arguments passed to the application.
 183      *             An application may get these parameters using the
 184      *             {@link #getParameters()} method.
 185      *
 186      * @throws IllegalStateException if this method is called more than once.
 187      * @throws IllegalArgumentException if <code>appClass</code> is not a
 188      *         subclass of <code>Application</code>.





 189      */
 190     public static void launch(Class<? extends Application> appClass, String... args) {
 191         LauncherImpl.launchApplication(appClass, args);
 192     }
 193 
 194     /**
 195      * Launch a standalone application. This method is typically called
 196      * from the main method(). It must not be called more than once or an
 197      * exception will be thrown.
 198      * This is equivalent to launch(TheClass.class, args) where TheClass is the
 199      * immediately enclosing class of the method that called launch. It must
 200      * be a subclass of Application or a RuntimeException will be thrown.
 201      *
 202      * <p>
 203      * The launch method does not return until the application has exited,
 204      * either via a call to Platform.exit or all of the application windows
 205      * have been closed.
 206      *
 207      * <p>
 208      * Typical usage is:
 209      * <ul>
 210      * <pre>
 211      * public static void main(String[] args) {
 212      *     Application.launch(args);
 213      * }
 214      * </pre>
 215      * </ul>
 216      *
 217      * @param args the command line arguments passed to the application.
 218      *             An application may get these parameters using the
 219      *             {@link #getParameters()} method.
 220      *
 221      * @throws IllegalStateException if this method is called more than once.





 222      */
 223     public static void launch(String... args) {
 224         // Figure out the right class to call
 225         StackTraceElement[] cause = Thread.currentThread().getStackTrace();
 226 
 227         boolean foundThisMethod = false;
 228         String callingClassName = null;
 229         for (StackTraceElement se : cause) {
 230             // Skip entries until we get to the entry for this class
 231             String className = se.getClassName();
 232             String methodName = se.getMethodName();
 233             if (foundThisMethod) {
 234                 callingClassName = className;
 235                 break;
 236             } else if (Application.class.getName().equals(className)
 237                     && "launch".equals(methodName)) {
 238 
 239                 foundThisMethod = true;
 240             }
 241         }


   1 /*
   2  * Copyright (c) 2010, 2017, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   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.reflect.Module;
  29 import java.security.AccessController;
  30 import java.security.PrivilegedAction;
  31 import java.util.List;
  32 import java.util.Map;
  33 
  34 import javafx.application.Preloader.PreloaderNotification;
  35 import javafx.scene.Scene;
  36 import javafx.stage.Stage;
  37 
  38 import com.sun.javafx.application.LauncherImpl;
  39 import com.sun.javafx.application.ParametersImpl;
  40 import com.sun.javafx.application.PlatformImpl;
  41 import com.sun.javafx.css.StyleManager;
  42 
  43 /**
  44  * Application class from which JavaFX applications extend.
  45  *
  46  * <p><b>Life-cycle</b></p>
  47  * <p>
  48  * The entry point for JavaFX applications is the Application class. The
  49  * JavaFX runtime does the following, in order, whenever an application is
  50  * launched:
  51  * </p>
  52  * <ol>
  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 the
  69  * containing package must be {@link Module#isExported(String,Module) exported}
  70  * to the {@code javafx.graphics} module.</p>
  71  *
  72  * <p>Calling {@link Platform#exit} is the preferred way to explicitly terminate
  73  * a JavaFX Application. Directly calling {@link System#exit} is
  74  * an acceptable alternative, but doesn't allow the Application {@link #stop}
  75  * method to run.
  76  * </p>
  77  *
  78  * <p>A JavaFX Application should not attempt to use JavaFX after the
  79  * FX toolkit has terminated or from a ShutdownHook, that is, after the
  80  * {@link #stop} method returns or {@link System#exit} is called.
  81  * </p>
  82  *
  83  * <p><b>Parameters</b></p>
  84  * <p>
  85  * Application parameters are available by calling the {@link #getParameters}
  86  * method from the {@link #init} method, or any time after the {@code init}
  87  * method has been called.
  88  * </p>
  89  *
  90  * <p><b>Threading</b></p>


 173      * <p>
 174      * Typical usage is:
 175      * <ul>
 176      * <pre>
 177      * public static void main(String[] args) {
 178      *     Application.launch(MyApp.class, args);
 179      * }
 180      * </pre>
 181      * </ul>
 182      * where <code>MyApp</code> is a subclass of Application.
 183      *
 184      * @param appClass the application class that is constructed and executed
 185      *        by the launcher.
 186      * @param args the command line arguments passed to the application.
 187      *             An application may get these parameters using the
 188      *             {@link #getParameters()} method.
 189      *
 190      * @throws IllegalStateException if this method is called more than once.
 191      * @throws IllegalArgumentException if <code>appClass</code> is not a
 192      *         subclass of <code>Application</code>.
 193      * @throws RuntimeException if there is an error launching the
 194      * JavaFX runtime, or if the application class cannot be constructed
 195      * (e.g., if the class is not public or is not in an exported package), or
 196      * if an Exception or Error is thrown by the Application constructor, init
 197      * method, start method, or stop method.
 198      */
 199     public static void launch(Class<? extends Application> appClass, String... args) {
 200         LauncherImpl.launchApplication(appClass, args);
 201     }
 202 
 203     /**
 204      * Launch a standalone application. This method is typically called
 205      * from the main method(). It must not be called more than once or an
 206      * exception will be thrown.
 207      * This is equivalent to launch(TheClass.class, args) where TheClass is the
 208      * immediately enclosing class of the method that called launch. It must
 209      * be a subclass of Application or a RuntimeException will be thrown.
 210      *
 211      * <p>
 212      * The launch method does not return until the application has exited,
 213      * either via a call to Platform.exit or all of the application windows
 214      * have been closed.
 215      *
 216      * <p>
 217      * Typical usage is:
 218      * <ul>
 219      * <pre>
 220      * public static void main(String[] args) {
 221      *     Application.launch(args);
 222      * }
 223      * </pre>
 224      * </ul>
 225      *
 226      * @param args the command line arguments passed to the application.
 227      *             An application may get these parameters using the
 228      *             {@link #getParameters()} method.
 229      *
 230      * @throws IllegalStateException if this method is called more than once.
 231      * @throws RuntimeException if there is an error launching the
 232      * JavaFX runtime, or if the application class cannot be constructed
 233      * (e.g., if the class is not public or is not in an exported package), or
 234      * if an Exception or Error is thrown by the Application constructor, init
 235      * method, start method, or stop method.
 236      */
 237     public static void launch(String... args) {
 238         // Figure out the right class to call
 239         StackTraceElement[] cause = Thread.currentThread().getStackTrace();
 240 
 241         boolean foundThisMethod = false;
 242         String callingClassName = null;
 243         for (StackTraceElement se : cause) {
 244             // Skip entries until we get to the entry for this class
 245             String className = se.getClassName();
 246             String methodName = se.getMethodName();
 247             if (foundThisMethod) {
 248                 callingClassName = className;
 249                 break;
 250             } else if (Application.class.getName().equals(className)
 251                     && "launch".equals(methodName)) {
 252 
 253                 foundThisMethod = true;
 254             }
 255         }


< prev index next >