Core Framework

/**
 * Central framework entry point for Atmosphere runtime
 */
public class AtmosphereFramework {
    /**
     * Initialize the framework with configuration
     * @return this framework instance for chaining
     */
    public AtmosphereFramework init();
    
    /**
     * Initialize with specific servlet config
     * @param sc ServletConfig for initialization
     * @return this framework instance
     */
    public AtmosphereFramework init(ServletConfig sc);
    
    /**
     * Destroy the framework and cleanup resources
     */
    public void destroy();
    
    /**
     * Add an AtmosphereHandler for a specific path mapping
     * @param mapping URL pattern to handle
     * @param handler AtmosphereHandler instance
     * @return this framework instance
     */
    public AtmosphereFramework addAtmosphereHandler(String mapping, AtmosphereHandler handler);
    
    /**
     * Get the broadcaster factory for managing broadcasters
     * @return BroadcasterFactory instance
     */
    public BroadcasterFactory getBroadcasterFactory();
    
    /**
     * Get the atmosphere configuration
     * @return AtmosphereConfig instance
     */
    public AtmosphereConfig getAtmosphereConfig();
    
    /**
     * Add an interceptor to the processing pipeline
     * @param interceptor AtmosphereInterceptor to add
     * @return this framework instance
     */
    public AtmosphereFramework intercept(AtmosphereInterceptor interceptor);
}

// Initialize framework
AtmosphereFramework framework = new AtmosphereFramework();
framework.init();

// Add handlers
framework.addAtmosphereHandler("/chat/*", new ChatHandler());

// Add interceptors
framework.intercept(new CorsInterceptor());

// Cleanup when done
framework.destroy();

/**
 * Configuration container for the Atmosphere framework
 */
public class AtmosphereConfig {
    /**
     * Get the servlet configuration
     * @return ServletConfig instance
     */
    public ServletConfig getServletConfig();
    
    /**
     * Get the servlet context
     * @return ServletContext instance
     */
    public ServletContext getServletContext();
    
    /**
     * Get initialization parameter by name
     * @param name parameter name
     * @return parameter value or null
     */
    public String getInitParameter(String name);
    
    /**
     * Get all framework properties
     * @return Map of configuration properties
     */
    public Map<String, Object> properties();
    
    /**
     * Get the AtmosphereFramework instance
     * @return AtmosphereFramework
     */
    public AtmosphereFramework framework();
}

/**
 * Encapsulates suspended HTTP connections and provides broadcast mechanism
 */
public interface AtmosphereResource {
    /**
     * Suspend the connection indefinitely for real-time updates
     * @return this resource for chaining
     */
    public AtmosphereResource suspend();
    
    /**
     * Suspend with timeout
     * @param timeout timeout value
     * @return this resource for chaining
     */
    public AtmosphereResource suspend(long timeout);
    
    /**
     * Suspend with timeout and time unit
     * @param timeout timeout value
     * @param timeunit TimeUnit for timeout
     * @return this resource for chaining
     */
    public AtmosphereResource suspend(long timeout, TimeUnit timeunit);
    
    /**
     * Resume the suspended connection
     * @return this resource for chaining
     */
    public AtmosphereResource resume();
    
    /**
     * Check if connection is currently suspended
     * @return true if suspended
     */
    public boolean isSuspended();
    
    /**
     * Check if connection has been resumed
     * @return true if resumed
     */
    public boolean isResumed();
    
    /**
     * Check if connection has been cancelled
     * @return true if cancelled
     */
    public boolean isCancelled();
    
    /**
     * Get the broadcaster associated with this resource
     * @return Broadcaster instance
     */
    public Broadcaster getBroadcaster();
    
    /**
     * Set the broadcaster for this resource
     * @param broadcaster Broadcaster instance
     * @return this resource for chaining
     */
    public AtmosphereResource setBroadcaster(Broadcaster broadcaster);
    
    /**
     * Get the enhanced request object
     * @return AtmosphereRequest instance
     */
    public AtmosphereRequest getRequest();
    
    /**
     * Get the enhanced response object
     * @return AtmosphereResponse instance
     */
    public AtmosphereResponse getResponse();
    
