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:
IDataSource
IItemDataRenderer
IRepeatInfoUser
TActiveFileUpload
TBaseDataList
TBaseValidator
TBoundColumn
TBulletedList
TBulletedListDisplayMode
TBulletedListEventParameter
TBulletStyle
TButton
TButtonColumn
TButtonColumnType
TButtonType
TCaptcha
TCaptchaValidator
TCheckBox
TCheckBoxColumn
TCheckBoxList
TCircleHotSpot
TClientScript
TClientScriptLoader
TClientSideValidationSummaryOptions
TColorPicker
TColorPickerClientSide
TColorPickerMode
TCompareValidator
TCompleteWizardStep
TConditional
TContent
TContentDirection
TContentPlaceHolder
TCustomValidator
TDataBoundControl
TDataGrid
TDataGridColumn
TDataGridColumnCollection
TDataGridCommandEventParameter
TDataGridItem
TDataGridItemCollection
TDataGridItemEventParameter
TDataGridItemRenderer
TDataGridPageChangedEventParameter
TDataGridPager
TDataGridPagerButtonType
TDataGridPagerEventParameter
TDataGridPagerMode
TDataGridPagerPosition
TDataGridPagerStyle
TDataGridSortCommandEventParameter
TDataList
TDataListCommandEventParameter
TDataListItem
TDataListItemCollection
TDataListItemEventParameter
TDataListItemRenderer
TDataRenderer
TDataSourceControl
TDataSourceSelectParameters
TDataSourceView
TDataTypeValidator
TDatePicker
TDatePickerClientScript
TDatePickerInputMode
TDatePickerMode
TDatePickerPositionMode
TDisplayStyle
TDraggable
TDropContainer
TDropDownList
TDropDownListColumn
TEditCommandColumn
TEmailAddressValidator
TExpression
TFileUpload
TFont
THiddenField
THorizontalAlign
THotSpot
THotSpotCollection
THotSpotMode
THtmlArea
THtmlElement
THyperLink
THyperLinkColumn
TImage
TImageButton
TImageClickEventParameter
TImageMap
TImageMapEventParameter
TInlineFrame
TInlineFrameAlign
TInlineFrameScrollBars
TItemDataRenderer
TJavascriptLogger
TKeyboard
TLabel
TLinkButton
TListBox
TListControl
TListControlValidator
TListItem
TListItemCollection
TListItemType
TListSelectionMode
TLiteral
TLiteralColumn
TMarkdown
TMetaTag
TMetaTagCollection
TMultiView
TOutputCache
TOutputCacheCalculateKeyEventParameter
TOutputCacheCheckDependencyEventParameter
TPager
TPagerButtonType
TPagerMode
TPagerPageChangedEventParameter
TPanel
TPanelStyle
TPlaceHolder
TPolygonHotSpot
TRadioButton
TRadioButtonList
TRangeValidationDataType
TRangeValidator
TRatingList
TReadOnlyDataSource
TReadOnlyDataSourceView
TRectangleHotSpot
TRegularExpressionValidator
TRepeatDirection
TRepeater
TRepeaterCommandEventParameter
TRepeaterItem
TRepeaterItemCollection
TRepeaterItemEventParameter
TRepeaterItemRenderer
TRepeatInfo
TRepeatLayout
TRequiredFieldValidator
TSafeHtml
TScrollBars
TServerValidateEventParameter
TSlider
TSliderClientScript
TSliderDirection
TStatements
TStyle
TStyleSheet
TTable
TTableCaptionAlign
TTableCell
TTableCellCollection
TTableFooterRow
TTableGridLines
TTableHeaderCell
TTableHeaderRow
TTableHeaderScope
TTableItemStyle
TTableRow
TTableRowCollection
TTableRowSection
TTableStyle
TTabPanel
TTabView
TTabViewCollection
TTemplateColumn
TTemplatedWizardStep
TTextAlign
TTextBox
TTextBoxAutoCompleteType
TTextBoxMode
TTextHighlighter
TTextHighlighterLineNumberStyle
TValidationCompareOperator
TValidationDataType
TValidationSummary
TValidationSummaryDisplayMode
TValidationSummaryDisplayStyle
TValidatorClientSide
TValidatorDisplayStyle
TVerticalAlign
TView
TViewCollection
TWebControl
TWebControlAdapter
TWizard
TWizardFinishNavigationTemplate
TWizardNavigationButtonStyle
TWizardNavigationButtonType
TWizardNavigationContainer
TWizardNavigationEventParameter
TWizardNavigationTemplate
TWizardSideBarListItemTemplate
TWizardSideBarTemplate
TWizardStartNavigationTemplate
TWizardStep
TWizardStepCollection
TWizardStepNavigationTemplate
TWizardStepType
TXmlTransform
Keyword

