tessl/maven-org-atmosphere--atmosphere-runtime
The Atmosphere Framework runtime providing 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.
—
Pending
annotations.mddocs/
Annotation-Based Services
Declarative service configuration using annotations for HTTP method mapping, event handling, parameter injection, and component registration. This provides a simplified programming model for building Atmosphere applications.
Capabilities
Service Configuration Annotations
Core annotations for defining Atmosphere services with declarative configuration.
/**
* Mark classes as Atmosphere services with path mapping and configuration
*/
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface AtmosphereHandlerService {
/**
* URL path pattern for this service
* @return path pattern string
*/
String path() default "/";
/**
* Broadcaster to use for this service
* @return Broadcaster class
*/
Class<? extends Broadcaster> broadcaster() default Broadcaster.class;
/**
* Interceptors to apply to this service
* @return array of AtmosphereInterceptor classes
*/
Class<? extends AtmosphereInterceptor>[] interceptors() default {};
/**
* Atmosphere properties for configuration
* @return array of property key-value pairs
*/
String[] atmosphereConfig() default {};
}
/**
* Managed service with automatic lifecycle management
*/
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface ManagedService {
/**
* URL path pattern for this managed service
* @return path pattern string
*/
String path() default "/";
/**
* Broadcaster to use for this service
* @return Broadcaster class
*/
Class<? extends Broadcaster> broadcaster() default Broadcaster.class;
/**
* Atmosphere configuration properties
* @return array of property key-value pairs
*/
String[] atmosphereConfig() default {};
}
/**
* Meteor-style service configuration
*/
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface MeteorService {
/**
* URL path pattern
* @return path string
*/
String path() default "/";
/**
* Serializer class for message processing
* @return Serializer class
*/
Class<?> serializer() default Object.class;
}Usage Examples:
@AtmosphereHandlerService(path = "/chat/{room}")
public class ChatHandler implements AtmosphereHandler {
// Handler implementation
}
@ManagedService(path = "/api/notifications")
public class NotificationService {
// Managed service methods
}
@MeteorService(path = "/meteor/data")
public class DataService {
// Meteor-style service
}HTTP Method Mapping Annotations
Annotations for mapping HTTP methods to service methods in managed services.
/**
* Map method to HTTP GET requests
*/
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface Get {
}
/**
* Map method to HTTP POST requests
*/
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface Post {
}
/**
* Map method to HTTP PUT requests
*/
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface Put {
}
/**
* Map method to HTTP DELETE requests
*/
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface Delete {
}Usage Examples:
@ManagedService(path = "/api/users")
public class UserService {
@Get
public void onConnect(AtmosphereResource resource) {
resource.suspend();
}
@Post
public void onPost(AtmosphereResource resource) {
// Handle POST request
}
@Put
public void onPut(AtmosphereResource resource) {
// Handle PUT request
}
@Delete
public void onDelete(AtmosphereResource resource) {
// Handle DELETE request
}
}Event Handling Annotations
Annotations for handling lifecycle events and messages in managed services.
/**
* Mark method to be called when resource is ready (suspended)
*/
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface Ready {
}
/**
* Mark method to be called when client disconnects
*/
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface Disconnect {
}
/**
* Mark method to be called when connection is resumed
*/
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface Resume {
}
/**
* Mark method to handle incoming messages
*/
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface Message {
/**
* Encoder classes for outgoing messages
* @return array of Encoder classes
*/
Class<? extends Encoder>[] encoders() default {};
/**
* Decoder classes for incoming messages
* @return array of Decoder classes
*/
Class<? extends Decoder>[] decoders() default {};
}
/**
* Mark method to handle heartbeat events
*/
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface Heartbeat {
}Usage Examples:
@ManagedService(path = "/chat")
public class ChatService {
@Ready
public void onReady(AtmosphereResource resource) {
System.out.println("Client connected and ready");
}
@Message(decoders = {JsonDecoder.class}, encoders = {JsonEncoder.class})
public ChatMessage onMessage(ChatMessage message) {
// Process incoming chat message
return new ChatMessage("Echo: " + message.getText());
}
@Disconnect
public void onDisconnect(AtmosphereResourceEvent event) {
System.out.println("Client disconnected");
}
@Resume
public void onResume(AtmosphereResourceEvent event) {
System.out.println("Connection resumed");
}
@Heartbeat
public void onHeartbeat(AtmosphereResourceEvent event) {
System.out.println("Heartbeat received");
}
}Parameter Injection Annotations
Annotations for injecting parameters and values into service method parameters.
/**
* Inject path parameters from URL patterns
*/
@Target({ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
public @interface PathParam {
/**
* Name of the path parameter to inject
* @return parameter name
*/
String value();
}
/**
* Specify message delivery targets
*/
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface DeliverTo {
/**
* Delivery target specification
* @return target specification
*/
String value() default "";
}Usage Examples:
@ManagedService(path = "/chat/{room}/{user}")
public class ChatRoomService {
@Get
public void joinRoom(@PathParam("room") String roomId,
@PathParam("user") String userId,
AtmosphereResource resource) {
System.out.println("User " + userId + " joining room " + roomId);
resource.suspend();
}
@Message
@DeliverTo("/chat/{room}")
public String onMessage(@PathParam("room") String roomId,
String message) {
return "Room " + roomId + ": " + message;
}
}Component Registration Annotations
Annotations for registering custom Atmosphere components and services.
/**
* Register custom Broadcaster implementations
*/
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface BroadcasterService {
}
/**
* Register AtmosphereHandler implementations
*/
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface AtmosphereHandlerService {
String path() default "/";
Class<? extends Broadcaster> broadcaster() default Broadcaster.class;
Class<? extends AtmosphereInterceptor>[] interceptors() default {};
}
/**
* Register AtmosphereInterceptor implementations
*/
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface AtmosphereInterceptorService {
}
/**
* Register WebSocketHandler implementations
*/
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface WebSocketHandlerService {
/**
* Path pattern for WebSocket handler
* @return path string
*/
String path() default "/";
/**
* Broadcaster to use
* @return Broadcaster class
*/
Class<? extends Broadcaster> broadcaster() default Broadcaster.class;
}
/**
* Register WebSocketProtocol implementations
*/
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface WebSocketProtocolService {
}
/**
* Register BroadcasterCache implementations
*/
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface BroadcasterCacheService {
}
/**
* Register BroadcasterFactory implementations
*/
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface BroadcasterFactoryService {
}Usage Examples:
@BroadcasterService
public class CustomBroadcaster extends DefaultBroadcaster {
// Custom broadcaster implementation
}
@AtmosphereInterceptorService
public class LoggingInterceptor implements AtmosphereInterceptor {
// Custom interceptor implementation
}
@WebSocketHandlerService(path = "/websocket/custom")
public class CustomWebSocketHandler implements WebSocketHandler {
// Custom WebSocket handler
}
@BroadcasterCacheService
public class RedisBroadcasterCache implements BroadcasterCache {
// Redis-based cache implementation
}Scope and Lifecycle Annotations
Annotations for controlling component scope and lifecycle management.
/**
* Mark service as singleton instance
*/
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface Singleton {
}Usage Examples:
@ManagedService(path = "/global-counter")
@Singleton
public class GlobalCounterService {
private int counter = 0;
@Message
public int incrementCounter() {
return ++counter;
}
}Message Processing Interfaces
Interfaces for encoding and decoding messages in managed services.
/**
* Decode incoming messages from clients
*/
public interface Decoder<T, U> {
/**
* Decode incoming message
* @param s input message to decode
* @return decoded object
*/
U decode(T s);
}
/**
* Encode outgoing messages to clients
*/
public interface Encoder<T, U> {
/**
* Encode outgoing message
* @param s object to encode
* @return encoded message
*/
U encode(T s);
}Usage Examples:
public class JsonDecoder implements Decoder<String, ChatMessage> {
@Override
public ChatMessage decode(String json) {
// Parse JSON string to ChatMessage object
return gson.fromJson(json, ChatMessage.class);
}
}
public class JsonEncoder implements Encoder<ChatMessage, String> {
@Override
public String encode(ChatMessage message) {
// Convert ChatMessage to JSON string
return gson.toJson(message);
}
}
@ManagedService(path = "/chat")
public class ChatService {
@Message(decoders = {JsonDecoder.class}, encoders = {JsonEncoder.class})
public ChatMessage onMessage(ChatMessage incoming) {
// Process typed message objects instead of raw strings
return new ChatMessage("Processed: " + incoming.getText());
}
}Complete Service Example
@ManagedService(path = "/api/chat/{room}")
@Singleton
public class CompleteChatService {
private final Map<String, List<String>> roomHistory = new ConcurrentHashMap<>();
@Get
public void onConnect(@PathParam("room") String roomId,
AtmosphereResource resource) {
System.out.println("New connection to room: " + roomId);
// Send room history to new client
List<String> history = roomHistory.getOrDefault(roomId, new ArrayList<>());
for (String msg : history) {
resource.write(msg);
}
resource.suspend();
}
@Ready
public void onReady(@PathParam("room") String roomId,
AtmosphereResource resource) {
resource.getBroadcaster().broadcast("User joined room " + roomId);
}
@Message(decoders = {JsonDecoder.class}, encoders = {JsonEncoder.class})
@DeliverTo("/api/chat/{room}")
public ChatMessage onMessage(@PathParam("room") String roomId,
ChatMessage message) {
// Store message in room history
roomHistory.computeIfAbsent(roomId, k -> new ArrayList<>())
.add(message.getText());
// Return processed message for broadcast
return new ChatMessage("[" + roomId + "] " + message.getText());
}
@Disconnect
public void onDisconnect(@PathParam("room") String roomId,
AtmosphereResourceEvent event) {
System.out.println("User left room: " + roomId);
event.getResource().getBroadcaster()
.broadcast("User left room " + roomId);
}
@Heartbeat
public void onHeartbeat(AtmosphereResourceEvent event) {
// Handle heartbeat to keep connection alive
System.out.println("Heartbeat from: " + event.getResource().uuid());
}
}Install with Tessl CLI
npx tessl i tessl/maven-org-atmosphere--atmosphere-runtime