org.openmdx.base.application.control
Class Application

java.lang.Object
  org.openmdx.base.application.control.Manageable
      org.openmdx.base.application.control.Application

Direct Known Subclasses:

Application_1_0, ExportXml, ImportXml, Replicate

public class Application
extends Manageable

The application class represents an executable Java application.

Simple application

The most simple application looks like:

      import org.openmdx.base.application.Application;
      import org.openmdx.base.application.ApplicationController_1_0;

      public class SimpApp extends Application
      {
        public SimpApp()
        {
          super("SimpApp", "1.0", "Simple App", null);
        }

        protected void run()
          throws Exception
        {
          System.out.println("Hello World");
        }

        public static void main(String args[])
        {
          ApplicationController_1_0  controller;

          controller = new ApplicationController_1_0(args);

          controller.registerApplication(new SimpApp());
          controller.run();
        }
      }
 

Elaborated application

A full featured application using

• Application name and version
• Command line parameters
• Help text
• Logging initialisation
• Exception handler
• CommandLine event handler
• Exit codes

Both handlers shown here are similiar to the default handlers.

      import org.openmdx.base.application.CmdLineOption;
      import org.openmdx.base.application.Application;
      import org.openmdx.base.application.ApplicationController_1_0;
      import org.openmdx.base.application.ExceptionEvent;
      import org.openmdx.base.application.ExceptionListener;
      import org.openmdx.base.log.generic.AppLog;
      import org.openmdx.base.exception.StackedException;
      import myPackage.MyException;


      public class SimpApp extends Application
        implements ExceptionListener
      {
        public SimpApp()
        {
          super("SimpApp", "1.0",
                "A sample to demonstrate the Application features",
                createCmdLineOptions());
        }


        protected void init()
          throws Exception
        {
          this.msg   = getCmdLineArgs().getFirstValue("msg"));
          this.print = getCmdLineArgs().hasArg("print"));
        }

        protected void run()
          throws Exception
        {
          if (this.print) System.out.println(this.msg);
        }

        protected void release()
          throws Exception
        {
          AppLog.trace("Done");
          setExitCode(1);
        }

        // ExceptionEvent listener
        public void exception(ExceptionEvent e)
        {
          // handle your own exceptions, that org.openmdx.base is not
          // aware of
          Throwable  th = e.getException();
          if (ex instanceof StackedException) {
            AppLog.error("",((StackedException)ex).toString());
          }else if (ex instanceof MyException) {
            AppLog.error("",((MyException)ex).toString());
          }else{
            AppLog.error("", ex);
          }
        }

        // CmdLineEvent listener
        public void cmdLineBadArgs(CmdLineEvent e)
        {
          System.out.println("Command line parsing failed!");
          System.out.println();
          System.out.println(e.getInfo());
          exit(Application.EXIT_CODE_FAILED);
        }

        // CmdLineEvent listener
        public void cmdLineHelpRequest(CmdLineEvent e)
        {
          System.out.println(e.getInfo());
          exit(Application.EXIT_CODE_FAILED);
        }

        // CmdLineEvent listener
        public void cmdLineVersionRequest(CmdLineEvent e)
        {
          System.out.println(e.getInfo());
          exit(Application.EXIT_CODE_OK);
        }

        // CmdLineEvent listener
        public void cmdLineTrace(CmdLineEvent e)
        {
          System.out.println(e.getInfo());
        }

        private static ArrayList createCmdLineOptions()
        {
          ArrayList  options = new ArrayList();

          options.add(new CmdLineOption("msg"  , "A message to be printed", 1, 1));
          options.add(new CmdLineOption("print", "Enable message printing"));
          return options;
        }

        public static void main(String args[])
        {
          ApplicationController_1_0  controller;

          controller = new ApplicationController_1_0(args);

          controller.initLogging("simpapp", "SimpApp");
          controller.registerApplication(new SimpApp());
          controller.run();
        }

        private boolean print;
        private String  msg;
      }
 

Field Summary

static int	EXIT_CODE_FAILED
static int	EXIT_CODE_OK Predefined application exit codes

Constructor Summary

Application()
Creates an Application object.

Application(String name, String version, String helpText, List cmdLineOptions)
Creates an Application object.

Application(String name, String version, String helpText, List cmdLineOptions, CmdLineFreeArgOption cmdLineFreeArgOption)
Creates an Application object.

Method Summary