Class TOutputCache

TComponent
   |
   --TApplicationComponent
      |
      --TControl
         |
         --TOutputCache

TOutputCache class.

TOutputCache enables caching a portion of a Web page, also known as partial caching. The content being cached can be either static or dynamic.

To use TOutputCache, simply enclose the content to be cached within the TOutputCache component tag on a template, e.g.,

  1. <com:TOutputCache>
  2. content to be cached
  3. </com:TOutputCache>
where content to be cached can be static text and/or component tags.

The validity of the cached content is determined based on two factors: the Duration and the cache dependency. The former specifies the number of seconds that the data can remain valid in cache (defaults to 60s), while the latter specifies conditions that the cached data depends on. If a dependency changes, (e.g. relevant data in DB are updated), the cached data will be invalidated.

There are two ways to specify cache dependency. One may write event handlers to respond to the OnCheckDependency event and set the event parameter's TOutputCacheCheckDependencyEventParameter::getIsValid property to indicate whether the cached data remains valid or not. One can also extend TOutputCache and override its getCacheDependency function. While the former is easier to use, the latter offers more extensibility.

The content fetched from cache may be variated with respect to some parameters. It supports variation with respect to request parameters, which is specified by VaryByParam property. If a specified request parameter is different, a different version of cached content is used. This is extremely useful if a page's content may be variated according to some GET parameters. The content being cached may also be variated with user sessions if VaryBySession is set true. To variate the cached content by other factors, override calculateCacheKey() method.

Output caches can be nested. An outer cache takes precedence over an inner cache. This means, if the content cached by the inner cache expires or is invalidated, while that by the outer cache not, the outer cached content will be used.

Note, TOutputCache is effective only for non-postback page requests and when cache module is enabled.

Do not attempt to address child controls of TOutputCache when the cached content is to be used. Use ContentCached property to determine whether the content is cached or not.

Since: 3.1
Author: Qiang Xue <qiang.xue@gmail.com>
Constants Inherited From TControl
AUTOMATIC_ID_PREFIX, CLIENT_ID_SEPARATOR, CS_CHILD_INITIALIZED, CS_CONSTRUCTED, CS_INITIALIZED, CS_LOADED, CS_PRERENDERED, CS_STATE_LOADED, ID_FORMAT, ID_SEPARATOR, IS_CHILD_CREATED, IS_CREATING_CHILD, IS_DISABLE_THEMING, IS_DISABLE_VIEWSTATE, IS_ID_SET, IS_SKIN_APPLIED, IS_STYLESHEET_APPLIED, RF_ADAPTER, RF_AUTO_BINDINGS, RF_CHILD_STATE, RF_CONTROLS, RF_CONTROLSTATE, RF_DATA_BINDINGS, RF_EVENTS, RF_NAMED_CONTROLS, RF_NAMED_CONTROLS_ID, RF_NAMED_OBJECTS, RF_SKIN_ID,

