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:

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: 
    1.  $application=new TApplication($configFile);
      2. 

    2.  $application->run();
      3.

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$configthe configuration
boolean$withinServicewhether 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$keythe 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$createIfNotExistswhether 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$keythe name of the value to be returned
mixed$defaultValuethe 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
string0configuration file path (absolute or relative to current executing script)
string1cache file path, empty if no present or needed
Output
Exception
throwsTConfigurationException 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$paramevent 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$basePaththe 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$persisterapplication state persister
Output
Exception

setAssetManager

public void setAssetManager (TAssetManager $value )

Input
TAssetManager$valueasset manager
Output
Exception

setBasePath

public void setBasePath (string $value )

Input
string$valuethe directory containing the application configuration file
Output
Exception

setCache

public void setCache (ICache $cache )

Input
ICache$cachethe cache module
Output
Exception

setConfigurationFile

public void setConfigurationFile (string $value )

Input
string$valuethe application configuration file (absolute path)
Output
Exception

setErrorHandler

public void setErrorHandler (TErrorHandler $handler )

Input
TErrorHandler$handlerthe error handler module
Output
Exception

setGlobalization

public void setGlobalization (TGlobalization $glob )

Input
TGlobalization$globglobalization 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$keythe name of the value to be set
mixed$valuethe global value to be set
mixed$defaultValuethe default value. If $key is not found, $defaultValue will be returned
Output
Exception

setID

public void setID (string $value )

Input
string$valueapplication ID
Output
Exception

setMode

public void setMode (TApplicationMode $value )

Input
TApplicationMode$valueapplication 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$idID of the module
IModule$modulemodule object
Output
Exception

setPageServiceID

public void setPageServiceID (string $value )

Input
string$valuepage service ID
Output
Exception

setRequest

public void setRequest (THttpRequest $request )

Input
THttpRequest$requestthe request module
Output
Exception

setResponse

public void setResponse (THttpResponse $response )

Input
THttpResponse$responsethe request module
Output
Exception

setRuntimePath

public void setRuntimePath (string $value )

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

setSecurityManager

public void setSecurityManager (TSecurityManager $sm )

Input
TSecurityManager$smthe security manager module
Output
Exception

setService

public void setService (IService $value )

Input
IService$valuethe currently requested service
Output
Exception

setSession

public void setSession (THttpSession $session )

Input
THttpSession$sessionthe session module
Output
Exception

setUser

public void setUser (IUser $user )

Input
IUser$userthe 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$serviceIDservice 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'