DeltaSession (Apache Tomcat 11.0.22 API Documentation)
Description: declaration: package: org.apache.catalina.ha.session, class: DeltaSession

# Class DeltaSession

java.lang.Object
org.apache.catalina.session.StandardSession
org.apache.catalina.ha.session.DeltaSession

All Implemented Interfaces:
  `HttpSession, Externalizable, Serializable, ClusterSession, Session, ReplicatedMapEntry`

public class DeltaSession extends StandardSession implements Externalizable, ClusterSession, ReplicatedMapEntry
Similar to the StandardSession except that this session will keep track of deltas during a request.

See Also:
  - Serialized Form

- ## Nested Class Summary

  ### Nested classes/interfaces inherited from interface HttpSession

  `HttpSession.Accessor`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final Lock`
  `diffLock`
  `static final Log`
  `log`
  `protected static final StringManager`
  `sm`
  The string manager for this package.

  ### Fields inherited from class StandardSession

  `accessCount, activityCheck, attributes, authType, creationTime, EMPTY_ARRAY, expiring, facade, id, isNew, isValid, lastAccessAtStart, lastAccessedTime, listeners, manager, maxInactiveInterval, notes, principal, support, thisAccessedTime`

  ### Fields inherited from interface Session

  `SESSION_ACTIVATED_EVENT, SESSION_CHANGED_ID_EVENT, SESSION_CREATED_EVENT, SESSION_DESTROYED_EVENT, SESSION_PASSIVATED_EVENT`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DeltaSession()`
  `DeltaSession(Manager manager)`
  Construct a new Session associated with the specified Manager.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `accessEntry()`
  Access to an existing object.
  `void`
  `addSessionListener(SessionListener listener)`
  Add a session event listener to this component.
  `void`
  `addSessionListener(SessionListener listener, boolean addDeltaRequest)`
  `void`
  `applyDiff(byte[] diff, int offset, int length)`
  Applies a diff to an existing object.
  `protected DeltaRequest`
  `createRequest(String sessionId, boolean recordAllActions)`
  `protected void`
  `deserializeAndExecuteDeltaRequest(byte[] delta)`
  `protected void`
  `doReadObject(ObjectInputStream stream)`
  Read a serialized version of this session object from the specified object input stream.
  `protected void`
  `doWriteObject(ObjectOutputStream stream)`
  Write a serialized version of this session object to the specified object output stream.
  `void`
  `endAccess()`
  End access to the session.
  `void`
  `expire(boolean notify)`
  Perform the internal processing required to invalidate this session, without triggering an exception if the session has already expired.
  `void`
  `expire(boolean notify, boolean notifyCluster)`
  `ClassLoader[]`
  `getClassLoaders()`
  `DeltaRequest`
  `getDeltaRequest()`
  Deprecated.
  Unused.
  `byte[]`
  `getDiff()`
  Returns a diff and sets the dirty map to false
  `long`
  `getLastTimeReplicated()`
  `long`
  `getVersion()`
  For accuracy checking, a serialized attribute can contain a version number This number increases as modifications are made to the data.
  `boolean`
  `isAccessReplicate()`
  If this returns true, to replicate that an object has been accessed
  `boolean`
  `isDiffable()`
  If this returns true, the map will extract the diff using getDiff() Otherwise it will serialize the entire object.
  `boolean`
  `isDirty()`
  Has the object changed since last replication and is not in a locked state
  `boolean`
  `isPrimarySession()`
  returns true if this session is the primary session, if that is the case, the manager can expire it upon timeout.
  `boolean`
  `isValid()`
  `void`
  `lock()`
  Lock during serialization
  `void`
  `readExternal(ObjectInput in)`
  `void`
  `readObjectData(ObjectInput stream)`
  `void`
  `readObjectData(ObjectInputStream stream)`
  Read a serialized version of the contents of this session object from the specified object input stream, without requiring that the StandardSession itself have been serialized.
  `void`
  `recycle()`
  Release all object references, and initialize instance variables, in preparation for reuse of this object.
  `void`
  `removeAttribute(String name, boolean notify)`
  Remove the object bound with the specified name from this session.
  `void`
  `removeAttribute(String name, boolean notify, boolean addDeltaRequest)`
  `protected void`
  `removeAttributeInternal(String name, boolean notify, boolean addDeltaRequest)`
  `void`
  `removeNote(String name)`
  Remove any object bound to the specified name in the internal notes for this session.
  `void`
  `removeNote(String name, boolean addDeltaRequest)`
  `void`
  `removeSessionListener(SessionListener listener)`
  Remove a session event listener from this component.
  `void`
  `removeSessionListener(SessionListener listener, boolean addDeltaRequest)`
  `void`
  `resetDeltaRequest()`
  `void`
  `resetDiff()`
  Resets the current diff state and resets the dirty flag
  `protected void`
  `setAccessCount(int count)`
  `void`
  `setAttribute(String name, Object value)`
  Binds an object to this session, using the name specified.
  `void`
  `setAttribute(String name, Object value, boolean notify, boolean addDeltaRequest)`
  `void`
  `setAuthType(String authType)`
  Set the authentication type used to authenticate our cached Principal, if any.
  `void`
  `setAuthType(String authType, boolean addDeltaRequest)`
  `void`
  `setId(String id)`
  Set the session identifier for this session and notifies any associated listeners that a new session has been created.
  `void`
  `setId(String id, boolean notify)`
  Set the session identifier for this session and optionally notifies any associated listeners that a new session has been created.
  `void`
  `setLastTimeReplicated(long lastTimeReplicated)`
  Set the last replicate time.
  `void`
  `setMaxInactiveInterval(int interval)`
  Specifies the time, in seconds, between client requests before the servlet container will invalidate this session.
  `void`
  `setMaxInactiveInterval(int interval, boolean addDeltaRequest)`
  `void`
  `setNew(boolean isNew)`
  Set the `isNew` flag for this session.
  `void`
  `setNew(boolean isNew, boolean addDeltaRequest)`
  `void`
  `setNote(String name, Object value)`
  Bind an object to a specified name in the internal notes associated with this session, replacing any existing binding for this name.
  `void`
  `setNote(String name, Object value, boolean addDeltaRequest)`
  `void`
  `setOwner(Object owner)`
  This method is called after the object has been created on a remote map.
  `void`
  `setPrimarySession(boolean primarySession)`
  Sets whether this is the primary session or not.
  `void`
  `setPrincipal(Principal principal)`
  Set the authenticated Principal that is associated with this Session.
  `void`
  `setPrincipal(Principal principal, boolean addDeltaRequest)`
  `void`
  `setVersion(long version)`
  Forces a certain version to a replicated map entry
  `String`
  `toString()`
  `void`
  `unlock()`
  Unlock after serialization
  `void`
  `writeExternal(ObjectOutput out)`
  `void`
  `writeObjectData(ObjectOutput stream)`
  `void`
  `writeObjectData(ObjectOutputStream stream)`
  Write a serialized version of the contents of this session object to the specified object output stream, without requiring that the StandardSession itself have been serialized.

  ### Methods inherited from class StandardSession

  `access, activate, exclude, expire, fireSessionEvent, getAccessor, getAttribute, getAttributeNames, getAuthType, getCreationTime, getCreationTimeInternal, getId, getIdInternal, getIdleTime, getIdleTimeInternal, getLastAccessedTime, getLastAccessedTimeInternal, getManager, getMaxInactiveInterval, getNote, getNoteNames, getPrincipal, getServletContext, getSession, getThisAccessedTime, getThisAccessedTimeInternal, invalidate, isAttributeDistributable, isNew, isValidInternal, keys, passivate, removeAttribute, removeAttributeInternal, setAttribute, setCreationTime, setManager, setValid, tellChangedSessionId, tellNew`

  ### Methods inherited from class Object

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

  ### Methods inherited from interface HttpSession

  `getAccessor, getAttribute, getAttributeNames, getCreationTime, getId, getLastAccessedTime, getMaxInactiveInterval, getServletContext, invalidate, isNew, removeAttribute`

  ### Methods inherited from interface Session

  `access, expire, getAuthType, getCreationTime, getCreationTimeInternal, getId, getIdInternal, getIdleTime, getIdleTimeInternal, getLastAccessedTime, getLastAccessedTimeInternal, getManager, getMaxInactiveInterval, getNote, getNoteNames, getPrincipal, getSession, getThisAccessedTime, getThisAccessedTimeInternal, isAttributeDistributable, isNew, setCreationTime, setManager, setValid, tellChangedSessionId`