Method Summary
protected  string
Calculates the cache key.
void
getAllowChildControls ( boolean 0)
Returns a value indicating whether body contents are allowed for this control.
protected  string
protected  ICacheDependency
Returns the dependency of the data to be cached.
string
integer
boolean
boolean
integer
string
boolean
protected  void
initRecursive ( TControl $namingContainer)
Performs the Init step for the control and all its child controls.
protected  void
Performs the Load step for the control and all its child controls.
protected  void
loadStateRecursive ( array &$state, boolean $needViewState)
Loads state (viewstate and controlstate) into a control and its children.
void
This event is raised when the output cache is calculating cache key.
void
This event is raised when the output cache is checking cache dependency.
protected  void
Performs the PreRender step for the control and all its child controls.
void
registerAction ( string $context, string $funcName, array $funcParams)
Registers an action associated with the content being cached.
void
render ( THtmlWriter $writer)
Renders the output cache control.
protected  array
saveStateRecursive ( boolean $needViewState)
Saves all control state (viewstate and controlstate) as a collection.
void
setCacheKeyPrefix ( string $value)
Sets the prefix of the cache key.
void
setCacheModuleID ( string $value)
void
setCachingPostBack ( boolean $value)
Sets a value indicating whether cached output will be used on postback requests.
void
setDuration ( integer $value)
string
setVaryByParam ( mixed $value)
Sets the names of the request parameters that should be used in calculating the cache key.
void
setVaryBySession ( boolean $value)
Methods Inherited From TControl
TControl::addedControl(), TControl::addParsedObject(), TControl::addToPostDataLoader(), TControl::applyStyleSheetSkin(), TControl::autoBindProperty(), TControl::autoDataBindProperties(), TControl::bindProperty(), TControl::broadcastEvent(), TControl::bubbleEvent(), TControl::clearChildState(), TControl::clearControlState(), TControl::clearNamingContainer(), TControl::clearViewState(), TControl::convertUniqueIdToClientId(), TControl::createChildControls(), TControl::createControlCollection(), TControl::dataBind(), TControl::dataBindChildren(), TControl::dataBindProperties(), TControl::ensureChildControls(), TControl::findControl(), TControl::findControlsByID(), TControl::findControlsByType(), TControl::focus(), TControl::getAdapter(), TControl::getAllowChildControls(), TControl::getAttribute(), TControl::getAttributes(), TControl::getChildControlsCreated(), TControl::getClientID(), TControl::getControls(), TControl::getControlStage(), TControl::getControlState(), TControl::getCustomData(), TControl::getEnabled(), TControl::getEnableTheming(), TControl::getEnableViewState(), TControl::getHasAdapter(), TControl::getHasAttributes(), TControl::getHasChildInitialized(), TControl::getHasControls(), TControl::getHasInitialized(), TControl::getHasLoaded(), TControl::getHasLoadedPostData(), TControl::getHasPreRendered(), TControl::getID(), TControl::getNamingContainer(), TControl::getPage(), TControl::getParent(), TControl::getRegisteredObject(), TControl::getSkinID(), TControl::getSourceTemplateControl(), TControl::getTemplateControl(), TControl::getUniqueID(), TControl::getViewState(), TControl::getVisible(), TControl::hasAttribute(), TControl::initRecursive(), TControl::isDescendentOf(), TControl::isObjectRegistered(), TControl::loadRecursive(), TControl::loadState(), TControl::loadStateRecursive(), TControl::onDataBinding(), TControl::onInit(), TControl::onLoad(), TControl::onPreRender(), TControl::onUnload(), TControl::preRenderRecursive(), TControl::raiseBubbleEvent(), TControl::registerObject(), TControl::removeAttribute(), TControl::removedControl(), TControl::render(), TControl::renderChildren(), TControl::renderControl(), TControl::saveState(), TControl::saveStateRecursive(), TControl::setAdapter(), TControl::setAttribute(), TControl::setChildControlsCreated(), TControl::setControlStage(), TControl::setControlState(), TControl::setCustomData(), TControl::setEnabled(), TControl::setEnableTheming(), TControl::setEnableViewState(), TControl::setID(), TControl::setPage(), TControl::setSkinID(), TControl::setTemplateControl(), TControl::setViewState(), TControl::setVisible(), TControl::trackViewState(), TControl::traverseChildControls(), TControl::unbindProperty(), TControl::unloadRecursive(), TControl::unregisterObject(), TControl::__get()
Methods Inherited From TApplicationComponent
TApplicationComponent::getApplication(), TApplicationComponent::getRequest(), TApplicationComponent::getResponse(), TApplicationComponent::getService(), TApplicationComponent::getSession(), TApplicationComponent::getUser(), TApplicationComponent::publishAsset(), TApplicationComponent::publishFilePath()
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 CACHE_ID_PREFIX

Method Details

calculateCacheKey

protected string calculateCacheKey ()

Calculates the cache key.

The key is calculated based on the unique ID of this control and the request parameters specified via VaryByParam. If VaryBySession is true, the session ID will also participate in the key calculation. This method may be overriden to support other variations in the calculated cache key.

Output
string cache key
Exception

getAllowChildControls

public void getAllowChildControls (boolean 0 )

Returns a value indicating whether body contents are allowed for this control.

This method overrides the parent implementation by checking if cached content is available or not. If yes, it returns false, otherwise true.

Input
boolean0whether body contents are allowed for this control.
Output
Exception

getBaseCacheKey

protected string getBaseCacheKey ()

Output
string basic cache key without variations
Exception

getCacheDependency

protected ICacheDependency getCacheDependency ()

Returns the dependency of the data to be cached.

The default implementation simply returns null, meaning no specific dependency. This method may be overriden to associate the data to be cached with additional dependencies.

Output
Exception

getCacheModuleID

public string getCacheModuleID ()

Output
string the ID of the cache module. Defaults to '', meaning the primary cache module is used.
Exception

getCacheTime

public integer getCacheTime ()

Output
integer the timestamp of the cached content. This is only valid if the content is being cached.
Exception

getCachingPostBack

public boolean getCachingPostBack ()

Output
boolean whether cached output will be used on postback requests. Defaults to false.
Exception

getContentCached

public boolean getContentCached ()

Output
boolean whether content enclosed is cached or not
Exception

getDuration

public integer getDuration ()

Output
integer number of seconds that the data can remain in cache. Defaults to 60 seconds. Note, if cache dependency changes or cache space is limited, the data may be purged out of cache earlier.
Exception

getVaryByParam

public string getVaryByParam ()

Output
string a semicolon-separated list of strings used to vary the output cache. Defaults to ''.
Exception

