- Home
- About
- Testimonials
- Demos
- Download
- Documentation
- Blogs
- Forum
- Support

Packages:
default
System
System.Caching
System.Collections
System.Data
System.Data.ActiveRecord
System.Data.ActiveRecord.Relations
System.Data.ActiveRecord.Scaffold
System.Data.ActiveReecord.Scaffold.InputBuilder
System.Data.Commom.Sqlite
System.Data.Common
System.Data.Common.Mssql
System.Data.Common.Mysql
System.Data.Common.Oracle
System.Data.Common.Pgsql
System.Data.Common.Sqlite
System.Data.DataGateway
System.Data.SqlMap
System.Data.SqlMap.Configuration
System.Data.SqlMap.Statements
System.Exceptions
System.I18N
System.IO
System.Security
System.Util
System.Web
System.Web.Services
System.Web.UI
System.Web.UI.ActiveControls
System.Web.UI.WebControls
System.Web.UI.WebControls.assets
System.Xml
Classes:
IActiveControl
IBindable
ICache
ICacheDependency
ICallbackEventHandler
IDataRenderer
IModule
IRenderable
IService
IStatePersister
IStyleable
ITextWriter
IUser
Prado
PradoBase
TApplication
TApplicationComponent
TApplicationConfiguration
TApplicationMode
TApplicationStatePersister
TComponent
TComponentReflection
TDraggableConstraint
TDropContainerEventParameter
TEnumerable
TEventParameter
TModule
TPropertyValue
TReflectionClass
TService
TShellApplication

Keyword

# Class TApplication

    TComponent
       |
       --TApplication

#### Direct Known Sub-classes:

TShellApplication

TApplication class.

TApplication coordinates modules and services, and serves as a configuration context for all Prado components.

TApplication uses a configuration file to specify the settings of the application, the modules, the services, the parameters, and so on.

TApplication adopts a modular structure. A TApplication instance is a composition of multiple modules. A module is an instance of class implementing IModule interface. Each module accomplishes certain functionalities that are shared by all Prado components in an application. There are default modules and user-defined modules. The latter offers extreme flexibility of extending TApplication in a plug-and-play fashion. Modules cooperate with each other to serve a user request by following a sequence of lifecycles predefined in TApplication.

TApplication has four modes that can be changed by setting Mode property (in the application configuration file).

- Off mode will prevent the application from serving user requests.
- Debug mode is mainly used during application development. It ensures the cache is always up-to-date if caching is enabled. It also allows exceptions are displayed with rich context information if they occur.
- Normal mode is mainly used during production stage. Exception information will only be recorded in system error logs. The cache is ensured to be up-to-date if it is enabled.
- Performance mode is similar to Normal mode except that it does not ensure the cache is up-to-date.

TApplication dispatches each user request to a particular service which finishes the actual work for the request with the aid from the application modules.

TApplication maintains a lifecycle with the following stages:

- [construct] : construction of the application instance
- [initApplication] : load application configuration and instantiate modules and the requested service
- onBeginRequest : this event happens right after application initialization
- onAuthentication : this event happens when authentication is needed for the current request
- onAuthenticationComplete : this event happens right after the authentication is done for the current request
- onAuthorization : this event happens when authorization is needed for the current request
- onAuthorizationComplete : this event happens right after the authorization is done for the current request
- onLoadState : this event happens when application state needs to be loaded
- onLoadStateComplete : this event happens right after the application state is loaded
- onPreRunService : this event happens right before the requested service is to run
- runService : the requested service runs
- onSaveState : this event happens when application needs to save its state
- onSaveStateComplete : this event happens right after the application saves its state
- onPreFlushOutput : this event happens right before the application flushes output to client side.
- flushOutput : the application flushes output to client side.
- onEndRequest : this is the last stage a request is being completed
- [destruct] : destruction of the application instance

Modules and services can attach their methods to one or several of the above events and do appropriate processing when the events are raised. By this way, the application is able to coordinate the activities of modules and services in the above order. To terminate an application before the whole lifecycle completes, call completeRequest.

Examples:

