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

# Class SessionIdGeneratorBase

java.lang.Object
org.apache.catalina.util.LifecycleBase
org.apache.catalina.util.SessionIdGeneratorBase

All Implemented Interfaces:
  `Lifecycle, SessionIdGenerator`

Direct Known Subclasses:
  `StandardSessionIdGenerator`

public abstract class SessionIdGeneratorBase extends LifecycleBase implements SessionIdGenerator
Base implementation of `SessionIdGenerator` that manages a pool of `SecureRandom` instances for generating session identifiers.

- ## Nested Class Summary

  ### Nested classes/interfaces inherited from interface Lifecycle

  `Lifecycle.SingleUse`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `DEFAULT_SECURE_RANDOM_ALGORITHM`
  The default SecureRandom algorithm.

  ### Fields inherited from interface Lifecycle

  `AFTER_DESTROY_EVENT, AFTER_INIT_EVENT, AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_DESTROY_EVENT, BEFORE_INIT_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, CONFIGURE_START_EVENT, CONFIGURE_STOP_EVENT, PERIODIC_EVENT, START_EVENT, STOP_EVENT`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `SessionIdGeneratorBase()`
  Construct a new SessionIdGeneratorBase instance.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `destroyInternal()`
  Subclasses implement this method to perform any instance destruction required.
  `String`
  `generateSessionId()`
  Generate a new session ID using the configured jvmRoute.
  `String`
  `getJvmRoute()`
  Returns the node identifier associated with this node which will be included in the generated session ID.
  `protected void`
  `getRandomBytes(byte[] bytes)`
  Fill the given byte array with random bytes using a pooled `SecureRandom` instance.
  `String`
  `getSecureRandomAlgorithm()`
  Get the name of the algorithm used to create the `SecureRandom` instances which generate new session IDs.
  `String`
  `getSecureRandomClass()`
  Get the class name of the `SecureRandom` implementation used to generate session IDs.
  `String`
  `getSecureRandomProvider()`
  Get the name of the provider used to create the `SecureRandom` instances which generate new session IDs.
  `int`
  `getSessionIdLength()`
  Returns the number of bytes for a session ID.
  `protected void`
  `initInternal()`
  Subclasses implement this method to perform any instance initialisation required.
  `void`
  `setJvmRoute(String jvmRoute)`
  Set the node identifier used when generating session IDs in a clustered environment.
  `void`
  `setSecureRandomAlgorithm(String secureRandomAlgorithm)`
  Specify a non-default algorithm to use to create instances of `SecureRandom` which are used to generate session IDs.
  `void`
  `setSecureRandomClass(String secureRandomClass)`
  Specify a non-default `SecureRandom` implementation to use.
  `void`
  `setSecureRandomProvider(String secureRandomProvider)`
  Specify a non-default provider to use to create instances of `SecureRandom` which are used to generate session IDs.
  `void`
  `setSessionIdLength(int sessionIdLength)`
  Set the number of bytes used for a session ID.
  `protected void`
  `startInternal()`
  Subclasses must ensure that the state is changed to `LifecycleState.STARTING` during the execution of this method.
  `protected void`
  `stopInternal()`
  Subclasses must ensure that the state is changed to `LifecycleState.STOPPING` during the execution of this method.

  ### Methods inherited from class LifecycleBase

  `addLifecycleListener, destroy, findLifecycleListeners, fireLifecycleEvent, getState, getStateName, getThrowOnFailure, init, removeLifecycleListener, setState, setState, setThrowOnFailure, start, stop`

  ### Methods inherited from class Object

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

  ### Methods inherited from interface SessionIdGenerator

  `generateSessionId`

- ## Field Details

  - ### DEFAULT_SECURE_RANDOM_ALGORITHM

    public static final String DEFAULT_SECURE_RANDOM_ALGORITHM
    The default SecureRandom algorithm. SHA1PRNG if available, otherwise the platform default.

- ## Constructor Details

  - ### SessionIdGeneratorBase

    protected SessionIdGeneratorBase()
    Construct a new SessionIdGeneratorBase instance.

