SSIServletExternalResolver (Apache Tomcat 11.0.24 API Documentation)
Description: declaration: package: org.apache.catalina.ssi, class: SSIServletExternalResolver

# Class SSIServletExternalResolver

java.lang.Object
org.apache.catalina.ssi.SSIServletExternalResolver

All Implemented Interfaces:
  `SSIExternalResolver`

public class SSIServletExternalResolver extends Object implements SSIExternalResolver
An implementation of SSIExternalResolver that is used with servlets.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `protected static final record`
  `SSIServletExternalResolver.ServletContextAndPath`
  Holds a servlet context and an associated path.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final ServletContext`
  `context`
  The servlet context for resource access.
  `protected final int`
  `debug`
  Debug level for SSI processing.
  `protected final String`
  `inputEncoding`
  Character encoding for included file content.
  `protected final boolean`
  `isVirtualWebappRelative`
  Whether virtual paths are relative to the webapp.
  `protected final HttpServletRequest`
  `req`
  The current HTTP servlet request.
  `protected final HttpServletResponse`
  `res`
  The current HTTP servlet response.
  `protected final String[]`
  `VARIABLE_NAMES`
  Standard CGI variable names exposed to SSI.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `SSIServletExternalResolver(ServletContext context, HttpServletRequest req, HttpServletResponse res, boolean isVirtualWebappRelative, int debug, String inputEncoding)`
  Constructor.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addVariableNames(Collection<String> variableNames)`
  Add standard CGI variable names to the given collection.
  `protected String`
  `getAbsolutePath(String path)`
  Resolve a relative path to an absolute normalized path.
  `protected String`
  `getCGIVariable(String name)`
  Get the value of a CGI variable by name.
  `Date`
  `getCurrentDate()`
  Get the current date.
  `long`
  `getFileLastModified(String path, boolean virtual)`
  Get the last modified time of a file.
  `long`
  `getFileSize(String path, boolean virtual)`
  Get the size of a file.
  `String`
  `getFileText(String originalPath, boolean virtual)`
  Get the text content of a file.
  `protected String`
  `getPathWithoutContext(String contextPath, String servletPath)`
  Remove the context path prefix from a servlet path.
  `protected String`
  `getPathWithoutFileName(String servletPath)`
  Get the path portion without the file name.
  `protected Object`
  `getReqAttributeIgnoreCase(String targetName)`
  Get a request attribute by name, case-insensitive.
  `protected SSIServletExternalResolver.ServletContextAndPath`
  `getServletContextAndPath(String originalPath, boolean virtual)`
  Resolve a path to a servlet context and path.
  `protected SSIServletExternalResolver.ServletContextAndPath`
  `getServletContextAndPathFromNonVirtualPath(String nonVirtualPath)`
  Resolve a non-virtual (relative) path to a servlet context and path.
  `protected SSIServletExternalResolver.ServletContextAndPath`
  `getServletContextAndPathFromVirtualPath(String virtualPath)`
  Resolve a virtual path to a servlet context and path.
  `protected URLConnection`
  `getURLConnection(String originalPath, boolean virtual)`
  Get a URL connection for the given path.
  `String`
  `getVariableValue(String name)`
  Get the value of an SSI variable.
  `protected boolean`
  `isNameReserved(String name)`
  Check if a name is reserved (`java.`, `javax.`, `sun.`, `jakarta.`, `org.apache.catalina.` and `org.apache.tomcat.` prefixes).
  `protected boolean`
  `isRootContext(ServletContext servletContext)`
  Check if the given servlet context is the root context.
  `void`
  `log(String message, Throwable throwable)`
  Log a message with an optional throwable.
  `protected String`
  `nullToEmptyString(String string)`
  Convert null to an empty string.
  `void`
  `setVariableValue(String name, String value)`
  Set an SSI variable value as a request attribute.

  ### Methods inherited from class Object

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

- ## Field Details

  - ### VARIABLE_NAMES

    protected final String[] VARIABLE_NAMES
    Standard CGI variable names exposed to SSI.

  - ### context

    protected final ServletContext context
    The servlet context for resource access.

  - ### req

    protected final HttpServletRequest req
    The current HTTP servlet request.

  - ### res

    protected final HttpServletResponse res
    The current HTTP servlet response.

  - ### isVirtualWebappRelative

    protected final boolean isVirtualWebappRelative
    Whether virtual paths are relative to the webapp.

  - ### debug

    protected final int debug
    Debug level for SSI processing.

  - ### inputEncoding

    protected final String inputEncoding
    Character encoding for included file content.

- ## Constructor Details

  - ### SSIServletExternalResolver

    public SSIServletExternalResolver(ServletContext context, HttpServletRequest req, HttpServletResponse res, boolean isVirtualWebappRelative, int debug, String inputEncoding)
    Constructor.
    Parameters:
      `context` - the servlet context
      `req` - the HTTP servlet request
      `res` - the HTTP servlet response
      `isVirtualWebappRelative` - whether virtual paths are relative to the webapp
      `debug` - debug level
      `inputEncoding` - character encoding for included file content

