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 Details

    • 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:

  • Method Details

    • 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

      String getNamedRenderer()
      Returns:
      the name of the renderer, when using named servlet. Returns null when getRenderPath() does not return null
      See Also:

    • 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:

    • 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

    • 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

    • 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

    • 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. 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

    • 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

    • getCType

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

    • 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, aka an HstNode belonging to a different hst:configuration tree than this HstComponentConfiguration

    • isShared

      boolean isShared()
      Returns:
      true when the backing provider (HstNode) of this HstComponentConfiguration is most likely / can be shared with other HstComponentConfiguration instances

    • isPrototype

      boolean isPrototype()
      Returns:
      true when this HstComponentConfiguration can be used as a prototype to create other HstComponentConfigurations with

    • 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

    • 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.

    • 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

    • flattened

      default Stream<HstComponentConfiguration> flattened()
      Returns:
      a depth-first stream of this HstComponentConfiguration plus its descendants