    /**
     * Get the transport type for this connection
     * @return TRANSPORT enum value
     */
    public TRANSPORT transport();
    
    /**
     * Add event listener for resource state changes
     * @param listener AtmosphereResourceEventListener
     * @return this resource for chaining
     */
    public AtmosphereResource addEventListener(AtmosphereResourceEventListener listener);
    
    /**
     * Remove event listener
     * @param listener AtmosphereResourceEventListener to remove
     * @return this resource for chaining
     */
    public AtmosphereResource removeEventListener(AtmosphereResourceEventListener listener);
    
    /**
     * Set whether to resume on broadcast
     * @param resumeOnBroadcast true to resume after broadcast
     * @return this resource for chaining
     */
    public AtmosphereResource resumeOnBroadcast(boolean resumeOnBroadcast);
    
    /**
     * Write data directly to this resource
     * @param data data to write
     * @return this resource for chaining
     */
    public AtmosphereResource write(Object data);
}

public class ChatHandler implements AtmosphereHandler {
    @Override
    public void onRequest(AtmosphereResource resource) throws IOException {
        // Basic suspension
        resource.suspend();
        
        // Suspend with timeout
        resource.suspend(30, TimeUnit.SECONDS);
        
        // Add event listener
        resource.addEventListener(new AtmosphereResourceEventListener() {
            @Override
            public void onSuspend(AtmosphereResourceEvent event) {
                System.out.println("Resource suspended");
            }
            
            @Override
            public void onBroadcast(AtmosphereResourceEvent event) {
                System.out.println("Broadcast received: " + event.getMessage());
            }
        });
        
        // Check transport type
        TRANSPORT transport = resource.transport();
        System.out.println("Using transport: " + transport);
    }
}

/**
 * Factory for creating AtmosphereResource instances
 */
public interface AtmosphereResourceFactory {
    /**
     * Create a new AtmosphereResource
     * @param config AtmosphereConfig
     * @param request HttpServletRequest
     * @param response HttpServletResponse
     * @return new AtmosphereResource instance
     */
    public AtmosphereResource create(AtmosphereConfig config, 
                                   HttpServletRequest request, 
                                   HttpServletResponse response);
    
    /**
     * Find an existing AtmosphereResource by UUID
     * @param uuid unique identifier
     * @return AtmosphereResource or null if not found
     */
    public AtmosphereResource find(String uuid);
}

/**
 * Enhanced HttpServletRequest with Atmosphere-specific features
 */
public interface AtmosphereRequest extends HttpServletRequest {
    /**
     * Get the request body as string
     * @return request body content
     */
    public String getBody();
    
    /**
     * Check if request has body content
     * @return true if body is present
     */
    public boolean hasBody();
    
    /**
     * Get local address for this request
     * @return local address string
     */
    public String getLocalAddr();
    
    /**
     * Get local name for this request
     * @return local name string
     */
    public String getLocalName();
    
    /**
     * Get local port for this request
     * @return local port number
     */
    public int getLocalPort();
}

/**
 * Enhanced HttpServletResponse with async writing capabilities
 */
public interface AtmosphereResponse extends HttpServletResponse {
    /**
     * Get async I/O writer for non-blocking writes
     * @return AsyncIOWriter instance
     */
    public AsyncIOWriter getAsyncIOWriter();
    
    /**
     * Close the response and connection
     */
    public void close();
    
    /**
     * Flush the response buffer
     * @throws IOException if flush fails
     */
    public void flushBuffer() throws IOException;
}

/**
 * Handle incoming AtmosphereResource requests and broadcast events
 */
public interface AtmosphereHandler {
    /**
     * Handle incoming request for AtmosphereResource
     * @param resource AtmosphereResource to handle
     * @throws IOException if handling fails
     */
    public void onRequest(AtmosphereResource resource) throws IOException;
    
    /**
     * Handle broadcast events and state changes
     * @param event AtmosphereResourceEvent containing broadcast data
     * @throws IOException if handling fails
     */
    public void onStateChange(AtmosphereResourceEvent event) throws IOException;
    
