0
# Atmosphere Runtime
1

2
The Atmosphere Framework runtime provides comprehensive support for building real-time, event-driven web applications with transparent transport protocol support including WebSockets, Server Sent Events, Long-Polling, HTTP Streaming, and JSONP. It enables scalable real-time applications with automatic protocol fallback and cross-platform compatibility across all Servlet-based servers.
3

4
## Package Information
5

6
- **Package Name**: atmosphere-runtime
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Group ID**: org.atmosphere
10
- **Artifact ID**: atmosphere-runtime
11
- **Installation**: Add to Maven `pom.xml`:
12
  ```xml
13
  <dependency>
14
    <groupId>org.atmosphere</groupId>
15
    <artifactId>atmosphere-runtime</artifactId>
16
    <version>3.0.13</version>
17
  </dependency>
18
  ```
19

20
## Core Imports
21

22
```java
23
import org.atmosphere.cpr.*;
24
import org.atmosphere.config.service.*;
25
import org.atmosphere.websocket.*;
26
```
27

28
Common patterns:
29
```java
30
import org.atmosphere.cpr.AtmosphereFramework;
31
import org.atmosphere.cpr.AtmosphereResource;
32
import org.atmosphere.cpr.AtmosphereHandler;
33
import org.atmosphere.cpr.Broadcaster;
34
import org.atmosphere.config.service.AtmosphereHandlerService;
35
import org.atmosphere.config.service.ManagedService;
36
```
37

38
## Basic Usage
39

40
### AtmosphereHandler Approach
41

42
```java
43
import org.atmosphere.cpr.*;
44
import org.atmosphere.config.service.AtmosphereHandlerService;
45

46
@AtmosphereHandlerService(path = "/chat")
47
public class ChatHandler implements AtmosphereHandler {
48
    
49
    @Override
50
    public void onRequest(AtmosphereResource resource) throws IOException {
51
        // Suspend the connection for real-time updates
52
        resource.suspend();
53
    }
54
    
55
    @Override
56
    public void onStateChange(AtmosphereResourceEvent event) throws IOException {
57
        // Handle broadcast messages
58
        if (event.getMessage() != null) {
59
            event.getResource().write(event.getMessage().toString());
60
        }
61
    }
62
    
63
    @Override
64
    public void destroy() {
65
        // Cleanup resources
66
    }
67
}
68
```
69

70
### Managed Service Approach
71

72
```java
73
import org.atmosphere.config.service.*;
74

75
@ManagedService(path = "/managed-chat")
76
public class ManagedChatService {
77
    
78
    @Get
79
    public void onOpen(AtmosphereResource resource) {
80
        resource.suspend();
81
    }
82
    
83
    @Message
84
    public void onMessage(String message) {
85
        // Handle incoming message
86
        // Broadcast to other connected clients
87
    }
88
    
89
    @Disconnect
90
    public void onDisconnect(AtmosphereResourceEvent event) {
91
        // Handle client disconnection
92
    }
93
}
94
```
95

96
### Broadcasting Messages
97

98
```java
99
import org.atmosphere.cpr.*;
100

101
// Get broadcaster factory and create/lookup broadcaster
102
BroadcasterFactory factory = BroadcasterFactory.getDefault();
103
Broadcaster broadcaster = factory.lookup("/chat", true);
104

105
// Broadcast message to all connected resources
106
broadcaster.broadcast("Hello, everyone!");
107

108
// Broadcast to specific resource
109
broadcaster.broadcast("Private message", atmosphereResource);
110
```
111

112
## Architecture
113

114
The Atmosphere Framework is built around several core components:
115

116
- **AtmosphereFramework**: Central configuration and management hub
117
- **AtmosphereResource**: Represents a suspended HTTP connection with broadcast capabilities
118
- **Broadcaster**: Message distribution system supporting multiple scopes and policies
119
- **AtmosphereHandler**: Request processing interface for custom application logic
120
- **Transport Abstraction**: Automatic fallback between WebSocket, SSE, Long-Polling, and other transports
121
- **Annotation-Based Configuration**: Declarative service configuration with lifecycle management
122
- **Interceptor Pipeline**: Request/response processing and protocol adaptation
123
- **Caching System**: Message persistence and replay for connection recovery
124

125
## Capabilities
126

127
### Core Framework
128

129
Central framework management including configuration, resource handling, and the primary AtmosphereResource interface for managing suspended connections and broadcasting.
130

