Package com.globalmentor.application

Interface Application

  • All Superinterfaces:
    io.clogr.Clogged, com.globalmentor.model.Named<java.lang.String>, java.lang.Runnable
    All Known Implementing Classes:
    AbstractApplication, BaseCliApplication
    public interface Application
extends java.lang.Runnable, com.globalmentor.model.Named<java.lang.String>, io.clogr.Clogged
    A general application.

    To start an application, call the static start(Application) method, passing it an application instance.

    Author:
    Garret Wilson
    API Note:
    Although an application implements Runnable, it should usually be started using start(), which will eventually (depending on the implementation) call Runnable.run(). The start(Application) takes care of calling the correct entry point.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int EXIT_CODE_CONTINUE
      Pseudo exit code indicating that the application should not exit immediately, e.g.
      static int EXIT_CODE_OK
      Exit code indicating a successful termination.
      static int EXIT_CODE_SOFTWARE
      Exit code indicating execution failure.
      static int EXIT_CODE_USAGE
      Exit code indicating incorrect command-line usage.
      static java.lang.String[] NO_ARGUMENTS
      An array containing no arguments.

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      default void end()
      Ends the application with a status of success.
      void end​(int status)
      Ends the application with the given status.
      default void exit​(int status)
      Exits the application immediately with the given status without checking to see if exit should be performed.
      java.lang.String[] getArgs()  
      java.util.Optional<com.globalmentor.net.Authenticable> getAuthenticator()  
      java.util.Optional<java.time.LocalDate> getExpirationDate()  
      java.util.prefs.Preferences getPreferences()
      Returns the application user preferences.
      java.lang.String getVersion()  
      void initialize()
      Initializes the application.
      boolean isDebug()
      Returns whether debug mode is enabled.
      void reportError​(java.lang.String message)
      Reports the given error message to the user
      void reportError​(java.lang.String message, java.lang.Throwable throwable)
      Reports an error message to the user related to an exception.
      void reportError​(java.lang.Throwable throwable)
      Reports an error condition to the user.
      int start()
      Starts the application if it can be started.
      static void start​(Application application)
      Starts an application.

      • Methods inherited from interface io.clogr.Clogged

        getLogger

      • Methods inherited from interface com.globalmentor.model.Named

        getName

      • Methods inherited from interface java.lang.Runnable

        run

    • Method Detail

      • getAuthenticator

        java.util.Optional<com.globalmentor.net.Authenticable> getAuthenticator()
        Returns:
        The authenticator object used to retrieve client authentication.

      • getArgs

        java.lang.String[] getArgs()
        Returns:
        The command-line arguments of the application.

      • getVersion

        java.lang.String getVersion()
        Returns:
        The application version string .

      • isDebug

        boolean isDebug()
        Returns whether debug mode is enabled.
        API Note:
        Debug mode enables debug level logging and may also enable other debug functionality.
        Returns:
        The state of debug mode.

      • getPreferences

        java.util.prefs.Preferences getPreferences()
                                    throws java.lang.SecurityException
        Returns the application user preferences.
        Returns:
        The default user preferences for this application.
        Throws:
        java.lang.SecurityException - if a security manager is present and it denies RuntimePermission("preferences").

      • getExpirationDate

        java.util.Optional<java.time.LocalDate> getExpirationDate()
        Returns:
        The expiration date of the application, if there is one.

      • initialize

        void initialize()
         throws java.lang.Exception
        Initializes the application. This method is called after construction but before application execution.
        Throws:
        java.lang.Exception - if anything goes wrong.

      • start

        int start()
        Starts the application if it can be started.
        Implementation Note:
        This method should eventually delegate to Runnable.run().
        Returns:
        The application status:
        0
        Success.
        Any positive exit code.
        There was an error and the application should exit.
        -1
        The application should not exit but continue running, such as for a GUI or daemon application.

      • start

        static void start​(@Nonnull
                  Application application)
        Starts an application. If this method returns, the program is still running.
        1. Calls initialize().
        2. Calls start(), which eventually calls Runnable.run(). If a non-zero exit code is returned, the application will end. An exit code of -1 indicates that the application should not exit after running.
        3. Normally start() delegates to Runnable.run() for default functionality, but may delegate directly to other methods, e.g. representing CLI commands.
        4. If a positive exit code was given, calls end(int) to exit the application. (A status of -1 indicates that the program continues to run.)
        API Note:
        Except for GUI programs and daemons, this method will never return, as it will eventually call end(int) which will immediately exit the program. If the program chooses to continue running, it should call end(int) at some point when it is ready to stop so that all needed shutdown activities will occur.
        Parameters:
        application - The application to start.

      • end

        default void end()
        Ends the application with a status of success.
        Implementation Specification:
        The default implementation delegates to end(int) with a value of 0.
        Implementation Note:
        This method should eventually delegate to exit(int).
        See Also:
        end(int)

      • end

        void end​(@Nonnegative
         int status)
        Ends the application with the given status. This method first checks to see if the program can end. If the status is not 0, the application will then exit immediately.
        API Note:
        This method normally will never return., To add to exit functionality, exit(int) should be overridden rather than this method., This method explicitly does not accept -1, as continuing and ending contradictory concepts.
        Implementation Note:
        This method should eventually delegate to exit(int).
        Parameters:
        status - The exit status, which must not be negative.
        Throws:
        java.lang.IllegalArgumentException - if the given status is negative.
        See Also:
        exit(int)

      • exit

        default void exit​(int status)
        Exits the application immediately with the given status without checking to see if exit should be performed.
        API Note:
        This method normally will never return., Normally this method is never called directly by the application. To end the application, calling end(int) is preferred.
        Implementation Specification:
        The default implementation delegates to System.exit(int).
        Parameters:
        status - The exit status.
        Throws:
        java.lang.SecurityException - if a security manager exists and its SecurityManager.checkExit(int) method doesn't allow exit with the specified status.
        See Also:
        System.exit(int)

      • reportError

        void reportError​(@Nonnull
                 java.lang.Throwable throwable)
        Reports an error condition to the user. A message will be added as appropriate.
        Parameters:
        throwable - The condition that caused the error.

      • reportError

        void reportError​(@Nonnull
                 java.lang.String message,
                 @Nonnull
                 java.lang.Throwable throwable)
        Reports an error message to the user related to an exception.
        Parameters:
        message - The message to display.
        throwable - The condition that caused the error.

      • reportError

        void reportError​(@Nonnull
                 java.lang.String message)
        Reports the given error message to the user
        Parameters:
        message - The error to display.