    /**
     * Destroy handler and cleanup resources
     */
    public void destroy();
}

@AtmosphereHandlerService(path = "/chat")
public class ChatHandler implements AtmosphereHandler {
    
    @Override
    public void onRequest(AtmosphereResource resource) throws IOException {
        // Suspend connection for real-time updates
        resource.suspend();
        
        // Send welcome message
        resource.write("Welcome to chat!");
    }
    
    @Override
    public void onStateChange(AtmosphereResourceEvent event) throws IOException {
        // Handle broadcast messages
        if (event.getMessage() != null && !event.isCancelled()) {
            AtmosphereResource resource = event.getResource();
            resource.write(event.getMessage().toString());
        }
        
        // Handle disconnections
        if (event.isCancelled() || event.isResumedOnTimeout()) {
            System.out.println("Client disconnected");
        }
    }
    
    @Override
    public void destroy() {
        // Cleanup handler resources
        System.out.println("ChatHandler destroyed");
    }
}

/**
 * Simplified servlet-based API for Atmosphere functionality
 */
public class Meteor {
    /**
     * Build Meteor instance from HttpServletRequest
     * @param request HttpServletRequest
     * @return Meteor instance
     */
    public static Meteor build(HttpServletRequest request);
    
    /**
     * Build Meteor with custom configuration
     * @param request HttpServletRequest
     * @param broadcaster Broadcaster to use
     * @param handler AtmosphereHandler for processing
     * @return Meteor instance
     */
    public static Meteor build(HttpServletRequest request, Broadcaster broadcaster, 
                              AtmosphereHandler handler);
    
    /**
     * Suspend the connection
     * @param timeout timeout in milliseconds (-1 for indefinite)
     * @return Meteor instance for chaining
     */
    public Meteor suspend(long timeout);
    
    /**
     * Resume the connection
     * @return Meteor instance
     */
    public Meteor resume();
    
    /**
     * Add AtmosphereHandler for processing
     * @param handler AtmosphereHandler instance
     * @return Meteor instance
     */
    public Meteor addAtmosphereHandler(AtmosphereHandler handler);
    
    /**
     * Get the associated AtmosphereResource
     * @return AtmosphereResource instance
     */
    public AtmosphereResource getAtmosphereResource();
    
    /**
     * Get the Broadcaster for this Meteor
     * @return Broadcaster instance
     */
    public Broadcaster getBroadcaster();
}

// In a servlet
public class ChatServlet extends HttpServlet {
    
    @Override
    protected void doGet(HttpServletRequest request, HttpServletResponse response) 
            throws ServletException, IOException {
        
        // Create Meteor and suspend connection
        Meteor meteor = Meteor.build(request)
                             .addAtmosphereHandler(new ChatHandler())
                             .suspend(-1); // Suspend indefinitely
        
        // Get broadcaster for messaging
        Broadcaster broadcaster = meteor.getBroadcaster();
        broadcaster.broadcast("User joined chat");
    }
    
    @Override
    protected void doPost(HttpServletRequest request, HttpServletResponse response) 
            throws ServletException, IOException {
        
        // Handle chat message
        String message = request.getParameter("message");
        
        Meteor meteor = Meteor.build(request);
        meteor.getBroadcaster().broadcast(message);
    }
}

/**
 * Event object containing state change information
 */
public interface AtmosphereResourceEvent {
    /**
     * Get the broadcast message
     * @return message object
     */
    public Object getMessage();
    
    /**
     * Get the associated AtmosphereResource
     * @return AtmosphereResource instance
     */
    public AtmosphereResource getResource();
    
    /**
     * Check if this is a resuming event
     * @return true if resuming
     */
    public boolean isResuming();
    
    /**
     * Check if this is a cancelled event
     * @return true if cancelled
     */
    public boolean isCancelled();
    
    /**
     * Check if resumed on timeout
     * @return true if resumed due to timeout
     */
    public boolean isResumedOnTimeout();
    
    /**
     * Get any exception that occurred
     * @return Throwable or null
     */
    public Throwable throwable();
}

