0
# Broadcasting System
1

2
Message distribution system with support for multiple scopes, policies, and targeted broadcasting. The broadcasting system is the core mechanism for delivering messages to connected clients in real-time.
3

4
## Capabilities
5

6
### Broadcaster Interface
7

8
Core broadcasting mechanism for message delivery to suspended resources with support for different scopes and policies.
9

10
```java { .api }
11
/**
12
 * Core broadcasting mechanism for message delivery to suspended resources
13
 */
14
public interface Broadcaster {
15
    /**
16
     * Broadcast message to all connected resources asynchronously
17
     * @param msg message to broadcast
18
     * @return Future for async operation
19
     */
20
    public Future<Object> broadcast(Object msg);
21
    
22
    /**
23
     * Broadcast message to a specific resource
24
     * @param msg message to broadcast  
25
     * @param resource target AtmosphereResource
26
     * @return Future for async operation
27
     */
28
    public Future<Object> broadcast(Object msg, AtmosphereResource resource);
29
    
30
    /**
31
     * Broadcast message to a set of resources
32
     * @param msg message to broadcast
33
     * @param resources Set of target AtmosphereResources
34
     * @return Future for async operation
35
     */
36
    public Future<Object> broadcast(Object msg, Set<AtmosphereResource> resources);
37
    
38
    /**
39
     * Schedule delayed broadcast
40
     * @param msg message to broadcast
41
     * @param time delay time
42
     * @param unit TimeUnit for delay
43
     * @return Future for scheduled operation
44
     */
45
    public Future<Object> delayBroadcast(Object msg, long time, TimeUnit unit);
46
    
47
    /**
48
     * Schedule repeated broadcasts at fixed rate
49
     * @param msg message to broadcast
50
     * @param period time period between broadcasts
51
     * @param unit TimeUnit for period
52
     * @return Future for scheduled operation
53
     */
54
    public Future<Object> scheduleFixedBroadcast(Object msg, long period, TimeUnit unit);
55
    
56
    /**
57
     * Add AtmosphereResource to this broadcaster
58
     * @param resource AtmosphereResource to add
59
     * @return this broadcaster for chaining
60
     */
61
    public Broadcaster addAtmosphereResource(AtmosphereResource resource);
62
    
63
    /**
64
     * Remove AtmosphereResource from this broadcaster
65
     * @param resource AtmosphereResource to remove
66
     * @return this broadcaster for chaining
67
     */
68
    public Broadcaster removeAtmosphereResource(AtmosphereResource resource);
69
    
70
    /**
71
     * Get all resources associated with this broadcaster
72
     * @return Collection of AtmosphereResources
73
     */
74
    public Collection<AtmosphereResource> getAtmosphereResources();
75
    
76
    /**
77
     * Set the scope for this broadcaster
78
     * @param scope SCOPE enum (REQUEST, APPLICATION, VM)
79
     * @return this broadcaster for chaining
80
     */
81
    public Broadcaster setScope(SCOPE scope);
82
    
83
    /**
84
     * Get the current scope
85
     * @return SCOPE enum value
86
     */
87
    public SCOPE getScope();
88
    
89
    /**
90
     * Set resource policy for handling resource limits
91
     * @param policy POLICY enum (FIFO, REJECT)
92
     * @return this broadcaster for chaining
93
     */
94
    public Broadcaster setPolicy(POLICY policy);
95
    
96
    /**
97
     * Get unique identifier for this broadcaster
98
     * @return broadcaster ID
99
     */
100
    public String getID();
101
    
102
    /**
103
     * Destroy this broadcaster and cleanup resources
104
     */
105
    public void destroy();
106
    
107
    /**
108
     * Check if broadcaster has been destroyed
109
     * @return true if destroyed
110
     */
111
    public boolean isDestroyed();
112
    
113
    /**
114
     * Add broadcast filter for message processing
115
     * @param filter BroadcastFilter instance
116
     * @return this broadcaster for chaining
117
     */
118
    public Broadcaster addFilter(BroadcastFilter filter);
119
    
120
    /**
121
     * Remove broadcast filter
122
     * @param filter BroadcastFilter to remove
123
     * @return this broadcaster for chaining
124
     */
125
    public Broadcaster removeFilter(BroadcastFilter filter);
126
}
127
```
128

