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:
Method Summary |
void
|
Applies an application configuration.
|
void
|
Clears a global value.
|
void
|
Completes current request processing.
|
void
|
Flushes output to client side.
|
IStatePersister
|
|
TAssetManager
|
|
TAuthorizationRuleCollection
|
|
string
|
|
ICache
|
|
string
|
|
TErrorHandler
|
|
TGlobalization
|
|
mixed
|
Returns a global value.
|
string
|
|
TApplicationMode
|
|
IModule
|
|
array
|
|
string
|
|
TMap
|
Returns the list of application parameters.
|
THttpRequest
|
|
boolean
|
|
THttpResponse
|
|
string
|
|
TSecurityManager
|
|
IService
|
|
THttpSession
|
|
string
|
|
IUser
|
|
protected
void
|
Loads configuration and initializes application.
|
protected
void
|
Loads global values from persistent storage.
|
void
|
Raises OnAuthentication event.
|
void
|
Raises OnAuthenticationComplete event.
|
void
|
Raises OnAuthorization event.
|
void
|
Raises OnAuthorizationComplete event.
|
void
|
Raises OnBeginRequest event.
|
void
|
Raises OnEndRequest event.
|
void
|
Raises OnError event.
|
void
|
Raises OnLoadState event.
|
void
|
Raises OnLoadStateComplete event.
|
void
|
Raises OnPreFlushOutput event.
|
void
|
Raises OnPreRunService event.
|
void
|
Raises OnSaveState event.
|
void
|
Raises OnSaveStateComplete event.
|
protected
void
|
Resolves application-relevant paths.
|
void
|
Executes the lifecycles of the application.
|
void
|
Runs the requested service.
|
protected
void
|
Saves global values into persistent storage.
|
void
|
|
void
|
|
void
|
|
void
|
|
void
|
|
void
|
|
void
|
|
void
|
Sets a global value.
|
void
|
|
void
|
|
void
|
Adds a module to application.
|
void
|
|
void
|
|
void
|
|
void
|
|
void
|
|
void
|
|
void
|
|
void
|
|
void
|
Starts the specified service.
|
Method Details |
applyConfiguration
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.
|
flushOutput
public void flushOutput |
() |
Flushes output to client side.
|
getApplicationStatePersister
|
getAssetManager
|
getAuthorizationRules
|
getBasePath
public string getBasePath |
() |
Output |
string
| the directory containing the application configuration file (absolute path) |
Exception |
|
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
|
getGlobalization
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
Output |
string
| application ID |
Exception |
|
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
|
getRequestCompleted
public boolean getRequestCompleted |
() |
Output |
boolean
| whether the current request is processed. |
Exception |
|
getResponse
|
getRuntimePath
public string getRuntimePath |
() |
Output |
string
| the directory storing cache data and application-level persistent data. (absolute path) |
Exception |
|
getSecurityManager
|
getService
Output |
IService
| the currently requested service |
Exception |
|
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
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.
|
onAuthentication
public void onAuthentication |
() |
Raises OnAuthentication event.
This method is invoked when the user request needs to be authenticated.
|
onAuthenticationComplete
public void onAuthenticationComplete |
() |
Raises OnAuthenticationComplete event.
This method is invoked right after the user request is authenticated.
|
onAuthorization
public void onAuthorization |
() |
Raises OnAuthorization event.
This method is invoked when the user request needs to be authorized.
|
onAuthorizationComplete
public void onAuthorizationComplete |
() |
Raises OnAuthorizationComplete event.
This method is invoked right after the user request is authorized.
|
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.
|
onEndRequest
public void onEndRequest |
() |
Raises OnEndRequest event.
This method is invoked when the application completes the processing of the request.
|
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).
|
onLoadStateComplete
public void onLoadStateComplete |
() |
Raises OnLoadStateComplete event.
This method is invoked right after the application state has been loaded.
|
onPreFlushOutput
public void onPreFlushOutput |
() |
Raises OnPreFlushOutput event.
This method is invoked right before the application flushes output to client.
|
onPreRunService
public void onPreRunService |
() |
Raises OnPreRunService event.
This method is invoked right before the service is to be run.
|
onSaveState
public void onSaveState |
() |
Raises OnSaveState event.
This method is invoked when the application needs to save state (probably stored in session).
|
onSaveStateComplete
public void onSaveStateComplete |
() |
Raises OnSaveStateComplete event.
This method is invoked right after the application state has been saved.
|
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
Executes the lifecycles of the application.
This is the main entry function that leads to the running of the whole Prado application.
|
runService
public void runService |
() |
Runs the requested service.
|
saveGlobals
protected void saveGlobals |
() |
Saves global values into persistent storage.
This method is invoked when OnSaveState event is raised.
|
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
|
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 |
|