- ## Method Details

  - ### getSecureRandomClass

    public String getSecureRandomClass()
    Get the class name of the `SecureRandom` implementation used to generate session IDs.
    Returns:
      The fully qualified class name. `null` indicates that the JRE provided `SecureRandom` implementation will be used

  - ### setSecureRandomClass

    public void setSecureRandomClass(String secureRandomClass)
    Specify a non-default `SecureRandom` implementation to use. The implementation must be self-seeding and have a zero-argument constructor. If not specified, an instance of `SecureRandom` will be generated.
    Parameters:
      `secureRandomClass` - The fully-qualified class name

  - ### getSecureRandomAlgorithm

    public String getSecureRandomAlgorithm()
    Get the name of the algorithm used to create the `SecureRandom` instances which generate new session IDs.
    Returns:
      The name of the algorithm. `null` or the empty string means that platform default will be used

  - ### setSecureRandomAlgorithm

    public void setSecureRandomAlgorithm(String secureRandomAlgorithm)
    Specify a non-default algorithm to use to create instances of `SecureRandom` which are used to generate session IDs. If no algorithm is specified, SHA1PRNG will be used. If SHA1PRNG is not available, the platform default will be used. To use the platform default (which may be SHA1PRNG), specify `null` or the empty string. If an invalid algorithm and/or provider is specified the `SecureRandom` instances will be created using the defaults for this `SessionIdGenerator` implementation. If that fails, the `SecureRandom` instances will be created using platform defaults.
    Parameters:
      `secureRandomAlgorithm` - The name of the algorithm

  - ### getSecureRandomProvider

    public String getSecureRandomProvider()
    Get the name of the provider used to create the `SecureRandom` instances which generate new session IDs.
    Returns:
      The name of the provider. `null` or the empty string means that platform default will be used

  - ### setSecureRandomProvider

    public void setSecureRandomProvider(String secureRandomProvider)
    Specify a non-default provider to use to create instances of `SecureRandom` which are used to generate session IDs. If no provider is specified, the platform default is used. To use the platform default specify `null` or the empty string. If an invalid algorithm and/or provider is specified the `SecureRandom` instances will be created using the defaults for this `SessionIdGenerator` implementation. If that fails, the `SecureRandom` instances will be created using platform defaults.
    Parameters:
      `secureRandomProvider` - The name of the provider

  - ### getJvmRoute

    public String getJvmRoute()
    Description copied from interface: `SessionIdGenerator`
    Returns the node identifier associated with this node which will be included in the generated session ID.
    Specified by:
      `getJvmRoute` in interface `SessionIdGenerator`
    Returns:
      the node identifier used when generating session IDs in a clustered environment

  - ### setJvmRoute

    public void setJvmRoute(String jvmRoute)
    Set the node identifier used when generating session IDs in a clustered environment.
    Specified by:
      `setJvmRoute` in interface `SessionIdGenerator`
    Parameters:
      `jvmRoute` - the node identifier

  - ### getSessionIdLength

    public int getSessionIdLength()
    Description copied from interface: `SessionIdGenerator`
    Returns the number of bytes for a session ID.
    Specified by:
      `getSessionIdLength` in interface `SessionIdGenerator`
    Returns:
      the number of bytes used for a session ID

  - ### setSessionIdLength

    public void setSessionIdLength(int sessionIdLength)
    Set the number of bytes used for a session ID.
    Specified by:
      `setSessionIdLength` in interface `SessionIdGenerator`
    Parameters:
      `sessionIdLength` - the number of bytes

  - ### generateSessionId

    public String generateSessionId()
    Generate a new session ID using the configured jvmRoute.
    Specified by:
      `generateSessionId` in interface `SessionIdGenerator`
    Returns:
      the newly generated session ID

  - ### getRandomBytes

    protected void getRandomBytes(byte[] bytes)
    Fill the given byte array with random bytes using a pooled `SecureRandom` instance.
    Parameters:
      `bytes` - the byte array to fill with random data

  - ### initInternal

    protected void initInternal() throws LifecycleException
    Description copied from class: `LifecycleBase`
    Subclasses implement this method to perform any instance initialisation required.
    Specified by:
      `initInternal` in class `LifecycleBase`
    Throws:
      `LifecycleException` - If the initialisation fails

  - ### startInternal

    protected void startInternal() throws LifecycleException
    Description copied from class: `LifecycleBase`
    Subclasses must ensure that the state is changed to `LifecycleState.STARTING` during the execution of this method. Changing state will trigger the `Lifecycle.START_EVENT` event. If a component fails to start it may either throw a `LifecycleException` which will cause it's parent to fail to start, or it can place itself in the error state in which case `LifecycleBase.stop()` will be called on the failed component but the parent component will continue to start normally.
    Specified by:
      `startInternal` in class `LifecycleBase`
    Throws:
      `LifecycleException` - Start error occurred

  - ### stopInternal

    protected void stopInternal() throws LifecycleException
    Description copied from class: `LifecycleBase`
    Subclasses must ensure that the state is changed to `LifecycleState.STOPPING` during the execution of this method. Changing state will trigger the `Lifecycle.STOP_EVENT` event.
    Specified by:
      `stopInternal` in class `LifecycleBase`
    Throws:
      `LifecycleException` - Stop error occurred

  - ### destroyInternal

    protected void destroyInternal() throws LifecycleException
    Description copied from class: `LifecycleBase`
    Subclasses implement this method to perform any instance destruction required.
    Specified by:
      `destroyInternal` in class `LifecycleBase`
    Throws:
      `LifecycleException` - If the destruction fails