getVaryBySession

public boolean getVaryBySession ()

Output
boolean whether the content being cached should be differentiated according to user sessions. Defaults to false.
Exception

initRecursive

protected void initRecursive (TControl $namingContainer )

Performs the Init step for the control and all its child controls.

This method overrides the parent implementation by setting up the stack of the output cache in the page. Only framework developers should use this method.

Input
TControl$namingContainerthe naming container control
Output
Exception

loadRecursive

protected void loadRecursive (TControl 0 )

Performs the Load step for the control and all its child controls.

This method overrides the parent implementation by setting up the stack of the output cache in the page. If the data is restored from cache, it also recovers the actions associated with the cached data. Only framework developers should use this method.

Input
TControl0the naming container control
Output
Exception

loadStateRecursive

protected void loadStateRecursive (array &$state , boolean $needViewState )

Loads state (viewstate and controlstate) into a control and its children.

This method overrides the parent implementation by loading cached state if available. This method should only be used by framework developers.

Input
array&$statethe collection of the state
boolean$needViewStatewhether the viewstate should be loaded
Output
Exception

onCalculateKey

public void onCalculateKey (TOutputCacheCalculateKeyEventParameter $param )

This event is raised when the output cache is calculating cache key.

By varying cache keys, one can obtain different versions of cached content. An event handler may be written to add variety of the key calculation. The value set in TOutputCacheCalculateKeyEventParameter::setCacheKey of this event parameter will be appended to the default key calculation scheme.

Input
TOutputCacheCalculateKeyEventParameter$paramevent parameter
Output
Exception

onCheckDependency

public void onCheckDependency (TOutputCacheCheckDependencyEventParameter $param )

This event is raised when the output cache is checking cache dependency.

An event handler may be written to check customized dependency conditions. The checking result should be saved by setting TOutputCacheCheckDependencyEventParameter::setIsValid property of the event parameter (which defaults to true).

Input
TOutputCacheCheckDependencyEventParameter$paramevent parameter
Output
Exception

preRenderRecursive

protected void preRenderRecursive (TControl 0 )

Performs the PreRender step for the control and all its child controls.

This method overrides the parent implementation by setting up the stack of the output cache in the page. Only framework developers should use this method.

Input
TControl0the naming container control
Output
Exception

registerAction

public void registerAction (string $context , string $funcName , array $funcParams )

Registers an action associated with the content being cached.

The registered action will be replayed if the content stored in the cache is served to end-users.

Input
string$contextcontext of the action method. This is a property-path referring to the context object (e.g. Page, Page.ClientScript)
string$funcNamemethod name of the context object
array$funcParamslist of parameters to be passed to the action method
Output
Exception

render

public void render (THtmlWriter $writer )

Renders the output cache control.

This method overrides the parent implementation by capturing the output from its child controls and saving it into cache, if output cache is needed.

Input
THtmlWriter$writer
Output
Exception

saveStateRecursive

protected array saveStateRecursive (boolean $needViewState )

Saves all control state (viewstate and controlstate) as a collection.

This method overrides the parent implementation by saving state into cache if needed. This method should only be used by framework developers.

Input
boolean$needViewStatewhether the viewstate should be saved
Output
array the collection of the control state (including its children's state).
Exception

setCacheKeyPrefix

public void setCacheKeyPrefix (string $value )

Sets the prefix of the cache key.

This method is used internally by TTemplate.

Input
string$valuekey prefix
Output
Exception

setCacheModuleID

public void setCacheModuleID (string $value )

Input
string$valuethe ID of the cache module. If empty, the primary cache module will be used.
Output
Exception

setCachingPostBack

public void setCachingPostBack (boolean $value )

Sets a value indicating whether cached output will be used on postback requests.

By default, this is disabled. Be very cautious when enabling it. If the cached content including interactive user controls such as TTextBox, TDropDownList, your page may fail to render on postbacks.

Input
boolean$valuewhether cached output will be used on postback requests.
Output
Exception

setDuration

public void setDuration (integer $value )

Input
integer$valuenumber of seconds that the data can remain in cache. If 0, it means data is not cached.
Output
Exception
throwsTInvalidDataValueException if the value is smaller than 0.

setVaryByParam

public string setVaryByParam (mixed $value )

Sets the names of the request parameters that should be used in calculating the cache key.

The names should be concatenated by semicolons. By setting this value, the output cache will use different cached data for each different set of request parameter values.

Input
mixed$value
Output
string a semicolon-separated list of strings used to vary the output cache.
Exception

setVaryBySession

public void setVaryBySession (boolean $value )

Input
boolean$valuewhether the content being cached should be differentiated according to user sessions.
Output
Exception


Constant Details

CACHE_ID_PREFIX

Type:

string

Value:

'prado:outputcache'