0
# Session Management
1

2
HTTP session tracking and management with configurable persistence stores, session ID generation, timeout handling, clustering support, and event notification. Includes support for standard in-memory sessions, persistent file-based sessions, and JDBC-based session storage.
3

4
## Capabilities
5

6
### Manager Interface
7

8
Core session manager interface for managing HTTP sessions.
9

10
```java { .api }
11
public interface Manager {
12
    // Context
13
    Context getContext();
14
    void setContext(Context context);
15
    
16
    // Session ID generator
17
    SessionIdGenerator getSessionIdGenerator();
18
    void setSessionIdGenerator(SessionIdGenerator sessionIdGenerator);
19
    
20
    // Session operations
21
    void add(Session session);
22
    Session createSession(String sessionId);
23
    Session createEmptySession();
24
    Session findSession(String id) throws IOException;
25
    Session[] findSessions();
26
    void remove(Session session);
27
    void remove(Session session, boolean update);
28
    void changeSessionId(Session session, String newId);
29

30
    // Configuration
31
    int getMaxInactiveInterval();
32
    void setMaxInactiveInterval(int interval);
33
    
34
    // Statistics
35
    int getActiveSessions();
36
    long getExpiredSessions();
37
    void setExpiredSessions(long expiredSessions);
38
    int getRejectedSessions();
39
    long getSessionCounter();
40
    void setSessionCounter(long sessionCounter);
41
    int getMaxActive();
42
    void setMaxActive(int maxActive);
43
    int getSessionMaxAliveTime();
44
    void setSessionMaxAliveTime(int sessionMaxAliveTime);
45
    int getSessionAverageAliveTime();
46
    int getSessionCreateRate();
47
    int getSessionExpireRate();
48
    
49
    // Persistence
50
    void load() throws ClassNotFoundException, IOException;
51
    void unload() throws IOException;
52
    
53
    // Background processing
54
    void backgroundProcess();
55
    
56
    // Will support persistence
57
    boolean willAttributeDistribute(String name, Object value);
58

59
    // Session ID rotation
60
    default String rotateSessionId(Session session);
61

62
    // Listener notification configuration
63
    default boolean getNotifyBindingListenerOnUnchangedValue();
64
    void setNotifyBindingListenerOnUnchangedValue(boolean notifyBindingListenerOnUnchangedValue);
65
    default boolean getNotifyAttributeListenerOnUnchangedValue();
66
    void setNotifyAttributeListenerOnUnchangedValue(boolean notifyAttributeListenerOnUnchangedValue);
67

68
    // Session activity tracking
69
    default boolean getSessionActivityCheck();
70
    void setSessionActivityCheck(boolean sessionActivityCheck);
71
    default boolean getSessionLastAccessAtStart();
72
    void setSessionLastAccessAtStart(boolean sessionLastAccessAtStart);
73

74
    // Event listeners
75
    void addPropertyChangeListener(PropertyChangeListener listener);
76
    void removePropertyChangeListener(PropertyChangeListener listener);
77
}
78
```
79

80
### Session Interface
81

82
Internal representation of an HTTP session.
83

84
```java { .api }
85
public interface Session {
86
    // Session ID
87
    String getId();
88
    String getIdInternal();
89
    void setId(String id);
90
    void setId(String id, boolean notify);
91
    
92
    // Manager
93
    Manager getManager();
94
    void setManager(Manager manager);
95
    
96
    // Timing
97
    long getCreationTime();
98
    long getCreationTimeInternal();
99
    void setCreationTime(long time);
100
    long getLastAccessedTime();
101
    long getLastAccessedTimeInternal();
102
    long getThisAccessedTime();
103
    long getThisAccessedTimeInternal();
104
    long getIdleTime();
105
    long getIdleTimeInternal();
106
    int getMaxInactiveInterval();
107
    void setMaxInactiveInterval(int interval);
108
    
109
    // State
110
    void setNew(boolean isNew);
111
    boolean isValid();
112
    void setValid(boolean isValid);
113
    
114
    // Lifecycle
115
    void access();
116
    void endAccess();
117
    void expire();
118
    void recycle();
119
    
120
    // Attributes
121
    Object getNote(String name);
122
    void setNote(String name, Object value);
123
    void removeNote(String name);
124
    Iterator<String> getNoteNames();
125
    
126
    // Authentication
127
    Principal getPrincipal();
128
    void setPrincipal(Principal principal);
129
    String getAuthType();
130
    void setAuthType(String authType);
131
    
132
    // HTTP session
133
    HttpSession getSession();
134

135
    // Session ID change notification
136
    void tellChangedSessionId(String newId, String oldId, boolean notifySessionListeners, boolean notifyContainerListeners);
137

138
    // Attribute distribution check
139
    boolean isAttributeDistributable(String name, Object value);
140

141
    // Event constants
142
    String SESSION_CREATED_EVENT = "createSession";
143
    String SESSION_DESTROYED_EVENT = "destroySession";
144
    String SESSION_ACTIVATED_EVENT = "activateSession";
145
    String SESSION_PASSIVATED_EVENT = "passivateSession";
146

147
    // Event listeners
148
    void addSessionListener(SessionListener listener);
149
    void removeSessionListener(SessionListener listener);
150
}
151
```
152

153
### Session ID Generator
154

155
Interface for generating session IDs.
156

157
```java { .api }
158
public interface SessionIdGenerator {
159
    // JVM route (for clustering)
160
    String getJvmRoute();
161
    void setJvmRoute(String jvmRoute);
162
    
163
    // Session ID length
164
    int getSessionIdLength();
165
    void setSessionIdLength(int sessionIdLength);
166
    
167
    // Generation
168
    String generateSessionId();
169
    String generateSessionId(String route);
170
}
171
```
172

173
### Store Interface
174

175
Persistent session storage.
176

177
```java { .api }
178
public interface Store {
179
    // Manager
180
    Manager getManager();
181
    void setManager(Manager manager);
182
    
183
    // Size
184
    int getSize() throws IOException;
185
    
186
    // Operations
187
    String[] keys() throws IOException;
188
    Session load(String id) throws ClassNotFoundException, IOException;
189
    void remove(String id) throws IOException;
190
    void clear() throws IOException;
191
    void save(Session session) throws IOException;
192
    
193
    // Event listeners
194
    void addPropertyChangeListener(PropertyChangeListener listener);
195
    void removePropertyChangeListener(PropertyChangeListener listener);
196
}
197
```
198

199
## Usage Examples
200

201
### Custom Session Configuration
202

203
```java
204
import org.apache.catalina.startup.Tomcat;
205
import org.apache.catalina.Context;
206
import org.apache.catalina.Manager;
207
import org.apache.catalina.session.StandardManager;
208

209
public class SessionConfigExample {
210
    public static void main(String[] args) throws Exception {
211
        Tomcat tomcat = new Tomcat();
212
        tomcat.setPort(8080);
213
        
214
        Context ctx = tomcat.addContext("", System.getProperty("java.io.tmpdir"));
215
        
216
        // Configure session manager
217
        StandardManager manager = new StandardManager();
218
        manager.setMaxActiveSessions(1000);
219
        manager.getSessionIdGenerator().setSessionIdLength(32);
220
        ctx.setManager(manager);
221
        
222
        // Configure session timeout (minutes)
223
        ctx.setSessionTimeout(30);
224
        
225
        tomcat.start();
226
        tomcat.getServer().await();
227
    }
228
}
229
```
230