- Create and run a Prado application:

       $application=new TApplication($configFile);
       $application->run();

Since: 3.0
Author: Qiang Xue <qiang.xue@gmail.com>

Constructor Summary
public | __construct Array Constructor.

Method Summary
void | applyConfiguration ( TApplicationConfiguration $config, boolean $withinService) Applies an application configuration.
void | clearGlobalState ( string $key) Clears a global value.
void | completeRequest () Completes current request processing.
void | flushOutput () Flushes output to client side.
IStatePersister | getApplicationStatePersister ()
TAssetManager | getAssetManager ()
TAuthorizationRuleCollection | getAuthorizationRules ()
string | getBasePath ()
ICache | getCache ()
string | getConfigurationFile ()
TErrorHandler | getErrorHandler ()
TGlobalization | getGlobalization ( boolean $createIfNotExists)
mixed | getGlobalState ( string $key, mixed $defaultValue) Returns a global value.
string | getID ()
TApplicationMode | getMode ()
IModule | getModule ( mixed $id)
array | getModules ()
string | getPageServiceID ()
TMap | getParameters () Returns the list of application parameters.
THttpRequest | getRequest ()
boolean | getRequestCompleted ()
THttpResponse | getResponse ()
string | getRuntimePath ()
TSecurityManager | getSecurityManager ()
IService | getService ()
THttpSession | getSession ()
string | getUniqueID ()
IUser | getUser ()
protected void | initApplication ( string 0, string 1) Loads configuration and initializes application.
protected void | loadGlobals () Loads global values from persistent storage.
void | onAuthentication () Raises OnAuthentication event.
void | onAuthenticationComplete () Raises OnAuthenticationComplete event.
void | onAuthorization () Raises OnAuthorization event.
void | onAuthorizationComplete () Raises OnAuthorizationComplete event.
void | onBeginRequest () Raises OnBeginRequest event.
void | onEndRequest () Raises OnEndRequest event.
void | onError ( mixed $param) Raises OnError event.
void | onLoadState () Raises OnLoadState event.
void | onLoadStateComplete () Raises OnLoadStateComplete event.
void | onPreFlushOutput () Raises OnPreFlushOutput event.
void | onPreRunService () Raises OnPreRunService event.
void | onSaveState () Raises OnSaveState event.
void | onSaveStateComplete () Raises OnSaveStateComplete event.
protected void | resolvePaths ( string $basePath) Resolves application-relevant paths.
void | run () Executes the lifecycles of the application.
void | runService () Runs the requested service.
protected void | saveGlobals () Saves global values into persistent storage.
void | setApplicationStatePersister ( IStatePersister $persister)
void | setAssetManager ( TAssetManager $value)
void | setBasePath ( string $value)
void | setCache ( ICache $cache)
void | setConfigurationFile ( string $value)
void | setErrorHandler ( TErrorHandler $handler)
void | setGlobalization ( TGlobalization $glob)
void | setGlobalState ( string $key, mixed $value, mixed $defaultValue) Sets a global value.
void | setID ( string $value)
void | setMode ( TApplicationMode $value)
void | setModule ( string $id, IModule $module) Adds a module to application.
void | setPageServiceID ( string $value)
void | setRequest ( THttpRequest $request)
void | setResponse ( THttpResponse $response)
void | setRuntimePath ( string $value)
void | setSecurityManager ( TSecurityManager $sm)
void | setService ( IService $value)
void | setSession ( THttpSession $session)
void | setUser ( IUser $user)
void | startService ( string $serviceID) Starts the specified service.

Methods Inherited From TComponent

TComponent::addParsedObject(), TComponent::attachEventHandler(), TComponent::canGetProperty(), TComponent::canSetProperty(), TComponent::createdOnTemplate(), TComponent::detachEventHandler(), TComponent::evaluateExpression(), TComponent::evaluateStatements(), TComponent::getEventHandlers(), TComponent::getSubProperty(), TComponent::hasEvent(), TComponent::hasEventHandler(), TComponent::hasProperty(), TComponent::raiseEvent(), TComponent::setSubProperty(), TComponent::__get(), TComponent::__set()

