org.hippoecm.hst.configuration.components

Interface HstComponentConfiguration

All Superinterfaces:

HstComponentInfo

public interface HstComponentConfiguration
extends HstComponentInfo

A HstComponentConfiguration specifies a (Java) componentClassName implementing the HstComponent interface to provide the actual behavior for content rendering and (inter)action processing.

Furthermore, a HstComponentConfiguration can have child HstComponentConfiguration elements which are identified by a referenceName. This referenceName can be used by the HstComponent and its renderer to access its children request state and include their rendering output within its own rendering output. This referenceName is also use to build up a unique referencePath to identify a specific HstComponent within the whole tree of the HstComponent elements within the current request. It is up to the implementation to if this referenceName needs to be configured, or is auto-created. The constraint to the referenceName is that is MUST be unique for sibbling HstComponentConfiguration's. Implementations auto-creating the referenceName can better use a deterministic algorithm to make sure that the same configuration results in the same auto-created referenceName's, to avoid the need of sticky sessions in a clustered environment. Though, this is up to the implementation.

The referencePath is derived automatically by prepending a HstComponentConfiguration its parent referencePath to the referenceName, separated by a configurable character. As a HstComponent its referencePath is furthermore used to uniquely (prefix) request parameters which might end up in an external URL, a referenceName is not allowed to contain any of the following characters (bracket not included): [.,:/\'"?& |-+#$%~]

For a root HstComponentConfiguration however, the HstComponent referencePath will only contain the (root) ".", not its own referenceName which is simply ignored, and as such there is no restriction on which characters are used for it (or even that it has a value).

A root HstComponentConfiguration on the other hand is required to have an id, uniquely identifying it among other root HstComponentConfiguration objects. This id is used for lookup from the HstComponentsConfiguration and as reference by a HstSiteMapItem.

A HstComponentConfiguration provides access to its children through a LinkedHashMap, allowing the HST2 runtime to look them up by referenceName and/or referencePath, as well as process them in a sorted order. As the ordering in which HstComponent children are processed might be significant, the HstComponentConfiguration implementation is required to use a LinkedHashMap implementation (like a TreeMap) which returns the children in the order of the configuration/creation (not the "natural" ordering based only on the referenceName).

A HstComponentConfiguration may define a rendererPath to a view renderer (resource) which is a web application context relative (possibly servlet) path to be dispatched to during rendering, for example pointing to a JSP file, or maybe a script (like Velocity/Freemarker) to be "executed". Note: to allow repository based/stored renderer scripts, a prefix might be used for indicating scripts that live in the repository. This is up to the implementation to provide.

Finally, a HstComponentConfiguration may have additional parameters which are meaningful for its actual HstComponent implementation, which are provided as a simple map, accessible through getParameters(). The actual HstComponent will access the HstComponentConfiguration through ComponentConfiguration.getParameter(String, org.hippoecm.hst.core.request.ResolvedSiteMapItem) that can manipulate the parameter values. For example, the implementation can use some 'property placeholder' to be resolved for the request. Typically, an HstComponent might be interested in some parameters from the matched HstSiteMapItem item. Suppose the matched HstSiteMapItem has a parameter name foo with value bar, then a HstComponentConfiguration could have a parameter name called lux with value ${foo}. The runtime HstComponent fetching the parameter lux could then get the resolved value bar returned from the matched HstSiteMapItem. Obviously, the HstSiteMapItem could also have the value ${1} where ${1} might first be substituted by the matched wildcard in the HstSiteMapItem. Obviously, this is all up to the implementation whether to support this.

NOTE: As HstComponent instances can access HstComponentConfiguration instances but should not be able to modify them, implementations must make sure that through the api a HstComponentConfiguration instance cannot be changed. Returned List and Map should be therefore unmodifiable.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	HstComponentConfiguration.Type A HstComponentConfiguration comes in three different main types.

Field Summary

Fields

Modifier and Type	Field and Description
static char	PARAMETER_PREFIX_NAME_DELIMITER The delimiter that is used between the parametername and the parameterprefix when there is a prefix value

Method Summary

Modifier and Type	Method and Description
default Stream<HstComponentConfiguration>	flattened()
String	getCanonicalIdentifier() Returns the identifier of the backing stored component configuration.
String	getCanonicalStoredLocation() Returns the canonical (real physical) location of the stored configuration of this HstComponentConfiguration
HstComponentConfiguration	getChildByName(String name) Returns the child HstComponentConfiguration by its name, or null if it doens't exist
Map<String,HstComponentConfiguration>	getChildren() Implementations should return an unmodifiable linked map, for example Collections.unmodifiableMap(java.util.Map<? extends K, ? extends V>) to avoid client code changing configuration
String	getComponentFilterTag() The filter tag (see HstRequestContext.getComponentFilterTags()) for this component.
HstComponentConfiguration.Type	getComponentType()
String	getIconPath()
String	getLabel()
Calendar	getLastModified()
String	getLocalParameter(String name) Returns the parameter value without inheritance for the parameter name and null if not present.
Map<String,String>	getLocalParameters() see getParameter(String), but now only parameters directly present on the HstConfigurationItem are returned.
List<String>	getMountVariants() This method returns all getParameterPrefixes() for the entire Mount combined
String	getNamedRenderer()
String	getNamedResourceServer()
String	getPageErrorHandlerClassName()
String	getParameter(String name) Returns the parameter value for the parameter name and null if not present.
Set<String>	getParameterPrefixes() Parameters can have prefixes (variant).
Map<String,String>	getParameters() Returns the map of all parameters.
HstComponentConfiguration	getParent() Returns the parent HstComponentConfiguration for this this component or null if a root component.
String	getReferenceName() Return the referenceName of this HstComponentConfiguration.
String	getRenderPath()
String	getServeResourcePath()
List<String>	getVariants() This method returns getParameterPrefixes() for the entire composite tree of descendant components including the current component
String	getXType()
boolean	isInherited()
boolean	isMarkedDeleted() true when this HstComponentConfiguration is marked as deleted.
boolean	isPrototype()

Methods inherited from interface org.hippoecm.hst.configuration.components.HstComponentInfo

getAsyncMode, getComponentClassName, getId, getName, isAsync, isCompositeCacheable, isStandalone, isSuppressWasteMessage

Field Detail

PARAMETER_PREFIX_NAME_DELIMITER

static final char PARAMETER_PREFIX_NAME_DELIMITER

The delimiter that is used between the parametername and the parameterprefix when there is a prefix value

See Also:

Constant Field Values

Method Detail

getParent

HstComponentConfiguration getParent()

Returns the parent HstComponentConfiguration for this this component or null if a root component.

getReferenceName

String getReferenceName()

Return the referenceName of this HstComponentConfiguration. It must be unique amongst sibling HstComponentConfiguration's. The value returned by this method, is the value that will occur as part of the referencePath in request parameter names

Returns:

the referenceName this HstComponentConfiguration, unique amongst its siblings

getRenderPath

String getRenderPath()

Returns:

the location of the view renderer. Returns null when getNamedRenderer() does not return null

See Also:

getNamedRenderer()

getNamedRenderer

String getNamedRenderer()

Returns:

the name of the renderer, when using named servlet. Returns null when getRenderPath() does not return null

See Also:

getRenderPath()

getServeResourcePath

String getServeResourcePath()

Returns:

return the servletpath of the servlet that must serve the resources for this HstComponent

getNamedResourceServer

String getNamedResourceServer()

Returns:

the name of the resource server, when using named servlet. Returns null when getServeResourcePath() does not return null

See Also:

getServeResourcePath()

getPageErrorHandlerClassName

String getPageErrorHandlerClassName()

Returns:

the fully classified className of the class implementing PageErrorHandler or null when not configured

getParameter

String getParameter(String name)

Returns the parameter value for the parameter name and null if not present. Note that from the HstComponentConfiguration always 'raw' parameters are returned. 'Raw' as in unresolved with respect to property placeholders. So, a value might be ${year} or ${1}. In a HstComponent instance, the implementation might have implemented some resolving for these values.

Parameters are inherited from ancestor configurations. Parameters that are configured in an ancestor override parameters configured in this component. Ancestors have precedence. Note that this is opposite to HstSiteMapItem.getParameter(String)

Parameters:

name - the name of the parameter

Returns:

the configured parameter value for this name and null if not existing

getLocalParameter

String getLocalParameter(String name)

Returns the parameter value without inheritance for the parameter name and null if not present. It returns the parameters configured directly on this HstComponentConfiguration, without the merged parameters from parent components (which have precedence, see getParameter(String))

Parameters:

name - the name of the parameter

Returns:

the configured parameter value for this name and null if not existing

getParameters

Map<String,String> getParameters()

Returns the map of all parameters. Also see getParameter(String). Implementations should return an unmodifiable map, for example Collections.unmodifiableMap(java.util.Map<? extends K, ? extends V>) to avoid client code changing configuration

Parameters are inherited from ancestor configurations. Parameters that are configured in an ancestor override parameters configured in this component. Ancestors have precedence. Note that this is opposite to HstSiteMapItem.getParameters()

Returns:

the map of all configured parameters, and an empty map if no parameters present

getParameterPrefixes

Set<String> getParameterPrefixes()

Parameters can have prefixes (variant). If there are prefixes in used, this method returns the (possibly unmodifiable) Set of prefixes / variants in use. Only the prefixes/variants on the current component are returned, thus not for descendant components like getVariants() does.

Returns:

the Set of available prefixes for all available parameters and if no prefixes in use, returns an Empty Set

getVariants

List<String> getVariants()

This method returns getParameterPrefixes() for the entire composite tree of descendant components including the current component

Returns:

the List of all unique variants for this HstComponentConfiguration plus all the variants of all its descendant HstComponentConfigurations. If no variants are present, and EMPTY List is returned.

getMountVariants

List<String> getMountVariants()

This method returns all getParameterPrefixes() for the entire Mount combined

Returns:

the List of all unique variants for this Mount. If no variants are present, an empty list is returned.

getLocalParameters

Map<String,String> getLocalParameters()

see getParameter(String), but now only parameters directly present on the HstConfigurationItem are returned. Thus, no inheritance by parents involved

Returns:

the map of all configured parameters, and an empty map if no parameters present

getChildren

Map<String,HstComponentConfiguration> getChildren()

Implementations should return an unmodifiable linked map, for example Collections.unmodifiableMap(java.util.Map<? extends K, ? extends V>) to avoid client code changing configuration

Returns:

all HstComponentConfiguration children in order they were added, and an empty Map if no children present

getChildByName

HstComponentConfiguration getChildByName(String name)

Returns the child HstComponentConfiguration by its name, or null if it doens't exist

Parameters:

name - the name of the child HstComponentConfiguration

getCanonicalStoredLocation

String getCanonicalStoredLocation()

Returns the canonical (real physical) location of the stored configuration of this HstComponentConfiguration

Returns:

the canonical location where the configuration is stored

getCanonicalIdentifier

String getCanonicalIdentifier()

Returns the identifier of the backing stored component configuration. Note that multiple HstComponentConfiguration's can share the same canonical identifier due to inheritance. Also, multiple subsites can share the same backing configuration, and thus share the same canonical identifiers

Returns:

the identifier of the backing stored component configuration

getXType

String getXType()

Returns:

the xtype of this ComponentConfiguration and null if the component does not have an xtype

getComponentType

HstComponentConfiguration.Type getComponentType()

Returns:

the HstComponentConfiguration.Type of this component

getComponentFilterTag

String getComponentFilterTag()

The filter tag (see HstRequestContext.getComponentFilterTags()) for this component.

Returns:

the filter tag of this component, or null if no tag is available.

isInherited

boolean isInherited()

Returns:

true when the backing provider (HstNode) of this HstComponentConfiguration is inherited

isPrototype

boolean isPrototype()

Returns:

true when this HstComponentConfiguration can be used as a prototype to create other HstComponentConfigurations with

getLabel

String getLabel()

Returns:

the label if present and null otherwise

getIconPath

String getIconPath()

Returns:

the icon path if present and null otherwise. The iconPath should be a path relative to the site webapp

getLastModified

Calendar getLastModified()

Returns:

if Calendar time this component got changed for the last time or null if not available

isMarkedDeleted

boolean isMarkedDeleted()

true when this HstComponentConfiguration is marked as deleted. An HstComponentConfiguration that has an ancestor that is marked as deleted will itself also be marked as deleted. A marked deleted component item will be part of the HST model via HstComponentsConfiguration.getComponentConfigurations() but should be skipped during execution.

Returns:

true when this HstComponentConfiguration is marked as deleted.

flattened

default Stream<HstComponentConfiguration> flattened()

Returns:

a depth-first stream of this HstComponentConfiguration plus its descendants