/**
 * Listener for AtmosphereResource state changes
 */
public interface AtmosphereResourceEventListener {
    /**
     * Called when resource is suspended
     * @param event AtmosphereResourceEvent
     */
    public void onSuspend(AtmosphereResourceEvent event);
    
    /**
     * Called when resource is resumed
     * @param event AtmosphereResourceEvent
     */
    public void onResume(AtmosphereResourceEvent event);
    
    /**
     * Called when resource is disconnected
     * @param event AtmosphereResourceEvent
     */
    public void onDisconnect(AtmosphereResourceEvent event);
    
    /**
     * Called when broadcast occurs
     * @param event AtmosphereResourceEvent
     */
    public void onBroadcast(AtmosphereResourceEvent event);
    
    /**
     * Called when exception occurs
     * @param event AtmosphereResourceEvent
     */
    public void onThrowable(AtmosphereResourceEvent event);
    
    /**
     * Called when connection is closed
     * @param event AtmosphereResourceEvent
     */
    public void onClose(AtmosphereResourceEvent event);
    
    /**
     * Called on heartbeat events  
     * @param event AtmosphereResourceEvent
     */
    public void onHeartbeat(AtmosphereResourceEvent event);
}

/**
 * Factory for creating injectable objects
 */
public interface InjectableObjectFactory {
    /**
     * Create instance of specified class with dependency injection
     * @param clazz class to instantiate
     * @param config AtmosphereConfig for context
     * @return injected instance
     */
    public <T> T newClassInstance(Class<T> clazz, AtmosphereConfig config);
    
    /**
     * Configure the factory
     * @param config AtmosphereConfig instance
     */
    public void configure(AtmosphereConfig config);
}

/**
 * Base interface for injectable components
 */
public interface Injectable {
    /**
     * Set AtmosphereConfig for the injectable component
     * @param config AtmosphereConfig instance
     */
    public void configure(AtmosphereConfig config);
}

/**
 * Mark field or parameter for application-scoped injection
 */