Constant Summary
string | CONFIGCACHE_FILE | Config cache file
string | CONFIG_FILE | Application configuration file name
string | CONFIG_FILE_EXT | File extension for external config files
string | GLOBAL_FILE | Global data file
string | PAGE_SERVICE_ID | Page service ID
string | RUNTIME_PATH | Runtime directory name
string | STATE_DEBUG |
string | STATE_NORMAL |
string | STATE_OFF | possible application mode.
string | STATE_PERFORMANCE |

Constructor Details

## __construct

public __construct | Array

Constructor.

Sets application base path and initializes the application singleton. Application base path refers to the root directory storing application data and code not directly accessible by Web users. By default, the base path is assumed to be the protected directory under the directory containing the current running script.

Throws: TConfigurationException if configuration file cannot be read or the runtime path is invalid.

Method Details

## applyConfiguration

public void applyConfiguration | (TApplicationConfiguration $config , boolean $withinService )

Applies an application configuration.

Input
TApplicationConfiguration | $config | the configuration
boolean | $withinService | whether the configuration is specified within a service.
Output
Exception

## clearGlobalState

public void clearGlobalState | (string $key )

Clears a global value.

The value cleared will no longer be available in this request and the following requests.

Input
string | $key | the name of the value to be cleared
Output
Exception

## completeRequest

public void completeRequest | ()

Completes current request processing.

This method can be used to exit the application lifecycles after finishing the current cycle.

Output
Exception

## flushOutput

public void flushOutput | ()

Flushes output to client side.

Output
Exception

## getApplicationStatePersister

public IStatePersister getApplicationStatePersister | ()

Output
IStatePersister | application state persister
Exception

## getAssetManager

public TAssetManager getAssetManager | ()

Output
TAssetManager | asset manager
Exception

## getAuthorizationRules

public TAuthorizationRuleCollection getAuthorizationRules | ()

Output
TAuthorizationRuleCollection | list of authorization rules for the current request
Exception

## getBasePath

public string getBasePath | ()

Output
string | the directory containing the application configuration file (absolute path)
Exception

## getCache

public ICache getCache | ()

Output
ICache | the cache module, null if cache module is not installed
Exception

## getConfigurationFile

public string getConfigurationFile | ()

Output
string | the application configuration file (absolute path)
Exception

## getErrorHandler

public TErrorHandler getErrorHandler | ()

Output
TErrorHandler | the error handler module
Exception

## getGlobalization

public TGlobalization getGlobalization | (boolean $createIfNotExists )

Input
boolean | $createIfNotExists | whether to create globalization if it does not exist
Output
TGlobalization | globalization module
Exception

## getGlobalState

public mixed getGlobalState | (string $key , mixed $defaultValue )

Returns a global value.

A global value is one that is persistent across users sessions and requests.

Input
string | $key | the name of the value to be returned
mixed | $defaultValue | the default value. If $key is not found, $defaultValue will be returned
Output
mixed | the global value corresponding to $key
Exception

## getID

public string getID | ()

Output
string | application ID
Exception

## getMode

public TApplicationMode getMode | ()

Output
TApplicationMode | application mode. Defaults to TApplicationMode::Debug.
Exception

## getModule

public IModule getModule | (mixed $id )

Input
mixed | $id |
Output
IModule | the module with the specified ID, null if not found
Exception

## getModules

public array getModules | ()

Output
array | list of loaded application modules, indexed by module IDs
Exception

## getPageServiceID

public string getPageServiceID | ()

Output
string | page service ID
Exception

## getParameters

public TMap getParameters | ()

Returns the list of application parameters.

Since the parameters are returned as a TMap object, you may use the returned result to access, add or remove individual parameters.

Output
TMap | the list of application parameters
Exception

## getRequest

public THttpRequest getRequest | ()

Output
THttpRequest | the request module
Exception

## getRequestCompleted

public boolean getRequestCompleted | ()

Output
boolean | whether the current request is processed.
Exception

## getResponse

public THttpResponse getResponse | ()

