org.apache.struts2.components

## Class Component

- java.lang.Object
- - org.apache.struts2.components.Component

- Direct Known Subclasses:
    ContextBean, Else, ElseIf, I18n, If, Include, OptGroup, Param, Property, Push, UIBean

      public class Component
      extends Object

  Base class to extend for UI components.
  This class is a good extension point when building reusable UI components.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected ActionMapper` | `actionMapper`
    `static String` | `COMPONENT_STACK`
    `protected boolean` | `devMode`
    `protected boolean` | `escapeHtmlBody`
    `protected Map<String,Object>` | `parameters`
    `protected boolean` | `performClearTagStateForTagPoolingServers`
    `protected ValueStack` | `stack`
    `protected static ConcurrentMap<Class<?>,Collection<String>>` | `standardAttributesMap` Caches information about common tag's attributes to reduce scanning for annotation @StrutsTagAttribute
    `protected boolean` | `throwExceptionOnELFailure`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Component(ValueStack stack)` Constructor.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addAllParameters(Map<String,Object> params)` Adds all the given parameters to this component's own parameters.
    `void` | `addParameter(String key, Object value)` Adds the given key and value to this component's own parameter.
    `protected String` | `completeExpression(String expr)` Adds the surrounding %{ } to the expression for proper processing.
    `void` | `copyParams(Map<String,Object> params)` Pushes this component's parameter Map as well as the component itself on to the stack and then copies the supplied parameters over.
    `protected String` | `determineActionURL(String action, String namespace, String method, javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res, Map<String,Object> parameters, String scheme, boolean includeContext, boolean encodeResult, boolean forceAddSchemeHostAndPort, boolean escapeAmp)` Renders an action URL by consulting the `ActionMapper`.
    `protected String` | `determineNamespace(String namespace, ValueStack stack, javax.servlet.http.HttpServletRequest req)` Determines the namespace of the current page being renderdd.
    `boolean` | `end(Writer writer, String body)` Callback for the end tag of this component.
    `protected boolean` | `end(Writer writer, String body, boolean popComponentStack)` Callback for the start tag of this component.
    `boolean` | `escapeHtmlBody()` Override to set if body content should be HTML-escaped.
    `protected StrutsException` | `fieldError(String field, String errorMsg, Exception e)` Constructs a `RuntimeException` based on the given information.
    `protected Component` | `findAncestor(Class<?> clazz)` Finds the nearest ancestor of this component stack.
    `protected String` | `findString(String expr)` Evaluates the OGNL stack to find a String value.
    `protected String` | `findString(String expr, String field, String errorMsg)` Evaluates the OGNL stack to find a String value.
    `protected Object` | `findValue(String expression)` Finds a value from the OGNL stack based on the given expression.
    `protected Object` | `findValue(String expression, Class<?> toType)` Evaluates the OGNL stack to find an Object of the given type.
    `protected Object` | `findValue(String expr, String field, String errorMsg)` Evaluates the OGNL stack to find an Object value.
    `Stack<Component>` | `getComponentStack()` Gets the component stack of this component.
    `protected String` | `getNamespace(ValueStack stack)`
    `Map<String,Object>` | `getParameters()` Gets the parameters.
    `boolean` | `getPerformClearTagStateForTagPoolingServers()`
    `ValueStack` | `getStack()` Gets the OGNL value stack associated with this component.
    `protected Collection<String>` | `getStandardAttributes()` If needed caches all methods annotated by given annotation to avoid further scans
    `protected boolean` | `isAcceptableExpression(String expression)` Checks if expression doesn't contain vulnerable code
    `boolean` | `isValidTagAttribute(String attrName)` Checks if provided name is a valid tag's attribute
    `protected void` | `popComponentStack()` Pops the component stack.
    `void` | `setActionMapper(ActionMapper mapper)`
    `void` | `setDevMode(String devMode)`
    `void` | `setEscapeHtmlBody(String escapeHtmlBody)`
    `void` | `setNotExcludedAcceptedPatterns(NotExcludedAcceptedPatternsChecker notExcludedAcceptedPatterns)`
    `void` | `setPerformClearTagStateForTagPoolingServers(boolean performClearTagStateForTagPoolingServers)` Request that the tag state be cleared during `StrutsBodyTagSupport.doEndTag()` processing, which may help with certain edge cases with tag logic running on servers that implement JSP Tag Pooling.
    `void` | `setThrowExceptionsOnELFailure(String throwException)`
    `void` | `setUrlHelper(UrlHelper urlHelper)`
    `boolean` | `start(Writer writer)` Callback for the start tag of this component.
    `protected String` | `stripExpression(String expression)` If %{...} is applied, simply strip the "%{" and "}" off.
    `protected String` | `toString(Throwable t)` Constructs a string representation of the given exception.
    `boolean` | `usesBody()` Overwrite to set if body should be used.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### COMPONENT_STACK

          public static final String COMPONENT_STACK

      See Also:
        Constant Field Values

    - #### standardAttributesMap

          protected static ConcurrentMap<Class<?>,Collection<String>> standardAttributesMap

      Caches information about common tag's attributes to reduce scanning for annotation @StrutsTagAttribute

    - #### devMode

          protected boolean devMode

    - #### escapeHtmlBody

          protected boolean escapeHtmlBody

    - #### stack

          protected ValueStack stack

    - #### parameters

          protected Map<String,Object> parameters

    - #### actionMapper

          protected ActionMapper actionMapper

    - #### throwExceptionOnELFailure

          protected boolean throwExceptionOnELFailure

    - #### performClearTagStateForTagPoolingServers

          protected boolean performClearTagStateForTagPoolingServers

  - ### Constructor Detail

    - #### Component

          public Component(ValueStack stack)

      Constructor.
      Parameters:
        `stack` - OGNL value stack.

  - ### Method Detail

    - #### setDevMode

          public void setDevMode(String devMode)

    - #### setActionMapper

          public void setActionMapper(ActionMapper mapper)

    - #### setThrowExceptionsOnELFailure

          public void setThrowExceptionsOnELFailure(String throwException)

    - #### setEscapeHtmlBody

          public void setEscapeHtmlBody(String escapeHtmlBody)

    - #### setUrlHelper

          public void setUrlHelper(UrlHelper urlHelper)

    - #### setNotExcludedAcceptedPatterns

          public void setNotExcludedAcceptedPatterns(NotExcludedAcceptedPatternsChecker notExcludedAcceptedPatterns)

    - #### getStack

          public ValueStack getStack()

      Gets the OGNL value stack associated with this component.
      Returns:
        the OGNL value stack associated with this component.

    - #### getComponentStack

          public Stack<Component> getComponentStack()

      Gets the component stack of this component.
      Returns:
        the component stack of this component, never `null`.

    - #### start

          public boolean start(Writer writer)

      Callback for the start tag of this component. Should the body be evaluated?
      Parameters:
        `writer` - the output writer.
      Returns:
        true if the body should be evaluated

    - #### end

          public boolean end(Writer writer,
                             String body)

      Callback for the end tag of this component. Should the body be evaluated again?
      NOTE: will pop component stack.
      Parameters:
        `writer` - the output writer.
        `body` - the rendered body.
      Returns:
        true if the body should be evaluated again

    - #### end

          protected boolean end(Writer writer,
                                String body,
                                boolean popComponentStack)

      Callback for the start tag of this component. Should the body be evaluated again?
      NOTE: has a parameter to determine to pop the component stack.
      Parameters:
        `writer` - the output writer.
        `body` - the rendered body.
        `popComponentStack` - should the component stack be popped?
      Returns:
        true if the body should be evaluated again

    - #### popComponentStack

          protected void popComponentStack()

      Pops the component stack.

    - #### findAncestor

          protected Component findAncestor(Class<?> clazz)

      Finds the nearest ancestor of this component stack.
      Parameters:
        `clazz` - the class to look for, or if assignable from.
      Returns:
        the component if found, `null` if not.

    - #### findString

          protected String findString(String expr)

      Evaluates the OGNL stack to find a String value.
      Parameters:
        `expr` - OGNL expression.
      Returns:
        the String value found.

    - #### findString

          protected String findString(String expr,
                                      String field,
                                      String errorMsg)

      Evaluates the OGNL stack to find a String value.
      If the given expression is `null` a error is logged and a `RuntimeException` is thrown constructed with a messaged based on the given field and errorMsg parameter.
      Parameters:
        `expr` - OGNL expression.
        `field` - field name used when throwing `RuntimeException`.
        `errorMsg` - error message used when throwing `RuntimeException`.
      Returns:
        the String value found.
      Throws:
        `StrutsException` - is thrown in case of expression is null.

    - #### fieldError

          protected StrutsException fieldError(String field,
                                               String errorMsg,
                                               Exception e)

      Constructs a `RuntimeException` based on the given information.
      A message is constructed and logged at ERROR level before being returned as a `RuntimeException`.
      Parameters:
        `field` - field name used when throwing `RuntimeException`.
        `errorMsg` - error message used when throwing `RuntimeException`.
        `e` - the caused exception, can be `null`.
      Returns:
        the constructed `StrutsException`.

    - #### findValue

          protected Object findValue(String expression)

      Finds a value from the OGNL stack based on the given expression. Will always evaluate `expr` against stack except when `expr` is null. If %{...} is applied, simply strip it off.
      Parameters:
        `expression` - the expression. Returns `null` if expr is null.
      Returns:
        the value, `null` if not found.

    - #### stripExpression

          protected String stripExpression(String expression)

      If %{...} is applied, simply strip the "%{" and "}" off.
      Parameters:
        `expression` - the expression (must be not null)
      Returns:
        the stripped expression

    - #### completeExpression

          protected String completeExpression(String expr)

      Adds the surrounding %{ } to the expression for proper processing.
      Parameters:
        `expr` - the expression.
      Returns:
        the modified expression wrapped with %{...}

    - #### findValue

          protected Object findValue(String expr,
                                     String field,
                                     String errorMsg)

      Evaluates the OGNL stack to find an Object value.

      Function just like `findValue(String)` except that if the given expression is `null` a error is logged and a `RuntimeException` is thrown constructed with a messaged based on the given field and errorMsg parameter.

      Parameters:
        `expr` - OGNL expression.
        `field` - field name used when throwing `RuntimeException`.
        `errorMsg` - error message used when throwing `RuntimeException`.
      Returns:
        the Object found, is never `null`.
      Throws:
        `StrutsException` - is thrown in case of not found in the OGNL stack, or expression is `null`.

    - #### findValue

          protected Object findValue(String expression,
                                     Class<?> toType)

      Evaluates the OGNL stack to find an Object of the given type. Will evaluate `expression` the portion wrapped with %{...} against stack if evaluating to String.class, else the whole `expression` is evaluated against the stack.
      Parameters:
        `expression` - OGNL expression.
        `toType` - the type expected to find.
      Returns:
        the Object found, or `null` if not found.

    - #### determineActionURL

          protected String determineActionURL(String action,
                                              String namespace,
                                              String method,
                                              javax.servlet.http.HttpServletRequest req,
                                              javax.servlet.http.HttpServletResponse res,
                                              Map<String,Object> parameters,
                                              String scheme,
                                              boolean includeContext,
                                              boolean encodeResult,
                                              boolean forceAddSchemeHostAndPort,
                                              boolean escapeAmp)

      Renders an action URL by consulting the `ActionMapper`.
      Parameters:
        `action` - the action
        `namespace` - the namespace
        `method` - the method
        `req` - HTTP request
        `res` - HTTP response
        `parameters` - parameters
        `scheme` - http or https
        `includeContext` - should the context path be included or not
        `encodeResult` - should the url be encoded
        `forceAddSchemeHostAndPort` - should the scheme host and port be forced
        `escapeAmp` - should ampersand (&) be escaped to &amp;
      Returns:
        the action url.

    - #### determineNamespace

          protected String determineNamespace(String namespace,
                                              ValueStack stack,
                                              javax.servlet.http.HttpServletRequest req)

      Determines the namespace of the current page being renderdd. Useful for Form, URL, and href generations.
      Parameters:
        `namespace` - the namespace
        `stack` - OGNL value stack
        `req` - HTTP request
      Returns:
        the namepsace of the current page being rendered, is never `null`.

    - #### getNamespace

          protected String getNamespace(ValueStack stack)

    - #### copyParams

          public void copyParams(Map<String,Object> params)

      Pushes this component's parameter Map as well as the component itself on to the stack and then copies the supplied parameters over. Because the component's parameter Map is pushed before the component itself, any key-value pair that can't be assigned to component will be set in the parameters Map.
      Parameters:
        `params` - the parameters to copy.

    - #### toString

          protected String toString(Throwable t)

      Constructs a string representation of the given exception.
      Parameters:
        `t` - the exception
      Returns:
        the exception as a string.

    - #### getParameters

          public Map<String,Object> getParameters()

      Gets the parameters.
      Returns:
        the parameters. Is never `null`.

    - #### addAllParameters

          public void addAllParameters(Map<String,Object> params)

      Adds all the given parameters to this component's own parameters.
      Parameters:
        `params` - the parameters to add.

    - #### addParameter

          public void addParameter(String key,
                                   Object value)

      Adds the given key and value to this component's own parameter.
      If the provided key is `null` nothing happens. If the provided value is `null` any existing parameter with the given key name is removed.
      Parameters:
        `key` - the key of the new parameter to add.
        `value` - the value associated with the key.

    - #### usesBody

          public boolean usesBody()

      Overwrite to set if body should be used.
      Returns:
        always false for this component.

    - #### escapeHtmlBody

          public boolean escapeHtmlBody()

      Override to set if body content should be HTML-escaped.
      Returns:
        always true (default) for this component.
      Since:
        6.0.0

    - #### isValidTagAttribute

          public boolean isValidTagAttribute(String attrName)

      Checks if provided name is a valid tag's attribute
      Parameters:
        `attrName` - String name of attribute
      Returns:
        true if attribute with the same name was already defined

    - #### getStandardAttributes

          protected Collection<String> getStandardAttributes()

      If needed caches all methods annotated by given annotation to avoid further scans
      Returns:
        list of attributes

    - #### setPerformClearTagStateForTagPoolingServers

          public void setPerformClearTagStateForTagPoolingServers(boolean performClearTagStateForTagPoolingServers)

      Request that the tag state be cleared during `StrutsBodyTagSupport.doEndTag()` processing, which may help with certain edge cases with tag logic running on servers that implement JSP Tag Pooling. Note: All Tag classes that extend `StrutsBodyTagSupport` must implement a setter for this attribute (same name), and it must be defined at the Tag class level. Defining a setter in the superclass alone is insufficient (results in "Cannot find a setter method for the attribute").

      See {@link org.apache.struts2.views.jsp.StrutsBodyTagSupport#clearTagStateForTagPoolingServers() for additional details.

      Parameters:
        `performClearTagStateForTagPoolingServers` - true if tag state should be cleared, false otherwise.

    - #### getPerformClearTagStateForTagPoolingServers

          public boolean getPerformClearTagStateForTagPoolingServers()

    - #### isAcceptableExpression

          protected boolean isAcceptableExpression(String expression)

      Checks if expression doesn't contain vulnerable code
      Parameters:
        `expression` - of the component
      Returns:
        true|false
      Since:
        6.0.0

Copyright © 2000–2023 Apache Software Foundation. All rights reserved.