- ## Method Details

  - ### log

    public void log(String message, Throwable throwable)
    Log a message with an optional throwable.
    Specified by:
      `log` in interface `SSIExternalResolver`
    Parameters:
      `message` - the message to log
      `throwable` - the optional throwable

  - ### addVariableNames

    public void addVariableNames(Collection<String> variableNames)
    Add standard CGI variable names to the given collection.
    Specified by:
      `addVariableNames` in interface `SSIExternalResolver`
    Parameters:
      `variableNames` - the collection to add variable names to

  - ### getReqAttributeIgnoreCase

    protected Object getReqAttributeIgnoreCase(String targetName)
    Get a request attribute by name, case-insensitive.
    Parameters:
      `targetName` - the attribute name
    Returns:
      the attribute value or null

  - ### isNameReserved

    protected boolean isNameReserved(String name)
    Check if a name is reserved (`java.`, `javax.`, `sun.`, `jakarta.`, `org.apache.catalina.` and `org.apache.tomcat.` prefixes).
    Parameters:
      `name` - the name to check
    Returns:
      true if the name is reserved

  - ### setVariableValue

    public void setVariableValue(String name, String value)
    Set an SSI variable value as a request attribute.
    Specified by:
      `setVariableValue` in interface `SSIExternalResolver`
    Parameters:
      `name` - the variable name
      `value` - the variable value

  - ### getVariableValue

    public String getVariableValue(String name)
    Get the value of an SSI variable.
    Specified by:
      `getVariableValue` in interface `SSIExternalResolver`
    Parameters:
      `name` - the variable name
    Returns:
      the variable value or null

  - ### getCGIVariable

    protected String getCGIVariable(String name)
    Get the value of a CGI variable by name.
    Parameters:
      `name` - the CGI variable name
    Returns:
      the variable value or null

  - ### getCurrentDate

    public Date getCurrentDate()
    Get the current date.
    Specified by:
      `getCurrentDate` in interface `SSIExternalResolver`
    Returns:
      the current date

  - ### nullToEmptyString

    protected String nullToEmptyString(String string)
    Convert null to an empty string.
    Parameters:
      `string` - the input string
    Returns:
      the string or empty string if null

  - ### getPathWithoutFileName

    protected String getPathWithoutFileName(String servletPath)
    Get the path portion without the file name.
    Parameters:
      `servletPath` - the servlet path
    Returns:
      the path without file name or null

  - ### getPathWithoutContext

    protected String getPathWithoutContext(String contextPath, String servletPath)
    Remove the context path prefix from a servlet path.
    Parameters:
      `contextPath` - the context path
      `servletPath` - the servlet path
    Returns:
      the path without context prefix

  - ### getAbsolutePath

    protected String getAbsolutePath(String path) throws IOException
    Resolve a relative path to an absolute normalized path.
    Parameters:
      `path` - the relative path
    Returns:
      the absolute normalized path
    Throws:
      `IOException` - if path normalization fails

  - ### getServletContextAndPathFromNonVirtualPath

    protected SSIServletExternalResolver.ServletContextAndPath getServletContextAndPathFromNonVirtualPath(String nonVirtualPath) throws IOException
    Resolve a non-virtual (relative) path to a servlet context and path.
    Parameters:
      `nonVirtualPath` - the non-virtual path
    Returns:
      the servlet context and resolved path
    Throws:
      `IOException` - if the path is invalid

  - ### getServletContextAndPathFromVirtualPath

    protected SSIServletExternalResolver.ServletContextAndPath getServletContextAndPathFromVirtualPath(String virtualPath) throws IOException
    Resolve a virtual path to a servlet context and path.
    Parameters:
      `virtualPath` - the virtual path
    Returns:
      the servlet context and resolved path
    Throws:
      `IOException` - if the path cannot be resolved

  - ### isRootContext

    protected boolean isRootContext(ServletContext servletContext)
    Check if the given servlet context is the root context.
    Parameters:
      `servletContext` - the servlet context
    Returns:
      true if the context is the root

  - ### getServletContextAndPath

    protected SSIServletExternalResolver.ServletContextAndPath getServletContextAndPath(String originalPath, boolean virtual) throws IOException
    Resolve a path to a servlet context and path.
    Parameters:
      `originalPath` - the original path
      `virtual` - whether the path is virtual
    Returns:
      the servlet context and resolved path
    Throws:
      `IOException` - if the path cannot be resolved

  - ### getURLConnection

    protected URLConnection getURLConnection(String originalPath, boolean virtual) throws IOException
    Get a URL connection for the given path.
    Parameters:
      `originalPath` - the original path
      `virtual` - whether the path is virtual
    Returns:
      the URL connection
    Throws:
      `IOException` - if the resource is not found

  - ### getFileLastModified

    public long getFileLastModified(String path, boolean virtual) throws IOException
    Get the last modified time of a file.
    Specified by:
      `getFileLastModified` in interface `SSIExternalResolver`
    Parameters:
      `path` - the file path
      `virtual` - whether the path is virtual
    Returns:
      the last modified time in milliseconds
    Throws:
      `IOException` - if the file cannot be accessed

  - ### getFileSize

    public long getFileSize(String path, boolean virtual) throws IOException
    Get the size of a file.
    Specified by:
      `getFileSize` in interface `SSIExternalResolver`
    Parameters:
      `path` - the file path
      `virtual` - whether the path is virtual
    Returns:
      the file size in bytes or -1 if unknown
    Throws:
      `IOException` - if the file cannot be accessed

  - ### getFileText

    public String getFileText(String originalPath, boolean virtual) throws IOException
    Get the text content of a file.
    Specified by:
      `getFileText` in interface `SSIExternalResolver`
    Parameters:
      `originalPath` - the original file path
      `virtual` - whether the path is virtual
    Returns:
      the file content as text
    Throws:
      `IOException` - if the file cannot be read