@Target({ElementType.FIELD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
public @interface ApplicationScoped {
}

/**
 * Mark field or parameter for request-scoped injection
 */
@Target({ElementType.FIELD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
public @interface RequestScoped {
}

// Core injectable types:
AtmosphereConfig
AtmosphereFramework
BroadcasterFactory
AtmosphereResource
AtmosphereResourceFactory
MetaBroadcaster
WebSocketFactory

@ManagedService(path = "/api/chat")
public class ChatService {
    
    @ApplicationScoped
    private BroadcasterFactory broadcasterFactory;
    
    @ApplicationScoped
    private AtmosphereConfig config;
    
    @RequestScoped
    private AtmosphereResource resource;
    
    @Get
    public void onConnect() {
        // Use injected broadcaster factory
        Broadcaster broadcaster = broadcasterFactory.lookup("/chat", true);
        
        // Configure resource with injected config
        String timeout = config.getInitParameter("chat.timeout");
        if (timeout != null) {
            resource.suspend(Long.parseLong(timeout));
        } else {
            resource.suspend();
        }
    }
}

// Custom injectable component
@Injectable
public class UserService implements Injectable {
    private AtmosphereConfig config;
    
    @Override
    public void configure(AtmosphereConfig config) {
        this.config = config;
    }
    
    public User getUser(String userId) {
        // Custom user lookup logic
        return new User(userId);
    }
}

/**
 * Application-level configuration constants and parameters
 */
public class ApplicationConfig {
    // WebSocket configuration
    public static final String WEBSOCKET_SUPPORT = "org.atmosphere.websocket.WebSocketSupport";
    public static final String WEBSOCKET_PROTOCOL = "org.atmosphere.websocket.protocol";
    
    // Comet support
    public static final String NATIVE_COMETSUPPORT = "org.atmosphere.useNative";
    public static final String BLOCKING_COMETSUPPORT = "org.atmosphere.useBlocking";
    
    // Broadcasting configuration  
    public static final String BROADCASTER_FACTORY = "org.atmosphere.cpr.BroadcasterFactory";
    public static final String BROADCASTER_CACHE = "org.atmosphere.cpr.BroadcasterCache";
    public static final String BROADCASTER_LIFECYCLE_POLICY = "org.atmosphere.cpr.BroadcasterLifeCyclePolicy";
    
    // Serialization and encoding
    public static final String SERIALIZER = "org.atmosphere.cpr.Serializer";
    public static final String MESSAGE_DELIMITER = "org.atmosphere.cpr.messageDelimiter";
    
    // Performance and scaling
    public static final String SUSPENDED_RESOURCE_TIMEOUT = "org.atmosphere.cpr.suspendedResourceTimeout";
    public static final String BROADCASTER_MESSAGE_PROCESSING_THREADPOOL_MAXSIZE = 
        "org.atmosphere.cpr.BroadcasterMessageProcessingThreadPoolMaxSize";
    
    // Security
    public static final String ALLOW_QUERYSTRING_AS_REQUEST = "org.atmosphere.cpr.allowQueryStringAsRequest";
    public static final String EXCLUDED_CONTENT_TYPES = "org.atmosphere.cpr.excludedContentTypes";
}

/**
 * Framework-level configuration constants
 */
public class FrameworkConfig {
    // Internal framework constants
    public static final String ATMOSPHERE_RESOURCE = AtmosphereResource.class.getName();
    public static final String ATMOSPHERE_HANDLER = AtmosphereHandler.class.getName();
    public static final String BROADCASTER_FACTORY = BroadcasterFactory.class.getName();
    public static final String INJECTED_ATMOSPHERE_RESOURCE = "org.atmosphere.cpr.AtmosphereResource.injected";
    
    // Runtime configuration
    public static final String CONTAINER_AUTO_DETECTION = "org.atmosphere.container.autoDetection";
    public static final String WRITE_HEADERS = "org.atmosphere.cpr.writeHeaders";
    public static final String RESUME_AND_KEEPALIVE = "org.atmosphere.cpr.resumeAndKeepAlive";
}

// Configure Atmosphere in web.xml
<servlet>
    <servlet-name>AtmosphereServlet</servlet-name>
    <servlet-class>org.atmosphere.cpr.AtmosphereServlet</servlet-class>
    <init-param>
        <param-name>org.atmosphere.websocket.WebSocketSupport</param-name>
        <param-value>true</param-value>
    </init-param>
    <init-param>
        <param-name>org.atmosphere.cpr.BroadcasterCache</param-name>
        <param-value>org.atmosphere.cache.UUIDBroadcasterCache</param-value>
    </init-param>
    <init-param>
        <param-name>org.atmosphere.cpr.suspendedResourceTimeout</param-name>
        <param-value>300000</param-value>
    </init-param>
</servlet>

// Programmatic configuration
@ApplicationScoped
public class AtmosphereConfiguration {
    
    public void configureFramework(AtmosphereFramework framework) {
        AtmosphereConfig config = framework.getAtmosphereConfig();
        
        // Enable WebSocket support
        config.properties().put(ApplicationConfig.WEBSOCKET_SUPPORT, "true");
        
        // Set broadcaster cache
        config.properties().put(ApplicationConfig.BROADCASTER_CACHE, 
                               "org.atmosphere.cache.UUIDBroadcasterCache");
        
        // Configure timeouts
        config.properties().put(ApplicationConfig.SUSPENDED_RESOURCE_TIMEOUT, "300000");
        
        // Set message processing thread pool
        config.properties().put(ApplicationConfig.BROADCASTER_MESSAGE_PROCESSING_THREADPOOL_MAXSIZE, "10");
    }
}

/**
 * Available transport mechanisms
 */
public enum TRANSPORT {
    POLLING,        // Traditional polling
    LONG_POLLING,   // Long polling (Comet)
    STREAMING,      // HTTP streaming
    WEBSOCKET,      // WebSocket protocol
    JSONP,          // JSONP for cross-domain
    SSE,            // Server-Sent Events
    AJAX,           // AJAX requests
    HTMLFILE,       // HTML file transport
    CLOSE,          // Connection close
    UNDEFINED       // Unknown transport
}