Parameters are of great importance to programming as they act as the primary mean of inbound communication with the application. On web applications, parameters are particularly relevant since they are the way to modify the application's behavior on behalf of the user's interaction.
As a web application oriented framework, DiF supports parameter management as well. HTTP Requests like the following are subject to a lot of trouble in parameter conversion, validation, persistence in diferent scopes (session, request, etc). \
http://server.com/appcontext/servlet?param1=value¶m2=value...
All this is boilerplate code that we repeatedly need to create, and that is a source of programming errors or non-standardized behaviors.
DiF tries to save all this trouble from the developer.
This section explains DiF's parameter offer.
There are four possible domains, or scopes, for a given parameter value. These scopes affect the value availability and persistence.
The scopes are defined by the ParameterScope enumeration and can assume the following values:
These scopes meanings are more or less straightforward, but nevertheless attend the following remarks.
A Request parameter value ceases to exist after the request is served. That is after the Stage runs and returns it's results.
Session parameter values live between requests of the same session. If the user looses it's session (either by logging out or by some server-related issue) the parameter value is reset.
Static parameter values must be used with caution because if a given user's instance modifies it's value every other user will see the new value on the next parameter access. It's the same behavior as Java's own static fields and MUST be only be applied in attributes of this type! Hence the name used.
!! TODO Validate parameter behavior on redirection
Under the hood the parameter mechanism uses the Parameter Manager services. The manager takes care of parameter access and persistence acting like a central repository. The following graphic depicts the way the Dispatcher accesses the parameter values on the different scopes. Take a note that the dispatcher always searches for the parameter value on the request. This is done to allow the user to force the parameter value on the request, thus permitting parameter value to be overridden. If the parameter value is not forced on the request, the dispatcher tries to fetch the value from the appropriate location/scope, falling back on the parameter for the default value if none of the previous fetchings succeeds.
Parameters have a complex life cycle with several different phases.
The parameter manager is the entity responsible for controlling parameter operations. It keeps track of scopes, validation rules, persistence and type conversions.
It's the manager that supplies the parameter values to the Stage and that stores the values if they're modified.
The following diagram shows the parameter life cycle in detail. It depicts the situation where the parameter value is forced by the user, which is the most complex situation. The diagram will be explained in detail below.
The user makes a request, forcing the parameter value.
The request is forward to the Dispatcher by the ChAL.
The Dispatcher retrieves the Stage from the DEMRegistry and creates a new instance.
Upon Stage initialization the parameters are requested to the parameter manager which fetches their values from the appropriate context and validates the usage constraints. Prior to this, the manager checks the request to find if the parameter values were overridden by the user. If so, the forced values are passed to the Stage. See the parameter scope section above for the complete parameter retrieval cycle.
By now, the parameter value is available on the stage. The business logic is executed and the parameter value might be changed. The parameter might also be updated during the business object finalization. The last stage of Stage finalization is the parameter value update on the manager. Once again, there's a constraint validation by the manager. If the validation succeeds the values are stored on the appropriate repositories. The storage step is what makes the parameter value available on the different scopes. Once the Stage execution is terminated the parameter values persist (based on scope) and the execution flow proceeds to the view rendering step.
In essence, parameters are variables. As such, and being Java a statically-typed language, parameters must have types. At the time of this writing DiF supports the following parameter types:
DiF manages parameter types and converts between them as necessary.
Parameters can have validation rules associated. These rules are named constraints.
When the parameter value is set, the new value is validated against the defined constraints. Constraints might be specific for some parameter types. Some constraints must be used with other constraints.
The following list shows the supported parameter constraints:
See this page for more information on constraints and parameter usage.