- ## Field Details

  - ### log

    public static final Log log

  - ### sm

    protected static final StringManager sm
    The string manager for this package.

  - ### diffLock

    protected final Lock diffLock

- ## Constructor Details

  - ### DeltaSession

    public DeltaSession()

  - ### DeltaSession

    public DeltaSession(Manager manager)
    Construct a new Session associated with the specified Manager.
    Parameters:
      `manager` - The manager with which this Session is associated

- ## Method Details

  - ### createRequest

    protected DeltaRequest createRequest(String sessionId, boolean recordAllActions)

  - ### isDirty

    public boolean isDirty()
    Description copied from interface: `ReplicatedMapEntry`
    Has the object changed since last replication and is not in a locked state
    Specified by:
      `isDirty` in interface `ReplicatedMapEntry`
    Returns:
      boolean

  - ### isDiffable

    public boolean isDiffable()
    Description copied from interface: `ReplicatedMapEntry`
    If this returns true, the map will extract the diff using getDiff() Otherwise it will serialize the entire object.
    Specified by:
      `isDiffable` in interface `ReplicatedMapEntry`
    Returns:
      boolean

  - ### getDiff

    public byte[] getDiff() throws IOException
    Description copied from interface: `ReplicatedMapEntry`
    Returns a diff and sets the dirty map to false
    Specified by:
      `getDiff` in interface `ReplicatedMapEntry`
    Returns:
      Serialized diff data
    Throws:
      `IOException` - IO error serializing

  - ### getClassLoaders

    public ClassLoader[] getClassLoaders()

  - ### applyDiff

    public void applyDiff(byte[] diff, int offset, int length) throws IOException, ClassNotFoundException
    Description copied from interface: `ReplicatedMapEntry`
    Applies a diff to an existing object.
    Specified by:
      `applyDiff` in interface `ReplicatedMapEntry`
    Parameters:
      `diff` - Serialized diff data
      `offset` - Array offset
      `length` - Array length
    Throws:
      `IOException` - IO error deserializing
      `ClassNotFoundException` - Serialization error

  - ### resetDiff

    public void resetDiff()
    Resets the current diff state and resets the dirty flag

    This implementation is a NO-OP. The diff is reset in `getDiff()`.

    Specified by:
      `resetDiff` in interface `ReplicatedMapEntry`

  - ### lock

    public void lock()
    Lock during serialization

    This implementation is a NO-OP. Any required locking takes place in the methods that make modifications.

    Specified by:
      `lock` in interface `ReplicatedMapEntry`

  - ### unlock

    public void unlock()
    Unlock after serialization

    This implementation is a NO-OP. Any required unlocking takes place in the methods that make modifications.

    Specified by:
      `unlock` in interface `ReplicatedMapEntry`

  - ### setOwner

    public void setOwner(Object owner)
    Description copied from interface: `ReplicatedMapEntry`
    This method is called after the object has been created on a remote map. On this method, the object can initialize itself for any data that wasn't
    Specified by:
      `setOwner` in interface `ReplicatedMapEntry`
    Parameters:
      `owner` - Object

  - ### isAccessReplicate

    public boolean isAccessReplicate()
    Description copied from interface: `ReplicatedMapEntry`
    If this returns true, to replicate that an object has been accessed
    Specified by:
      `isAccessReplicate` in interface `ReplicatedMapEntry`
    Returns:
      boolean

  - ### accessEntry

    public void accessEntry()
    Description copied from interface: `ReplicatedMapEntry`
    Access to an existing object.
    Specified by:
      `accessEntry` in interface `ReplicatedMapEntry`

  - ### isPrimarySession

    public boolean isPrimarySession()
    Description copied from interface: `ClusterSession`
    returns true if this session is the primary session, if that is the case, the manager can expire it upon timeout.
    Specified by:
      `isPrimarySession` in interface `ClusterSession`
    Returns:
      True if this session is primary

  - ### setPrimarySession

    public void setPrimarySession(boolean primarySession)
    Description copied from interface: `ClusterSession`
    Sets whether this is the primary session or not.
    Specified by:
      `setPrimarySession` in interface `ClusterSession`
    Parameters:
      `primarySession` - Flag value

  - ### setId

    public void setId(String id, boolean notify)
    Description copied from interface: `Session`
    Set the session identifier for this session and optionally notifies any associated listeners that a new session has been created.
    Specified by:
      `setId` in interface `Session`
    Overrides:
      `setId` in class `StandardSession`
    Parameters:
      `id` - The new session identifier
      `notify` - Should any associated listeners be notified that a new session has been created?

  - ### setId

    public void setId(String id)
    Description copied from interface: `Session`
    Set the session identifier for this session and notifies any associated listeners that a new session has been created.
    Specified by:
      `setId` in interface `Session`
    Overrides:
      `setId` in class `StandardSession`
    Parameters:
      `id` - The new session identifier

  - ### setMaxInactiveInterval

    public void setMaxInactiveInterval(int interval)
    Description copied from interface: `jakarta.servlet.http.HttpSession`
    Specifies the time, in seconds, between client requests before the servlet container will invalidate this session. A zero or negative time indicates that the session should never time out.
    Specified by:
      `setMaxInactiveInterval` in interface `HttpSession`
    Specified by:
      `setMaxInactiveInterval` in interface `Session`
    Overrides:
      `setMaxInactiveInterval` in class `StandardSession`
    Parameters:
      `interval` - An integer specifying the number of seconds

  - ### setMaxInactiveInterval

    public void setMaxInactiveInterval(int interval, boolean addDeltaRequest)

  - ### setNew

    public void setNew(boolean isNew)
    Description copied from interface: `Session`
    Set the `isNew` flag for this session.
    Specified by:
      `setNew` in interface `Session`
    Overrides:
      `setNew` in class `StandardSession`
    Parameters:
      `isNew` - The new value for the `isNew` flag

  - ### setNew

    public void setNew(boolean isNew, boolean addDeltaRequest)

  - ### setPrincipal

    public void setPrincipal(Principal principal)
    Description copied from interface: `Session`
    Set the authenticated Principal that is associated with this Session. This provides an `Authenticator` with a means to cache a previously authenticated Principal, and avoid potentially expensive `Realm.authenticate()` calls on every request.
    Specified by:
      `setPrincipal` in interface `Session`
    Overrides:
      `setPrincipal` in class `StandardSession`
    Parameters:
      `principal` - The new Principal, or `null` if none

  - ### setPrincipal

    public void setPrincipal(Principal principal, boolean addDeltaRequest)

  - ### setAuthType

    public void setAuthType(String authType)
    Description copied from interface: `Session`
    Set the authentication type used to authenticate our cached Principal, if any.
    Specified by:
      `setAuthType` in interface `Session`
    Overrides:
      `setAuthType` in class `StandardSession`
    Parameters:
      `authType` - The new cached authentication type

  - ### setAuthType

    public void setAuthType(String authType, boolean addDeltaRequest)

  - ### isValid

    public boolean isValid()
    Specified by:
      `isValid` in interface `Session`
    Overrides:
      `isValid` in class `StandardSession`
    Returns:
      `true` if the session is still valid

  - ### endAccess

    public void endAccess()
    Description copied from interface: `Session`
    End access to the session.
    Specified by:
      `endAccess` in interface `Session`
    Overrides:
      `endAccess` in class `StandardSession`

  - ### expire

    public void expire(boolean notify)
    Description copied from class: `StandardSession`
    Perform the internal processing required to invalidate this session, without triggering an exception if the session has already expired.
    Overrides:
      `expire` in class `StandardSession`
    Parameters:
      `notify` - Should we notify listeners about the demise of this session?

  - ### expire

    public void expire(boolean notify, boolean notifyCluster)

  - ### recycle

    public void recycle()
    Description copied from interface: `Session`
    Release all object references, and initialize instance variables, in preparation for reuse of this object.
    Specified by:
      `recycle` in interface `Session`
    Overrides:
      `recycle` in class `StandardSession`

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `StandardSession`

  - ### addSessionListener

    public void addSessionListener(SessionListener listener)
    Description copied from interface: `Session`
    Add a session event listener to this component.
    Specified by:
      `addSessionListener` in interface `Session`
    Overrides:
      `addSessionListener` in class `StandardSession`
    Parameters:
      `listener` - the SessionListener instance that should be notified for session events

  - ### addSessionListener

    public void addSessionListener(SessionListener listener, boolean addDeltaRequest)

  - ### removeSessionListener

    public void removeSessionListener(SessionListener listener)
    Description copied from interface: `Session`
    Remove a session event listener from this component.
    Specified by:
      `removeSessionListener` in interface `Session`
    Overrides:
      `removeSessionListener` in class `StandardSession`
    Parameters:
      `listener` - remove the session listener, which will no longer be notified

  - ### removeSessionListener

    public void removeSessionListener(SessionListener listener, boolean addDeltaRequest)

  - ### readExternal

    public void readExternal(ObjectInput in) throws IOException, ClassNotFoundException
    Specified by:
      `readExternal` in interface `Externalizable`
    Throws:
      `IOException`
      `ClassNotFoundException`

  - ### readObjectData

    public void readObjectData(ObjectInputStream stream) throws ClassNotFoundException, IOException
    Description copied from class: `StandardSession`
    Read a serialized version of the contents of this session object from the specified object input stream, without requiring that the StandardSession itself have been serialized.
    Overrides:
      `readObjectData` in class `StandardSession`
    Parameters:
      `stream` - The object input stream to read from
    Throws:
      `ClassNotFoundException` - if an unknown class is specified
      `IOException` - if an input/output error occurs

  - ### readObjectData

    public void readObjectData(ObjectInput stream) throws ClassNotFoundException, IOException
    Throws:
      `ClassNotFoundException`
      `IOException`

  - ### writeObjectData

    public void writeObjectData(ObjectOutputStream stream) throws IOException
    Description copied from class: `StandardSession`
    Write a serialized version of the contents of this session object to the specified object output stream, without requiring that the StandardSession itself have been serialized.
    Overrides:
      `writeObjectData` in class `StandardSession`
    Parameters:
      `stream` - The object output stream to write to
    Throws:
      `IOException` - if an input/output error occurs

  - ### writeObjectData

    public void writeObjectData(ObjectOutput stream) throws IOException
    Throws:
      `IOException`

  - ### resetDeltaRequest

    public void resetDeltaRequest()

  - ### getDeltaRequest

    @Deprecated public DeltaRequest getDeltaRequest()
    Deprecated.
    Unused. This method will be removed in Tomcat 12.
    Get the request.
    Returns:
      the request

  - ### deserializeAndExecuteDeltaRequest

    protected void deserializeAndExecuteDeltaRequest(byte[] delta) throws IOException, ClassNotFoundException
    Throws:
      `IOException`
      `ClassNotFoundException`

  - ### removeAttribute

    public void removeAttribute(String name, boolean notify)
    Description copied from class: `StandardSession`
    Remove the object bound with the specified name from this session. If the session does not have an object bound with this name, this method does nothing.

    After this method executes, and if the object implements `HttpSessionBindingListener`, the container calls `valueUnbound()` on the object.

    Overrides:
      `removeAttribute` in class `StandardSession`
    Parameters:
      `name` - Name of the object to remove from this session.
      `notify` - Should we notify interested listeners that this attribute is being removed?

  - ### removeAttribute

    public void removeAttribute(String name, boolean notify, boolean addDeltaRequest)

  - ### setAttribute

    public void setAttribute(String name, Object value)
    Description copied from interface: `jakarta.servlet.http.HttpSession`
    Binds an object to this session, using the name specified. If an object of the same name is already bound to the session, the object is replaced.

    After this method executes, and if the new object implements `HttpSessionBindingListener`, the container calls `HttpSessionBindingListener.valueBound`. The container then notifies any `HttpSessionAttributeListener`s in the web application.

    If an object was already bound to this session of this name that implements `HttpSessionBindingListener`, its `HttpSessionBindingListener.valueUnbound` method is called.

    If the value passed in is null, this has the same effect as calling `removeAttribute()`.

    Specified by:
      `setAttribute` in interface `HttpSession`
    Overrides:
      `setAttribute` in class `StandardSession`
    Parameters:
      `name` - the name to which the object is bound; cannot be null
      `value` - the object to be bound

  - ### setAttribute

    public void setAttribute(String name, Object value, boolean notify, boolean addDeltaRequest)

  - ### removeNote

    public void removeNote(String name)
    Description copied from interface: `Session`
    Remove any object bound to the specified name in the internal notes for this session.
    Specified by:
      `removeNote` in interface `Session`
    Overrides:
      `removeNote` in class `StandardSession`
    Parameters:
      `name` - Name of the note to be removed

  - ### removeNote

    public void removeNote(String name, boolean addDeltaRequest)

  - ### setNote

    public void setNote(String name, Object value)
    Description copied from interface: `Session`
    Bind an object to a specified name in the internal notes associated with this session, replacing any existing binding for this name.
    Specified by:
      `setNote` in interface `Session`
    Overrides:
      `setNote` in class `StandardSession`
    Parameters:
      `name` - Name to which the object should be bound
      `value` - Object to be bound to the specified name

  - ### setNote

    public void setNote(String name, Object value, boolean addDeltaRequest)

  - ### doReadObject

    protected void doReadObject(ObjectInputStream stream) throws ClassNotFoundException, IOException
    Description copied from class: `StandardSession`
    Read a serialized version of this session object from the specified object input stream.

    IMPLEMENTATION NOTE: The reference to the owning Manager is not restored by this method, and must be set explicitly.

    Overrides:
      `doReadObject` in class `StandardSession`
    Parameters:
      `stream` - The input stream to read from
    Throws:
      `ClassNotFoundException` - if an unknown class is specified
      `IOException` - if an input/output error occurs

  - ### writeExternal

    public void writeExternal(ObjectOutput out) throws IOException
    Specified by:
      `writeExternal` in interface `Externalizable`
    Throws:
      `IOException`

  - ### doWriteObject

    protected void doWriteObject(ObjectOutputStream stream) throws IOException
    Description copied from class: `StandardSession`
    Write a serialized version of this session object to the specified object output stream.

    IMPLEMENTATION NOTE: The owning Manager will not be stored in the serialized representation of this Session. After calling `readObject()`, you must set the associated Manager explicitly.

    IMPLEMENTATION NOTE: Any attribute that is not Serializable will be unbound from the session, with appropriate actions if it implements HttpSessionBindingListener. If you do not want any such attributes, be sure the `distributable` property of the associated Manager is set to `true`.

    Overrides:
      `doWriteObject` in class `StandardSession`
    Parameters:
      `stream` - The output stream to write to
    Throws:
      `IOException` - if an input/output error occurs

  - ### removeAttributeInternal

    protected void removeAttributeInternal(String name, boolean notify, boolean addDeltaRequest)

  - ### getLastTimeReplicated

    public long getLastTimeReplicated()
    Specified by:
      `getLastTimeReplicated` in interface `ReplicatedMapEntry`
    Returns:
      the last replicate time.

  - ### getVersion

    public long getVersion()
    Description copied from interface: `ReplicatedMapEntry`
    For accuracy checking, a serialized attribute can contain a version number This number increases as modifications are made to the data. The replicated map can use this to ensure accuracy on a periodic basis
    Specified by:
      `getVersion` in interface `ReplicatedMapEntry`
    Returns:
      long - the version number or -1 if the data is not versioned

  - ### setLastTimeReplicated

    public void setLastTimeReplicated(long lastTimeReplicated)
    Description copied from interface: `ReplicatedMapEntry`
    Set the last replicate time.
    Specified by:
      `setLastTimeReplicated` in interface `ReplicatedMapEntry`
    Parameters:
      `lastTimeReplicated` - New timestamp

  - ### setVersion

    public void setVersion(long version)
    Description copied from interface: `ReplicatedMapEntry`
    Forces a certain version to a replicated map entry
    Specified by:
      `setVersion` in interface `ReplicatedMapEntry`
    Parameters:
      `version` - long

  - ### setAccessCount

    protected void setAccessCount(int count)