Output
THttpResponse | the response module
Exception

## getRuntimePath

public string getRuntimePath | ()

Output
string | the directory storing cache data and application-level persistent data. (absolute path)
Exception

## getSecurityManager

public TSecurityManager getSecurityManager | ()

Output
TSecurityManager | the security manager module
Exception

## getService

public IService getService | ()

Output
IService | the currently requested service
Exception

## getSession

public THttpSession getSession | ()

Output
THttpSession | the session module, null if session module is not installed
Exception

## getUniqueID

public string getUniqueID | ()

Output
string | an ID that uniquely identifies this Prado application from the others
Exception

## getUser

public IUser getUser | ()

Output
IUser | the application user
Exception

## initApplication

protected void initApplication | (string 0 , string 1 )

Loads configuration and initializes application.

Configuration file will be read and parsed (if a valid cached version exists, it will be used instead). Then, modules are created and initialized; Afterwards, the requested service is created and initialized.

Input
string | 0 | configuration file path (absolute or relative to current executing script)
string | 1 | cache file path, empty if no present or needed
Output
Exception
throws | TConfigurationException if module is redefined of invalid type, or service not defined or of invalid type

## loadGlobals

protected void loadGlobals | ()

Loads global values from persistent storage.

This method is invoked when OnLoadState event is raised. After this method, values that are stored in previous requests become available to the current request via getGlobalState.

Output
Exception

## onAuthentication

public void onAuthentication | ()

Raises OnAuthentication event.

This method is invoked when the user request needs to be authenticated.

Output
Exception

## onAuthenticationComplete

public void onAuthenticationComplete | ()

Raises OnAuthenticationComplete event.

This method is invoked right after the user request is authenticated.

Output
Exception

## onAuthorization

public void onAuthorization | ()

Raises OnAuthorization event.

This method is invoked when the user request needs to be authorized.

Output
Exception

## onAuthorizationComplete

public void onAuthorizationComplete | ()

Raises OnAuthorizationComplete event.

This method is invoked right after the user request is authorized.

Output
Exception

## onBeginRequest

public void onBeginRequest | ()

Raises OnBeginRequest event.

At the time when this method is invoked, application modules are loaded and initialized, user request is resolved and the corresponding service is loaded and initialized. The application is about to start processing the user request.

Output
Exception

## onEndRequest

public void onEndRequest | ()

Raises OnEndRequest event.

This method is invoked when the application completes the processing of the request.

Output
Exception

## onError

public void onError | (mixed $param )

Raises OnError event.

This method is invoked when an exception is raised during the lifecycles of the application.

Input
mixed | $param | event parameter
Output
Exception

## onLoadState

public void onLoadState | ()

Raises OnLoadState event.

This method is invoked when the application needs to load state (probably stored in session).

Output
Exception

## onLoadStateComplete

public void onLoadStateComplete | ()

Raises OnLoadStateComplete event.

This method is invoked right after the application state has been loaded.

Output
Exception

## onPreFlushOutput

public void onPreFlushOutput | ()

Raises OnPreFlushOutput event.

This method is invoked right before the application flushes output to client.

Output
Exception

## onPreRunService

public void onPreRunService | ()

Raises OnPreRunService event.

This method is invoked right before the service is to be run.

Output
Exception

## onSaveState

public void onSaveState | ()

Raises OnSaveState event.

This method is invoked when the application needs to save state (probably stored in session).

Output
Exception

## onSaveStateComplete

public void onSaveStateComplete | ()

Raises OnSaveStateComplete event.

This method is invoked right after the application state has been saved.

Output
Exception

## resolvePaths

protected void resolvePaths | (string $basePath )

Resolves application-relevant paths.

This method is invoked by the application constructor to determine the application configuration file, application root path and the runtime path.

Input
string | $basePath | the application root path or the application configuration file
Output
Exception

## run

public void run | ()

Executes the lifecycles of the application.

This is the main entry function that leads to the running of the whole Prado application.

Output
Exception

## runService

public void runService | ()

Runs the requested service.

Output
Exception

## saveGlobals

protected void saveGlobals | ()