129
**Usage Examples:**
130

131
```java
132
// Get broadcaster and broadcast to all
133
Broadcaster broadcaster = BroadcasterFactory.getDefault().lookup("/chat", true);
134
broadcaster.broadcast("Hello everyone!");
135

136
// Broadcast to specific resource
137
broadcaster.broadcast("Private message", specificResource);
138

139
// Scheduled broadcasting
140
broadcaster.scheduleFixedBroadcast("Heartbeat", 30, TimeUnit.SECONDS);
141

142
// Add/remove resources
143
broadcaster.addAtmosphereResource(newResource);
144
broadcaster.removeAtmosphereResource(disconnectedResource);
145

146
// Set scope and policy
147
broadcaster.setScope(Broadcaster.SCOPE.APPLICATION)
148
          .setPolicy(Broadcaster.POLICY.FIFO);
149
```
150

151
### DefaultBroadcaster
152

153
Default implementation of the Broadcaster interface providing standard broadcasting functionality.
154

155
```java { .api }
156
/**
157
 * Default Broadcaster implementation
158
 */
159
public class DefaultBroadcaster implements Broadcaster {
160
    /**
161
     * Create DefaultBroadcaster with ID
162
     * @param id unique identifier
163
     * @param config AtmosphereConfig instance
164
     */
165
    public DefaultBroadcaster(String id, AtmosphereConfig config);
166
    
167
    /**
168
     * Set broadcast timeout
169
     * @param time timeout value
170
     * @param unit TimeUnit for timeout
171
     * @return this broadcaster
172
     */
173
    public DefaultBroadcaster setTimeout(long time, TimeUnit unit);
174
    
175
    /**
176
     * Set maximum number of suspended resources
177
     * @param maxSuspendResource maximum resources
178
     * @return this broadcaster
179
     */
180
    public DefaultBroadcaster setMaxSuspendResource(long maxSuspendResource);
181
}
182
```
183

184
### BroadcasterFactory
185

186
Factory interface for creating and managing Broadcaster instances with lookup and lifecycle management.
187

188
```java { .api }
189
/**
190
 * Factory for creating and managing Broadcaster instances
191
 */
192
public interface BroadcasterFactory {
193
    /**
194
     * Lookup or create broadcaster by ID
195
     * @param id broadcaster identifier
196
     * @param createIfNull create if doesn't exist
197
     * @return Broadcaster instance
198
     */
199
    public Broadcaster lookup(Object id, boolean createIfNull);
200
    
201
    /**
202
     * Lookup broadcaster by ID (read-only)
203
     * @param id broadcaster identifier  
204
     * @return Broadcaster instance or null
205
     */
206
    public Broadcaster lookup(Object id);
207
    
208
    /**
209
     * Create new broadcaster with generated ID
210
     * @return new Broadcaster instance
211
     */
212
    public Broadcaster create();
213
    
214
    /**
215
     * Create new broadcaster with specific ID
216
     * @param id broadcaster identifier
217
     * @return new Broadcaster instance
218
     */
219
    public Broadcaster create(Object id);
220
    
221
    /**
222
     * Destroy specific broadcaster
223
     * @param broadcaster Broadcaster to destroy
224
     * @return true if destroyed
225
     */
226
    public boolean destroy(Broadcaster broadcaster);
227
    
228
    /**
229
     * Destroy broadcaster by ID
230
     * @param id broadcaster identifier
231
     * @return true if destroyed
232
     */
233
    public boolean destroy(Object id);
234
    
235
    /**
236
     * Destroy all broadcasters and cleanup
237
     * @return this factory
238
     */
239
    public BroadcasterFactory destroy();
240
    
241
    /**
242
     * Get all active broadcasters
243
     * @return Collection of all Broadcasters
244
     */
245
    public Collection<Broadcaster> lookupAll();
246
    
247
    /**
248
     * Remove AtmosphereResource from all broadcasters
249
     * @param resource AtmosphereResource to remove
250
     * @return this factory
251
     */
252
    public BroadcasterFactory removeAllAtmosphereResource(AtmosphereResource resource);
253
    
254
    /**
255
     * Get default factory instance
256
     * @return default BroadcasterFactory
257
     */
258
    public static BroadcasterFactory getDefault();
259
}
260
```
261

