Ice

Class Application

java.lang.Object

Ice.Application

public abstract class Application
extends java.lang.Object

Utility base class that makes it easy to correctly initialize and finalize the Ice run time, as well as handle signals. Unless the application specifies a logger, Application installs a per-process logger that logs to the standard error output.

Applications must create a derived class that implements the run(java.lang.String[]) method.

A program can contain only one instance of this class.

See Also:

run(java.lang.String[]), Communicator, Logger

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Application.AppHook

Field Summary

Fields

Modifier and Type	Field and Description
protected static Application.AppHook	_appHook
protected static java.lang.String	_appName
protected static boolean	_callbackInProgress
protected static Communicator	_communicator
protected static boolean	_destroyed
protected static boolean	_interrupted
protected static java.lang.Object	_mutex
protected static SignalPolicy	_signalPolicy

Constructor Summary

Constructors

Constructor and Description
Application() Initializes an instance that calls Communicator.shutdown() if a signal is received.
Application(SignalPolicy signalPolicy) Initializes an instance that handles signals according to the signal policy.

Method Summary

Modifier and Type	Method and Description
static java.lang.String	appName() Returns the value of appName that is passed to main (which is also the the value of Ice.ProgramName).
static Communicator	communicator() Returns the communicator for the application.
static void	defaultInterrupt() Clears any shutdown hooks, including any hook established with destroyOnInterrupt() or shutdownOnInterrupt().
static void	destroyOnInterrupt() Instructs Application to call Communicator.destroy() on receipt of a signal.
protected int	doMain(StringSeqHolder argHolder, InitializationData initData)
static boolean	interrupted() Determines whether the application shut down intentionally or was forced to shut down by the JVM.
int	main(java.lang.String appName, java.lang.String[] args) The application must call main after it has instantiated the derived class.
int	main(java.lang.String appName, java.lang.String[] args, InitializationData initializationData) The application must call main after it has instantiated the derived class.
int	main(java.lang.String appName, java.lang.String[] args, java.lang.String configFile) The application must call main after it has instantiated the derived class.
abstract int	run(java.lang.String[] args) Called once the communicator has been initialized.
static void	setInterruptHook(java.lang.Thread newHook) Installs a custom shutdown hook.
static void	shutdownOnInterrupt() Instructs Application to call Communicator.shutdown() on receipt of a signal.

Methods inherited from class java.lang.Object

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

Field Detail

_appName

protected static java.lang.String _appName

_communicator

protected static Communicator _communicator

_appHook

protected static Application.AppHook _appHook

_mutex

protected static final java.lang.Object _mutex

_callbackInProgress

protected static boolean _callbackInProgress

_destroyed

protected static boolean _destroyed

_interrupted

protected static boolean _interrupted

_signalPolicy

protected static SignalPolicy _signalPolicy

Constructor Detail

Application

public Application()

Initializes an instance that calls Communicator.shutdown() if a signal is received.

Application

public Application(SignalPolicy signalPolicy)

Initializes an instance that handles signals according to the signal policy.

Parameters:

signalPolicy - Determines how to respond to signals.

See Also:

SignalPolicy

Method Detail

main

public final int main(java.lang.String appName,
                      java.lang.String[] args)

The application must call main after it has instantiated the derived class. main creates a communicator, establishes the specified signal policy, and, once run returns, destroys the communicator.

The method prints an error message for any exception that propagates out of run and ensures that the communicator is destroyed correctly even if run completes abnormally.

Parameters:

appName - The name of the application. This parameter is used to initialize the value of the Ice.ProgramName property.

args - The arguments for the application (as passed to Main(String[]) by the operating system.

Returns:

The value returned by run. If run terminates with an exception, the return value is non-zero.

main

public final int main(java.lang.String appName,
                      java.lang.String[] args,
                      java.lang.String configFile)

The application must call main after it has instantiated the derived class. main creates a communicator, establishes the specified signal policy, and, once run returns, destroys the communicator.

The method prints an error message for any exception that propagates out of run and ensures that the communicator is destroyed correctly even if run completes abnormally.

Parameters:

appName - The name of the application. This parameter is used to initialize the value of the Ice.ProgramName property.

args - The command-line arguments.

configFile - The configuration file with which to initialize Ice properties.

Returns:

The value returned by run. If run terminates with an exception, the return value is non-zero.

main

public final int main(java.lang.String appName,
                      java.lang.String[] args,
                      InitializationData initializationData)

The application must call main after it has instantiated the derived class. main creates a communicator, establishes the specified signal policy, and, once run returns, destroys the communicator.

The method prints an error message for any exception that propagates out of run and ensures that the communicator is destroyed correctly even if run completes abnormally.

Parameters:

appName - The name of the application. This parameter is used to initialize the value of the Ice.ProgramName property.

args - The arguments for the application (as passed to Main(String[]).

initializationData - Additional data used to initialize the communicator.

Returns:

The value returned by run. If run terminates with an exception, the return value is non-zero.

See Also:

InitializationData

doMain

protected int doMain(StringSeqHolder argHolder,
                     InitializationData initData)

run

public abstract int run(java.lang.String[] args)

Called once the communicator has been initialized. The derived class must implement run, which is the application's starting method.

Parameters:

args - The argument vector for the application. Application scans the argument vector passed to main for options that are specific to the Ice run time and removes them; therefore, the vector passed to run is free from Ice-related options and contains only options and arguments that are application-specific.

Returns:

The run method should return zero for successful termination, and non-zero otherwise. Application.main returns the value returned by run.

appName

public static java.lang.String appName()

Returns the value of appName that is passed to main (which is also the the value of Ice.ProgramName). This method is useful mainly for error messages that include the application name. Because appName is a static method, it is available from anywhere in the program.

Returns:

The name of the application.

communicator

public static Communicator communicator()

Returns the communicator for the application. Because communicator is a static method, it permits access to the communicator from anywhere in the program. Note that, as a consequence, you cannot have more than one instance of Application in a program.

Returns:

The communicator for the application.

destroyOnInterrupt

public static void destroyOnInterrupt()

Instructs Application to call Communicator.destroy() on receipt of a signal. This is default signal handling policy established by the default constructor.

See Also:

Communicator.destroy()

shutdownOnInterrupt

public static void shutdownOnInterrupt()

Instructs Application to call Communicator.shutdown() on receipt of a signal.

See Also:

Communicator.shutdown()

setInterruptHook

public static void setInterruptHook(java.lang.Thread newHook)

Installs a custom shutdown hook. The implementation of the shutdown hook can do whatever cleanup is necessary to shut down the application. The hook is unregistered once run returns. Note that the hook must obey the rules for shutdown hooks; specifically, it must not call exit.

Parameters:

newHook - The thread to run on shutdown.

See Also:

Runtime.addShutdownHook(java.lang.Thread)

defaultInterrupt

public static void defaultInterrupt()

Clears any shutdown hooks, including any hook established with destroyOnInterrupt() or shutdownOnInterrupt().

interrupted

public static boolean interrupted()

Determines whether the application shut down intentionally or was forced to shut down by the JVM. This is useful for logging purposes.

Returns:

true if a shutdown hook caused the communicator to shut down; false otherwise.