Package com.globalmentor.application

Class AbstractApplication

  • All Implemented Interfaces:
    Application, com.globalmentor.model.Named<java.lang.String>, io.clogr.Clogged, java.lang.Runnable
    Direct Known Subclasses:
    BaseCliApplication
    public abstract class AbstractApplication
extends java.lang.Object
implements Application
    An abstract implementation of an application that by default is a console application.
    Author:
    Garret Wilson
    Implementation Specification:
    Errors are written in simple form to System.err., The default preference node is based upon the implementing application class.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected boolean canEnd()
      Determines whether the application can end.
      protected boolean canStart()
      Checks requirements, permissions, and expirations before starting.
      void end​(int status)
      Ends the application with the given status.
      protected int execute()
      Main execution implementation.
      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.
      void initialize()
      Initializes the application.
      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.
      protected void setAuthenticator​(com.globalmentor.net.Authenticable authenticable)
      Sets the authenticator object used to retrieve client authentication.
      protected void setExpirationDate​(java.time.LocalDate newExpirationDate)
      Sets the expiration date of the application.
      int start()
      Starts the application if it can be started.
      protected java.lang.String toErrorMessage​(java.lang.Throwable throwable)
      Constructs a user-presentable error message based on an exception.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

      • 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

    • Constructor Detail

      • AbstractApplication

        public AbstractApplication()
        No-arguments constructor.

      • AbstractApplication

        public AbstractApplication​(@Nonnull
                           java.lang.String[] args)
        Arguments constructor.
        Parameters:
        args - The command line arguments.

    • Method Detail

      • getAuthenticator

        public java.util.Optional<com.globalmentor.net.Authenticable> getAuthenticator()
        Specified by:
        getAuthenticator in interface Application
        Returns:
        The authenticator object used to retrieve client authentication.

      • setAuthenticator

        protected void setAuthenticator​(@Nullable
                                com.globalmentor.net.Authenticable authenticable)
        Sets the authenticator object used to retrieve client authentication.
        Parameters:
        authenticable - The object to retrieve authentication information regarding a client.

      • getArgs

        public java.lang.String[] getArgs()
        Specified by:
        getArgs in interface Application
        Returns:
        The command-line arguments of the application.

      • getPreferences

        public java.util.prefs.Preferences getPreferences()
                                           throws java.lang.SecurityException
        Description copied from interface: Application
        Returns the application user preferences.
        Specified by:
        getPreferences in interface Application
        Returns:
        The default user preferences for this application.
        Throws:
        java.lang.SecurityException - if a security manager is present and it denies RuntimePermission("preferences").

      • getExpirationDate

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

      • setExpirationDate

        protected void setExpirationDate​(@Nullable
                                 java.time.LocalDate newExpirationDate)
        Sets the expiration date of the application.
        Parameters:
        newExpirationDate - The new expiration date, or null if there is no expiration.

      • initialize

        public void initialize()
                throws java.lang.Exception
        Initializes the application. This method is called after construction but before application execution.
        Specified by:
        initialize in interface Application
        Implementation Specification:
        This version does nothing.
        Throws:
        java.lang.Exception - if anything goes wrong.

      • start

        public int start()
        Starts the application if it can be started.
        Specified by:
        start in interface Application
        API Note:
        To change how the main application is executed, normally execute() should be overridden and not this method.
        Implementation Specification:
        The default implementation delegates calls canStart() and, if it returns true, delegates to execute().
        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.
        See Also:
        canStart(), execute()

      • execute

        protected int execute()
        Main execution implementation.
        Implementation Specification:
        The default implementation delegates to Runnable.run() and returns a status code of 0.
        Implementation Note:
        Normally this method delegates to Runnable.run() for default functionality, but may delegate directly to other methods, e.g. representing CLI commands.
        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.

      • canStart

        protected boolean canStart()
        Checks requirements, permissions, and expirations before starting.
        Returns:
        true if the checks succeeded.

      • end

        public final void end​(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.
        Specified by:
        end in interface Application
        Implementation Specification:
        This method first calls canEnd() to see if exit can occur., If exit is allowed to occur, this method will exit even if there was an error in calling Application.exit(int).
        Parameters:
        status - The exit status.
        See Also:
        canEnd(), Application.exit(int)

      • canEnd

        protected boolean canEnd()
        Determines whether the application can end. This method may query the user. If the application has been modified, the configuration is saved if possible.
        Returns:
        true if the application can end, else false.

      • reportError

        public void reportError​(java.lang.Throwable throwable)
        Reports an error condition to the user. A message will be added as appropriate.
        Specified by:
        reportError in interface Application
        Implementation Specification:
        This version delegates to reportError(String, Throwable) using the message determined by toErrorMessage(Throwable).
        Parameters:
        throwable - The condition that caused the error.

      • reportError

        public void reportError​(@Nonnull
                        java.lang.String message,
                        @Nonnull
                        java.lang.Throwable throwable)
        Reports an error message to the user related to an exception.
        Specified by:
        reportError in interface Application
        Implementation Specification:
        This implementation calls reportError(String) and then prints a stack trace to System.err.
        Parameters:
        message - The message to display.
        throwable - The condition that caused the error.
        See Also:
        Throwable.printStackTrace(PrintStream)

      • reportError

        public void reportError​(java.lang.String message)
        Reports the given error message to the user
        Specified by:
        reportError in interface Application
        Implementation Specification:
        This implementation writes the message to System.err.
        Parameters:
        message - The error to display.

      • toErrorMessage

        @Nonnull
protected java.lang.String toErrorMessage​(java.lang.Throwable throwable)
        Constructs a user-presentable error message based on an exception.
        Implementation Specification:
        This version returns constructed messages for exceptions known not to contain useful information. In most cases it returns Throwable.getMessage().
        Parameters:
        throwable - The condition that caused the error.
        Returns:
        The error message.
        See Also:
        Throwable.getMessage()