262
**Usage Examples:**
263

264
```java
265
// Get default factory
266
BroadcasterFactory factory = BroadcasterFactory.getDefault();
267

268
// Lookup/create broadcasters
269
Broadcaster chatBroadcaster = factory.lookup("/chat", true);
270
Broadcaster newsBroadcaster = factory.create("/news");
271

272
// Manage broadcasters
273
Collection<Broadcaster> allBroadcasters = factory.lookupAll();
274
factory.destroy(chatBroadcaster);
275

276
// Cleanup resources
277
factory.removeAllAtmosphereResource(disconnectedResource);
278
factory.destroy(); // Destroy all
279
```
280

281
### MetaBroadcaster
282

283
Interface for broadcasting across multiple Broadcaster instances, enabling cross-broadcaster message distribution.
284

285
```java { .api }
286
/**
287
 * Allows broadcasting across multiple Broadcasters
288
 */
289
public interface MetaBroadcaster {
290
    /**
291
     * Broadcast message to specific broadcaster paths
292
     * @param to path or paths to broadcast to
293
     * @param message message to broadcast
294
     * @return MetaBroadcaster for chaining
295
     */
296
    public MetaBroadcaster broadcastTo(String to, Object message);
297
    
298
    /**
299
     * Broadcast to multiple broadcaster paths
300
     * @param to collection of paths
301
     * @param message message to broadcast
302
     * @return MetaBroadcaster for chaining
303
     */
304
    public MetaBroadcaster broadcastTo(Collection<String> to, Object message);
305
    
306
    /**
307
     * Add broadcaster to meta-broadcaster group
308
     * @param broadcaster Broadcaster to add
309
     * @return MetaBroadcaster for chaining
310
     */
311
    public MetaBroadcaster addBroadcaster(Broadcaster broadcaster);
312
    
313
    /**
314
     * Remove broadcaster from meta-broadcaster group
315
     * @param broadcaster Broadcaster to remove
316
     * @return MetaBroadcaster for chaining
317
     */
318
    public MetaBroadcaster removeBroadcaster(Broadcaster broadcaster);
319
    
320
    /**
321
     * Get default MetaBroadcaster instance
322
     * @return MetaBroadcaster instance
323
     */
324
    public static MetaBroadcaster getDefault();
325
}
326
```
327

328
**Usage Examples:**
329

330
```java
331
// Get meta-broadcaster
332
MetaBroadcaster metaBroadcaster = MetaBroadcaster.getDefault();
333

334
// Broadcast to multiple channels
335
metaBroadcaster.broadcastTo("/chat", "Message for chat");
336
metaBroadcaster.broadcastTo("/news", "News update");
337

338
// Broadcast to multiple paths at once
339
List<String> paths = Arrays.asList("/chat", "/news", "/alerts");
340
metaBroadcaster.broadcastTo(paths, "System announcement");
341
```
342

343
### Broadcast Filtering
344

345
Interface for filtering and transforming messages before broadcast delivery.
346

