with Objects; use Objects;
private with Ada.Strings.Unbounded;
private with Locking_Objects;
package Applications is
-- An Application is a global singleton object that implements an
-- application's initialization, runtime, and shutdown behavior and provides
-- some meta information about it.
type Application is abstract new Limited_Object with private;
type A_Application is access all Application'Class;
-- Returns the name of the company or individual that produced this
-- application.
function Get_Company( this : not null access Application'Class ) return String;
-- Returns the short name of the application. This can be used to determine
-- the names of application-specific files, etc. Special characters should
-- be avoided.
function Get_Name( this : not null access Application'Class ) return String;
-- Initializes, runs and finalizes the application runtime. 'returnCode'
-- contains the numeric code that should be returned to the OS on exit.
procedure Run( this : not null access Application'Class; returnCode : in out Integer );
----------------------------------------------------------------------------
-- Forces creation of the global application without returning a reference.
-- If the application already exists, nothing will happen.
procedure Create_Application;
-- Returns a reference to the global application or null if it has not been
-- created.
function Get_Application return A_Application;
-- Deletes the global application if it exists.
procedure Delete_Application;
----------------------------------------------------------------------------
-- Predefined values returned by Run
NO_ERROR : constant := 0;
ERROR_UNEXPECTED_EXCEPTION : constant := 1;
-- This can be raised by initialization code in other packages to indicate
-- that application initialization has failed. This exception is not raised
-- by the Application class.
INIT_EXCEPTION : exception;
-- This can be raised by the Application class to indicate that it is being
-- misused. For example, calling Create_Application without registering an
-- Application object allocator will raise USE_ERROR.
USE_ERROR : exception;
private
use Ada.Strings.Unbounded;
use Locking_Objects;
----------------------------------------------------------------------------
type Application is abstract new Limited_Object with
record
-- the following fields are unprotected because they don't change
company, -- developer's name
name : Unbounded_String; -- app short name
lock : A_Locking_Object; -- a lock for modifying fields
end record;
-- Closes the application and releases all resources. Do not call this if
-- the application didn't successfully initialize. This should be called
-- last by an overriding implementation.
procedure Close( this : access Application );
-- Constructs the application object. 'name' is a short name for the
-- application and should not contain any special characters. This should be
-- called first by a subclass constructor.
procedure Construct( this : access Application;
company : String;
name : String );
-- Deletes the internals of the application before freeing memory. This
-- should be called last by an overriding implementation.
procedure Delete( this : in out Application );
-- Initializes the application. Returns True on success. If initialization
-- fails, Close will be called automatically to clean up before False is
-- returned. No exception will be raised. This should be called first by
-- an overriding implementation.
function Init( this : access Application ) return Boolean;
-- This is the application's main procedure that will be executed after a
-- successful initialization. Return 0 for success or any other integer to
-- indicate an error to the operating system. If this function is not
-- overridden, it will raise a USE_ERROR.
-- OVERRIDE THIS FUNCTION --
function Run( this : access Application ) return Integer;
-- Deletes an Application object. If the Application has been initialized,
-- then Close must be called before deletion.
procedure Delete( this : in out A_Application );
pragma Postcondition( this = null );
----------------------------------------------------------------------------
-- An Allocator creates a new concrete Application instance.
type Allocator is access function return A_Application;
-- Registers an allocator for creating the global Application instance.
procedure Register_Allocator( allocate : not null Allocator );
end Applications;