DataSourceStore (Apache Tomcat 11.0.25 API Documentation)
Description: declaration: package: org.apache.catalina.session, class: DataSourceStore

# Class DataSourceStore

java.lang.Object
org.apache.catalina.util.LifecycleBase
org.apache.catalina.session.StoreBase
org.apache.catalina.session.DataSourceStore

All Implemented Interfaces:
  `Lifecycle, Store`

public class DataSourceStore extends StoreBase
Implementation of the `Store` interface that stores serialized session objects in a database. Sessions that are saved are still subject to being expired based on inactivity.

- ## Nested Class Summary

  ### Nested classes/interfaces inherited from interface Lifecycle

  `Lifecycle.SingleUse`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected DataSource`
  `dataSource`
  DataSource to use
  `protected String`
  `dataSourceName`
  name of the JNDI resource
  `protected String`
  `sessionAppCol`
  Column to use for /Engine/Host/Context name
  `protected String`
  `sessionDataCol`
  Data column to use.
  `protected String`
  `sessionIdCol`
  Id column to use.
  `protected String`
  `sessionLastAccessedCol`
  Last Accessed column to use.
  `protected String`
  `sessionMaxInactiveCol`
  Max Inactive column to use.
  `protected String`
  `sessionTable`
  Table to use.
  `protected String`
  `sessionValidCol`
  `Is Valid` column to use.
  `protected static final String`
  `storeName`
  Name to register for this Store, used for logging.

  ### Fields inherited from class StoreBase

  `manager, sm, support`

  ### 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
  Constructor
  Description
  `DataSourceStore()`
  Default constructor.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `clear()`
  Remove all Sessions from this Store.
  `protected void`
  `close(Connection dbConnection)`
  Close the specified database connection.
  `String[]`
  `expiredKeys()`
  Get only those keys of sessions, that are saved in the Store and are to be expired.
  `protected Connection`
  `getConnection()`
  Check the connection associated with this store, if it's `null` or closed try to reopen it.
  `String`
  `getDataSourceName()`
  Return the name of the JNDI DataSource-factory.
  `boolean`
  `getLocalDataSource()`
  Return whether the datasource will be looked up in the webapp JNDI Context.
  `String`
  `getName()`
  Return the name for this instance, built from the container name.
  `String`
  `getSessionAppCol()`
  Return the web application name column for the table.
  `String`
  `getSessionDataCol()`
  Return the data column for the table.
  `String`
  `getSessionIdCol()`
  Return the Id column for the table.
  `String`
  `getSessionLastAccessedCol()`
  Return the `Last Accessed` column.
  `String`
  `getSessionMaxInactiveCol()`
  Return the `Max Inactive` column.
  `String`
  `getSessionTable()`
  Return the table for this Store.
  `String`
  `getSessionValidCol()`
  Return the `Is Valid` column.
  `int`
  `getSize()`
  Return the number of Sessions present in this Store.
  `String`
  `getStoreName()`
  Return the name for this Store, used for logging.
  `String[]`
  `keys()`
  Return an array containing the session identifiers of all Sessions currently saved in this Store.
  `Session`
  `load(String id)`
  Load and return the Session associated with the specified session identifier from this Store, without removing it.
  `protected Connection`
  `open()`
  Open (if necessary) and return a database connection for use by this Store.
  `protected void`
  `release(Connection conn)`
  Release the connection, if it is associated with a connection pool.
  `void`
  `remove(String id)`
  Remove the Session with the specified session identifier from this Store, if present.
  `void`
  `save(Session session)`
  Save the specified Session into this Store.
  `void`
  `setDataSourceName(String dataSourceName)`
  Set the JNDI name of a DataSource-factory to use for db access
  `void`
  `setLocalDataSource(boolean localDataSource)`
  Set to `true` to cause the datasource to be looked up in the webapp JNDI Context.
  `void`
  `setSessionAppCol(String sessionAppCol)`
  Set the App column for the table.
  `void`
  `setSessionDataCol(String sessionDataCol)`
  Set the Data column for the table
  `void`
  `setSessionIdCol(String sessionIdCol)`
  Set the Id column for the table.
  `void`
  `setSessionLastAccessedCol(String sessionLastAccessedCol)`
  Set the `Last Accessed` column for the table
  `void`
  `setSessionMaxInactiveCol(String sessionMaxInactiveCol)`
  Set the `Max Inactive` column for the table
  `void`
  `setSessionTable(String sessionTable)`
  Set the table for this Store.
  `void`
  `setSessionValidCol(String sessionValidCol)`
  Set the `Is Valid` column for the table

  ### Methods inherited from class StoreBase

  `addPropertyChangeListener, destroyInternal, getManager, getObjectInputStream, initInternal, processExpires, removePropertyChangeListener, setManager, startInternal, stopInternal, toString`

  ### 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, wait, wait, wait`