131
```java { .api }
132
public class AtmosphereFramework {
133
    public AtmosphereFramework init();
134
    public void destroy();
135
    public AtmosphereFramework addAtmosphereHandler(String mapping, AtmosphereHandler handler);
136
    public BroadcasterFactory getBroadcasterFactory();
137
    public AtmosphereConfig getAtmosphereConfig();
138
}
139

140
public interface AtmosphereResource {
141
    public AtmosphereResource suspend();
142
    public AtmosphereResource suspend(long timeout);
143
    public AtmosphereResource resume();
144
    public boolean isSuspended();
145
    public Broadcaster getBroadcaster();
146
    public AtmosphereResource setBroadcaster(Broadcaster broadcaster);
147
    public AtmosphereRequest getRequest();
148
    public AtmosphereResponse getResponse();
149
    public TRANSPORT transport();
150
}
151
```
152

153
[Core Framework](./core-framework.md)
154

155
### Broadcasting System
156

157
Message distribution system with support for multiple scopes, policies, and targeted broadcasting. Includes factory management and meta-broadcasting capabilities.
158

159
```java { .api }
160
public interface Broadcaster {
161
    public Future<Object> broadcast(Object msg);
162
    public Future<Object> broadcast(Object msg, AtmosphereResource resource);
163
    public Broadcaster addAtmosphereResource(AtmosphereResource resource);
164
    public Broadcaster removeAtmosphereResource(AtmosphereResource resource);
165
    public void destroy();
166
    public Broadcaster setScope(SCOPE scope);
167
}
168

169
public interface BroadcasterFactory {
170
    public Broadcaster lookup(Object id, boolean createIfNull);
171
    public void destroy();
172
    public Collection<Broadcaster> lookupAll();
173
}
174
```
175

176
[Broadcasting System](./broadcasting.md)
177

178
### Annotation-Based Services
179

180
Declarative service configuration using annotations for HTTP method mapping, event handling, parameter injection, and component registration.
181

182
```java { .api }
183
@AtmosphereHandlerService(path = "/example")
184
@ManagedService(path = "/managed")
185
@Get @Post @Put @Delete
186
@Message @Ready @Disconnect @Resume @Heartbeat
187
@PathParam("param")
188
@BroadcasterService @AtmosphereInterceptorService
189
```
190

191
[Annotation Services](./annotations.md)
192

193
### WebSocket Support
194

195
Complete WebSocket integration including connection management, protocol handling, message processing, and custom protocol implementations.
196

197
```java { .api }
198
public interface WebSocket {
199
    public WebSocket write(String data);
200
    public void close();
201
    public boolean isOpen();
202
    public AtmosphereResource resource();
203
}
204

205
public interface WebSocketHandler {
206
    public void onOpen(WebSocket webSocket);
207
    public void onClose(WebSocket webSocket);
208
    public void onTextMessage(WebSocket webSocket, String message);
209
    public void onByteMessage(WebSocket webSocket, byte[] message);
210
}
211
```
212

213
[WebSocket Support](./websocket.md)
214

215
### Caching System
216

217
Message caching and replay capabilities for connection recovery, with multiple cache implementations and inspection utilities.
218

219
```java { .api }
220
public interface BroadcasterCache {
221
    public void addToCache(String broadcasterId, String uuid, BroadcastMessage message);
222
    public List<Object> retrieveFromCache(String broadcasterId, String uuid);
223
    public void clearCache(String broadcasterId, String uuid);
224
}
225
```
226

227
[Caching System](./caching.md)
228

229
### Interceptor System
230

231
Request/response processing pipeline with built-in interceptors for CORS, heartbeat, protocol handling, and custom processing logic.
232

233
```java { .api }
234
public interface AtmosphereInterceptor {
235
    public Action intercept(AtmosphereResource resource);
236
    public void postInspect(AtmosphereResource resource);
237
    public int priority();
238
}
239
```
240

241
[Interceptor System](./interceptors.md)
242

243
## Transport Types
244

245
```java { .api }
246
public enum TRANSPORT {
247
    POLLING,
248
    LONG_POLLING, 
249
    STREAMING,
250
    WEBSOCKET,
251
    JSONP,
252
    SSE,
253
    AJAX,
254
    HTMLFILE,
255
    CLOSE,
256
    UNDEFINED
257
}
258
```
259

260
## Core Enums and Constants
261

262
```java { .api }
263
public enum SCOPE {
264
    REQUEST,     // Current request only
265
    APPLICATION, // Current web application  
266
    VM          // Entire JVM
267
}
268

269
public enum POLICY {
270
    FIFO,   // First In, First Out
271
    REJECT  // Reject new resources when limit reached
272
}
273
```