347
```java { .api }
348
/**
349
 * Filter messages before broadcasting
350
 */
351
public interface BroadcastFilter {
352
    /**
353
     * Filter and potentially transform broadcast message
354
     * @param originalMessage original message to broadcast
355
     * @return BroadcastAction containing filtered message and action
356
     */
357
    public BroadcastAction filter(Object originalMessage);
358
    
359
    /**
360
     * Filter message for specific resource
361
     * @param resource target AtmosphereResource
362
     * @param originalMessage original message
363
     * @param messageToFilter message being filtered
364
     * @return BroadcastAction with filtering result
365
     */
366
    public BroadcastAction filter(AtmosphereResource resource, Object originalMessage, Object messageToFilter);
367
}
368

369
/**
370
 * Result of broadcast filtering operation
371
 */
372
public static class BroadcastAction {
373
    /**
374
     * Action to take with filtered message
375
     */
376
    public enum ACTION {
377
        CONTINUE,  // Continue with broadcast
378
        ABORT     // Abort broadcast
379
    }
380
    
381
    /**
382
     * Get the filtered message
383
     * @return filtered message object
384
     */
385
    public Object message();
386
    
387
    /**
388
     * Get the action to take
389
     * @return ACTION enum value
390
     */
391
    public ACTION action();
392
}
393
```
394

395
### Broadcaster Lifecycle and Events
396

397
Event listener for monitoring broadcaster lifecycle and activity.
398

399
```java { .api }
400
/**
401
 * Listener for broadcaster events
402
 */
403
public interface BroadcasterListener {
404
    /**
405
     * Called when resource is added to broadcaster
406
     * @param broadcaster the Broadcaster
407
     * @param resource added AtmosphereResource
408
     */
409
    public void onAddAtmosphereResource(Broadcaster broadcaster, AtmosphereResource resource);
410
    
411
    /**
412
     * Called when resource is removed from broadcaster
413
     * @param broadcaster the Broadcaster
414
     * @param resource removed AtmosphereResource
415
     */
416
    public void onRemoveAtmosphereResource(Broadcaster broadcaster, AtmosphereResource resource);
417
    
418
    /**
419
     * Called when broadcaster is destroyed
420
     * @param broadcaster the destroyed Broadcaster
421
     */
422
    public void onDestroy(Broadcaster broadcaster);
423
    
424
    /**
425
     * Called when broadcast completes
426
     * @param broadcaster the Broadcaster
427
     * @param message the broadcast message
428
     * @param resources target resources
429
     */
430
    public void onComplete(Broadcaster broadcaster, Object message, Set<AtmosphereResource> resources);
431
}
432
```
433

434
## Scope and Policy Enums
435

436
```java { .api }
437
/**
438
 * Broadcaster scope determines resource sharing
439
 */
440
public enum SCOPE {
441
    REQUEST,     // Resources scoped to current request only
442
    APPLICATION, // Resources shared across web application
443
    VM          // Resources shared across entire JVM
444
}
445

446
/**
447
 * Policy for handling resource limits
448
 */
449
public enum POLICY {
450
    FIFO,   // First In, First Out - remove oldest when limit reached
451
    REJECT  // Reject new resources when limit is reached
452
}
453
```
454

455
**Usage Examples:**
456

457
```java
458
// Set broadcaster scope
459
broadcaster.setScope(Broadcaster.SCOPE.APPLICATION);
460

461
// Set resource policy  
462
broadcaster.setPolicy(Broadcaster.POLICY.FIFO);
463

464
// Add broadcaster listener
465
broadcaster.addBroadcasterListener(new BroadcasterListener() {
466
    @Override
467
    public void onAddAtmosphereResource(Broadcaster b, AtmosphereResource r) {
468
        System.out.println("Resource added: " + r.uuid());
469
    }
470
    
471
    @Override
472
    public void onComplete(Broadcaster b, Object message, Set<AtmosphereResource> resources) {
473
        System.out.println("Broadcast completed to " + resources.size() + " resources");
474
    }
475
});
476

477
// Add broadcast filter
478
broadcaster.addFilter(new BroadcastFilter() {
479
    @Override
480
    public BroadcastAction filter(Object originalMessage) {
481
        // Transform message or abort broadcast
482
        if (originalMessage == null) {
483
            return new BroadcastAction(null, BroadcastAction.ACTION.ABORT);
484
        }
485
        String filtered = originalMessage.toString().toUpperCase();
486
        return new BroadcastAction(filtered, BroadcastAction.ACTION.CONTINUE);
487
    }
488
});
489
```