- ## Field Details

  - ### storeName

    protected static final String storeName
    Name to register for this Store, used for logging.
    See Also:
      - Constant Field Values

  - ### dataSourceName

    protected String dataSourceName
    name of the JNDI resource

  - ### dataSource

    protected DataSource dataSource
    DataSource to use

  - ### sessionTable

    protected String sessionTable
    Table to use.

  - ### sessionAppCol

    protected String sessionAppCol
    Column to use for /Engine/Host/Context name

  - ### sessionIdCol

    protected String sessionIdCol
    Id column to use.

  - ### sessionDataCol

    protected String sessionDataCol
    Data column to use.

  - ### sessionValidCol

    protected String sessionValidCol
    `Is Valid` column to use.

  - ### sessionMaxInactiveCol

    protected String sessionMaxInactiveCol
    Max Inactive column to use.

  - ### sessionLastAccessedCol

    protected String sessionLastAccessedCol
    Last Accessed column to use.

- ## Constructor Details

  - ### DataSourceStore

    public DataSourceStore()
    Default constructor.

- ## Method Details

  - ### getName

    public String getName()
    Return the name for this instance, built from the container name.
    Returns:
      the instance name

  - ### getStoreName

    public String getStoreName()
    Description copied from class: `StoreBase`
    Return the name for this Store, used for logging.
    Overrides:
      `getStoreName` in class `StoreBase`
    Returns:
      the store name

  - ### setSessionTable

    public void setSessionTable(String sessionTable)
    Set the table for this Store.
    Parameters:
      `sessionTable` - The new table

  - ### getSessionTable

    public String getSessionTable()
    Return the table for this Store.
    Returns:
      the table name

  - ### setSessionAppCol

    public void setSessionAppCol(String sessionAppCol)
    Set the App column for the table.
    Parameters:
      `sessionAppCol` - the column name

  - ### getSessionAppCol

    public String getSessionAppCol()
    Return the web application name column for the table.
    Returns:
      the column name

  - ### setSessionIdCol

    public void setSessionIdCol(String sessionIdCol)
    Set the Id column for the table.
    Parameters:
      `sessionIdCol` - the column name

  - ### getSessionIdCol

    public String getSessionIdCol()
    Return the Id column for the table.
    Returns:
      the column name

  - ### setSessionDataCol

    public void setSessionDataCol(String sessionDataCol)
    Set the Data column for the table
    Parameters:
      `sessionDataCol` - the column name

  - ### getSessionDataCol

    public String getSessionDataCol()
    Return the data column for the table.
    Returns:
      the column name

  - ### setSessionValidCol

    public void setSessionValidCol(String sessionValidCol)
    Set the `Is Valid` column for the table
    Parameters:
      `sessionValidCol` - The column name

  - ### getSessionValidCol

    public String getSessionValidCol()
    Return the `Is Valid` column.
    Returns:
      the column name

  - ### setSessionMaxInactiveCol

    public void setSessionMaxInactiveCol(String sessionMaxInactiveCol)
    Set the `Max Inactive` column for the table
    Parameters:
      `sessionMaxInactiveCol` - The column name

  - ### getSessionMaxInactiveCol

    public String getSessionMaxInactiveCol()
    Return the `Max Inactive` column.
    Returns:
      the column name

  - ### setSessionLastAccessedCol

    public void setSessionLastAccessedCol(String sessionLastAccessedCol)
    Set the `Last Accessed` column for the table
    Parameters:
      `sessionLastAccessedCol` - The column name

  - ### getSessionLastAccessedCol

    public String getSessionLastAccessedCol()
    Return the `Last Accessed` column.
    Returns:
      the column name

  - ### setDataSourceName

    public void setDataSourceName(String dataSourceName)
    Set the JNDI name of a DataSource-factory to use for db access
    Parameters:
      `dataSourceName` - The JNDI name of the DataSource-factory

  - ### getDataSourceName

    public String getDataSourceName()
    Return the name of the JNDI DataSource-factory.
    Returns:
      the JNDI name

  - ### getLocalDataSource

    public boolean getLocalDataSource()
    Return whether the datasource will be looked up in the webapp JNDI Context.
    Returns:
      true if the datasource is looked up in the webapp JNDI Context

  - ### setLocalDataSource

    public void setLocalDataSource(boolean localDataSource)
    Set to `true` to cause the datasource to be looked up in the webapp JNDI Context.
    Parameters:
      `localDataSource` - the new flag value

  - ### expiredKeys

    public String[] expiredKeys() throws IOException
    Description copied from class: `StoreBase`
    Get only those keys of sessions, that are saved in the Store and are to be expired.
    Overrides:
      `expiredKeys` in class `StoreBase`
    Returns:
      array of session keys, that are to be expired
    Throws:
      `IOException` - if an input-/output error occurred

  - ### keys

    public String[] keys() throws IOException
    Description copied from interface: `Store`
    Return an array containing the session identifiers of all Sessions currently saved in this Store. If there are no such Sessions, a zero-length array is returned.
    Returns:
      the session identifiers
    Throws:
      `IOException` - if an input/output error occurred

  - ### getSize

    public int getSize() throws IOException
    Description copied from interface: `Store`
    Return the number of Sessions present in this Store.
    Returns:
      the number of Sessions
    Throws:
      `IOException` - if an input/output error occurs

  - ### load

    public Session load(String id) throws ClassNotFoundException, IOException
    Description copied from interface: `Store`
    Load and return the Session associated with the specified session identifier from this Store, without removing it. If there is no such stored Session, return `null`.

    Implementations should expect, and correctly handle, concurrent calls to any method but in particular calls to `#load(String)`, `#save(Session)` and `#remove(String)` for the same session.

    The session ID is user provided so stores must treat it as untrusted data.

    Parameters:
      `id` - Session identifier of the session to load
    Returns:
      the loaded Session instance
    Throws:
      `ClassNotFoundException` - if a deserialization error occurs
      `IOException` - if an input/output error occurs

  - ### remove

    public void remove(String id) throws IOException
    Description copied from interface: `Store`
    Remove the Session with the specified session identifier from this Store, if present. If no such Session is present, this method takes no action.

    Implementations should expect, and correctly handle, concurrent calls to any method but in particular calls to `#load(String)`, `#save(Session)` and `#remove(String)` for the same session.

    The session ID is user provided so stores must treat it as untrusted data.

    Parameters:
      `id` - Session identifier of the Session to be removed
    Throws:
      `IOException` - if an input/output error occurs

  - ### clear

    public void clear() throws IOException
    Description copied from interface: `Store`
    Remove all Sessions from this Store.
    Throws:
      `IOException` - if an input/output error occurs

  - ### save

    public void save(Session session) throws IOException
    Description copied from interface: `Store`
    Save the specified Session into this Store. Any previously saved information for the associated session identifier is replaced.

    Implementations should expect, and correctly handle, concurrent calls to any method but in particular calls to `#load(String)`, `#save(Session)` and `#remove(String)` for the same session.

    Parameters:
      `session` - Session to be saved
    Throws:
      `IOException` - if an input/output error occurs

  - ### getConnection

    protected Connection getConnection()
    Check the connection associated with this store, if it's `null` or closed try to reopen it. Returns `null` if the connection could not be established.
    Returns:
      `Connection` if the connection succeeded

  - ### open

    protected Connection open() throws SQLException
    Open (if necessary) and return a database connection for use by this Store.
    Returns:
      database connection ready to use
    Throws:
      `SQLException` - if a database error occurs

  - ### close

    protected void close(Connection dbConnection)
    Close the specified database connection.
    Parameters:
      `dbConnection` - The connection to be closed

  - ### release

    protected void release(Connection conn)
    Release the connection, if it is associated with a connection pool.
    Parameters:
      `conn` - The connection to be released