Saves global values into persistent storage.

This method is invoked when OnSaveState event is raised.

Output
Exception

## setApplicationStatePersister

public void setApplicationStatePersister | (IStatePersister $persister )

Input
IStatePersister | $persister | application state persister
Output
Exception

## setAssetManager

public void setAssetManager | (TAssetManager $value )

Input
TAssetManager | $value | asset manager
Output
Exception

## setBasePath

public void setBasePath | (string $value )

Input
string | $value | the directory containing the application configuration file
Output
Exception

## setCache

public void setCache | (ICache $cache )

Input
ICache | $cache | the cache module
Output
Exception

## setConfigurationFile

public void setConfigurationFile | (string $value )

Input
string | $value | the application configuration file (absolute path)
Output
Exception

## setErrorHandler

public void setErrorHandler | (TErrorHandler $handler )

Input
TErrorHandler | $handler | the error handler module
Output
Exception

## setGlobalization

public void setGlobalization | (TGlobalization $glob )

Input
TGlobalization | $glob | globalization module
Output
Exception

## setGlobalState

public void setGlobalState | (string $key , mixed $value , mixed $defaultValue )

Sets a global value.

A global value is one that is persistent across users sessions and requests. Make sure that the value is serializable and unserializable.

Input
string | $key | the name of the value to be set
mixed | $value | the global value to be set
mixed | $defaultValue | the default value. If $key is not found, $defaultValue will be returned
Output
Exception

## setID

public void setID | (string $value )

Input
string | $value | application ID
Output
Exception

## setMode

public void setMode | (TApplicationMode $value )

Input
TApplicationMode | $value | application mode
Output
Exception

## setModule

public void setModule | (string $id , IModule $module )

Adds a module to application.

Note, this method does not do module initialization.

Input
string | $id | ID of the module
IModule | $module | module object
Output
Exception

## setPageServiceID

public void setPageServiceID | (string $value )

Input
string | $value | page service ID
Output
Exception

## setRequest

public void setRequest | (THttpRequest $request )

Input
THttpRequest | $request | the request module
Output
Exception

## setResponse

public void setResponse | (THttpResponse $response )

Input
THttpResponse | $response | the request module
Output
Exception

## setRuntimePath

public void setRuntimePath | (string $value )

Input
string | $value | the directory storing cache data and application-level persistent data. (absolute path)
Output
Exception

## setSecurityManager

public void setSecurityManager | (TSecurityManager $sm )

Input
TSecurityManager | $sm | the security manager module
Output
Exception

## setService

public void setService | (IService $value )

Input
IService | $value | the currently requested service
Output
Exception

## setSession

public void setSession | (THttpSession $session )

Input
THttpSession | $session | the session module
Output
Exception

## setUser

public void setUser | (IUser $user )

Input
IUser | $user | the application user
Output
Exception

## startService

public void startService | (string $serviceID )

Starts the specified service.

The service instance will be created. Its properties will be initialized and the configurations will be applied, if any.

Input
string | $serviceID | service ID
Output
Exception

Constant Details

### CONFIGCACHE_FILE

Config cache file

#### Type:

string

#### Value:

'config.cache'

### CONFIG_FILE

Application configuration file name

#### Type:

string

#### Value:

'application.xml'

### CONFIG_FILE_EXT

File extension for external config files

#### Type:

string

#### Value:

'.xml'

### GLOBAL_FILE

Global data file

#### Type:

string

#### Value:

'global.cache'

### PAGE_SERVICE_ID

Page service ID

#### Type:

string

#### Value:

'page'

### RUNTIME_PATH

Runtime directory name

#### Type:

string

#### Value:

'runtime'

### STATE_DEBUG

#### Type:

string

#### Value:

'Debug'

### STATE_NORMAL

#### Type:

string

#### Value:

'Normal'

### STATE_OFF

possible application mode.

#### Type:

string

#### Value:

'Off'
Deprecated: deprecated since version 3.0.4 (use TApplicationMode constants instead)

### STATE_PERFORMANCE

#### Type:

string

#### Value:

'Performance'