void	exit() Terminates the currently running application.
void	exit(int exitCode) Terminates the currently running application.
static Application	getApp() Returns the application object
CmdLineFreeArgOption	getCmdLineFreeArgOptions() Requests the command line free argument option specification
List	getCmdLineOptions() Requests the command line options specification
int	getExitCode() Returns the application's exit code
String	getHelpText() Returns the application's version
String	getName() Returns the application's name
String	getVersion() Returns the application's version
boolean	hasFailed() Checks if the application has failed.
protected void	init() Initializes the application.
protected static List	mergeCmdLineOptions(List opts1, List opts2) Merges all command line options from opst2 into opts1
protected void	release() The default application release.
protected void	run() The default application run.
protected void	setExitCode(int exitCode) Sets the applications exit code.

Methods inherited from class org.openmdx.base.application.control.Manageable

getCmdLineArgs, getController, getRawArgs, setController

Methods inherited from class java.lang.Object

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

Field Detail

EXIT_CODE_OK

public static final int EXIT_CODE_OK

Predefined application exit codes

See Also:

Constant Field Values

EXIT_CODE_FAILED

public static final int EXIT_CODE_FAILED

See Also:

Constant Field Values

Constructor Detail

Application

public Application()

Creates an Application object. The application name is the class name and the application version is set to 1.0

NOTE: NEVER PUT DIRECT OR INDIRECT APPLICATION LOGIC INTO THE CONSTRUCTOR!

Application

public Application(String name,
                   String version,
                   String helpText,
                   List cmdLineOptions)

Creates an Application object.

A note on help text:

Requests the application overview help text. Pass a short text that describes what the application is doing. The application name and the version are implicitely added.

Do not format the text using control characters as ('\r', '\n', ...) nor pass any command option description here. The Help text is appropriately formatted when outputted.

NOTE: NEVER PUT DIRECT OR INDIRECT APPLICATION LOGIC INTO THE CONSTRUCTOR!

Parameters:

name - The application's name

version - The application's version

helpText - The application's help

cmdLineOptions - The application's command line options. A list of CmdLineOption objects

Application

public Application(String name,
                   String version,
                   String helpText,
                   List cmdLineOptions,
                   CmdLineFreeArgOption cmdLineFreeArgOption)

Creates an Application object.

A note on help text:

Requests the application overview help text. Pass a short text that describes what the application is doing. The application name and the version are implicitely added.

Do not format the text using control characters as ('\r', '\n', ...) nor pass any command option description here. The Help text is appropriately formatted when outputted.

NOTE: NEVER PUT DIRECT OR INDIRECT APPLICATION LOGIC INTO THE CONSTRUCTOR!

Parameters:

name - The application's name

version - The application's version

helpText - The application's help

cmdLineOptions - The application's command line options. A list of CmdLineOption objects

cmdLineFreeArgOption - The application's command line free arg option

Method Detail

getName

public final String getName()

Returns the application's name

Returns:

String

getVersion

public final String getVersion()

Returns the application's version

Returns:

String

getHelpText

public final String getHelpText()

Returns the application's version

Returns:

String

getCmdLineOptions

public final List getCmdLineOptions()

Requests the command line options specification

Overrides:

getCmdLineOptions in class Manageable

Returns:

a list of cmd line options (objects of class CmdLineOption)

getCmdLineFreeArgOptions

public final CmdLineFreeArgOption getCmdLineFreeArgOptions()

Requests the command line free argument option specification

Returns:

A string

getExitCode

public final int getExitCode()

Returns the application's exit code

exit

public final void exit()

Terminates the currently running application. Uses the previously set exit code. This method calls the exit method in class System. This method never returns normally.

exit

public final void exit(int exitCode)

Terminates the currently running application. The argument serves as a status code; by convention, a nonzero status code indicates abnormal termination. This method calls the exit method in class System. This method never returns normally.

hasFailed

public final boolean hasFailed()

Checks if the application has failed. An application failure is indicated by an exit code not equal to EXIT_CODE_OK. The exit code can be set at any time during execution.

getApp

public static Application getApp()

Returns the application object

Returns:

the application object

init

protected void init()
             throws Exception

Initializes the application. May be overloaded by a concrete application If init() fails, init() has to cleanup all it's allocated resources.

Specified by:

init in class Manageable

Throws:

Exception

run

protected void run()
            throws Exception

The default application run. May be overloaded by a concrete application. run() is called only if init() was successful.

Throws:

Exception

release

protected void release()
                throws Exception

The default application release. May be overloaded by a concrete application release() is called only if init() was successful.

Specified by:

release in class Manageable

Throws:

Exception

setExitCode

protected final void setExitCode(int exitCode)

Sets the applications exit code. Once an exit code other than EXIT_CODE_OK has been set, it not possible to switch back to EXIT_CODE_OK. The default exit code set is EXIT_CODE_OK.

mergeCmdLineOptions

protected static List mergeCmdLineOptions(List opts1,
                                          List opts2)

Merges all command line options from opst2 into opts1

Parameters:

opts1 -

opts2 -

Returns:

List The merged option list