Package 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<String, HstComponentConfiguration>, 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 ParameterConfiguration.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.

    • 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

      • 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

      • 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 for components are inherited from ancestor configurations. In case the component configured a parameter also present on an ancestor, the parameter from the ancestor is ignored

        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

      • getDynamicComponentParameters

        default List<DynamicParameter> getDynamicComponentParameters()
        Returns the list of all named and residual component parameters
        Returns:
        the list of all named and residual component parameters, and an empty list if no parameters present

      • getFieldGroups

        List<DynamicFieldGroup> getFieldGroups()
        Returns the list of a component's field groups
        Returns:

      • getComponentDefinition

        String getComponentDefinition()
        Returns a reference to a catalog item
        Returns:
        a reference to a catalog item

      • getDynamicComponentParameter

        default Optional<DynamicParameter> getDynamicComponentParameter​(String name)
        Returns an optional of the component parameter(named or residual) that has the specified name
        Returns:
        an optional of the component parameter(named or residual) that has the specified name, and an empty optional if nothing found

      • 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

      • 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. For XPage document based HstComponentConfiguration instances, this returns all the 'mount variants' PLUS possibly the variants for the XPage Document container items if they are present

      • 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

      • 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

      • getCType

        String getCType()
        Allows to 'map' a specific component (catalog item type) to their implementation logic.

      • 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

      • getHstTemplate

        String getHstTemplate()
        Returns:
        the hst template property if available

      • getHippoIdentifier

        String getHippoIdentifier()

        In case the component has a hippo:identifier, it is returned. Typically, an hst:containercomponent will have an autocreated hippo:identifier with as value a uuid: This can be used a stable identifier across different (versions) of the same node, for example for an HST Config branch it can have the same value (opposed to the uuid of the node) and across unpublished/published versions below a document variant the xpage containers can have a stable uuid

        Returns:
        the hippo identifier if available for this HstComponentConfiguration, otherwise null

      • isExperiencePageComponent

        boolean isExperiencePageComponent()
        Returns:
        true if this component is part of a component STORED below an experience page document variant

      • isUnresolvedXpageLayoutContainer

        boolean isUnresolvedXpageLayoutContainer()
        Returns:
        true if this is a container component AND is part of a request based XPage config but comes from an XPage Layout since the XPage document does not have a representation of the container : in that case, very specific Channel Mgr behavior and page-composer behavior is needed: when an item is added to the container, the container should be CREATED in the XPage document

      • isHidden

        boolean isHidden()
        true if this catalog item should be hidden in channel manager