Service Provider Interface (SPI)

/**
 * Jersey container interface providing lifecycle management and configuration access.
 */
public interface Container {
    
    /**
     * Reload the container with current configuration.
     */
    void reload();
    
    /**
     * Reload the container with new configuration.
     * @param configuration New ResourceConfig to apply
     */
    void reload(ResourceConfig configuration);
    
    /**
     * Get the application handler for request processing.
     * @return ApplicationHandler instance
     */
    ApplicationHandler getApplicationHandler();
    
    /**
     * Get the current container configuration.
     * @return ResourceConfig for this container
     */
    ResourceConfig getConfiguration();
}

/**
 * Container provider SPI for creating container instances.
 */
public interface ContainerProvider {
    
    /**
     * Create a container instance of specified type.
     * @param type Container type to create
     * @param application JAX-RS application
     * @return Container instance of requested type or null if not supported
     */
    <T> T createContainer(Class<T> type, Application application);
}

/**
 * Container lifecycle listener for monitoring container events.
 */
public interface ContainerLifecycleListener {
    
    /**
     * Called when container is started.
     * @param container Container that was started
     */
    void onStartup(Container container);
    
    /**
     * Called when container is reloaded.
     * @param container Container that was reloaded
     */
    void onReload(Container container);
    
    /**
     * Called when container is shut down.
     * @param container Container that was shut down
     */
    void onShutdown(Container container);
}

/**
 * Container response writer for writing HTTP responses.
 */
public interface ContainerResponseWriter {
    
    /**
     * Write response headers and status.
     * @param contentLength Content length or -1 if unknown
     * @param containerResponse Response to write
     * @return OutputStream for writing response entity
     */
    OutputStream writeResponseStatusAndHeaders(long contentLength, ContainerResponse containerResponse);
    
    /**
     * Suspend the response writer for asynchronous processing.
     * @param timeOut Timeout value
     * @param timeUnit Time unit for timeout
     * @param timeoutHandler Handler called on timeout
     * @return true if successfully suspended
     */
    boolean suspend(long timeOut, TimeUnit timeUnit, TimeoutHandler timeoutHandler);
    
    /**
     * Set suspend timeout handler.
     * @param timeoutHandler Handler for timeout events
     */
    void setSuspendTimeout(long time, TimeUnit timeUnit);
    
    /**
     * Commit the response (make it immutable).
     */
    void commit();
    
    /**
     * Enable response buffering if supported.
     * @return true if buffering was enabled
     */
    boolean enableResponseBuffering();
    
    /**
     * Failure callback called when response writing fails.
     * @param error Error that occurred
     */
    void failure(Throwable error);
}

import org.glassfish.jersey.server.spi.*;
import org.glassfish.jersey.server.ApplicationHandler;
import org.glassfish.jersey.server.ResourceConfig;

// Custom container implementation
public class CustomContainer implements Container {
    
    private ApplicationHandler applicationHandler;
    private ResourceConfig configuration;
    private final List<ContainerLifecycleListener> listeners = new ArrayList<>();
    
    public CustomContainer(ResourceConfig config) {
        this.configuration = config;
        this.applicationHandler = new ApplicationHandler(config);
        
        // Notify startup
        for (ContainerLifecycleListener listener : listeners) {
            listener.onStartup(this);
        }
    }
    
    @Override
    public void reload() {
        reload(this.configuration);
    }
    
    @Override
    public void reload(ResourceConfig configuration) {
        this.configuration = configuration;
        this.applicationHandler = new ApplicationHandler(configuration);
        
        // Notify reload
        for (ContainerLifecycleListener listener : listeners) {
            listener.onReload(this);
        }
    }
    
    @Override
    public ApplicationHandler getApplicationHandler() {
        return applicationHandler;
    }
    
    @Override
    public ResourceConfig getConfiguration() {
        return configuration;
    }
    
    public void addLifecycleListener(ContainerLifecycleListener listener) {
        listeners.add(listener);
    }
    
    public void shutdown() {
        for (ContainerLifecycleListener listener : listeners) {
            listener.onShutdown(this);
        }
    }
}

// Custom container provider
public class CustomContainerProvider implements ContainerProvider {
    
    @Override
    public <T> T createContainer(Class<T> type, Application application) {
        if (type == CustomContainer.class) {
            ResourceConfig config = ResourceConfig.forApplication(application);
            return type.cast(new CustomContainer(config));
        }
        return null; // Type not supported
    }
}

/**
 * Server-side component provider extending the base ComponentProvider.
 * Enables custom dependency injection and component management.
 */
public interface ComponentProvider extends org.glassfish.jersey.spi.ComponentProvider {
    
    /**
     * Initialize the component provider with injection manager.
     * @param injectionManager Injection manager instance
     */
    void initialize(InjectionManager injectionManager);
    
    /**
     * Bind components and services.
     * @param injectionManager Injection manager for binding
     */
    void bind(InjectionManager injectionManager);
    
    /**
     * Called when component provider is being shut down.
     * @param injectionManager Injection manager instance
     */
    void done(InjectionManager injectionManager);
}

/**
 * External request scope interface for custom request scoping.
 * Extends AutoCloseable for proper resource management.
 */
public interface ExternalRequestScope<T> extends AutoCloseable {
    
    /**
     * Open a new request scope context.
     * @return ExternalRequestContext for the opened scope
     */
    ExternalRequestContext<T> open();
    
    /**
     * Close the request scope and clean up resources.
     */
    @Override
    void close();
}

/**
 * External request context representing an active request scope.
 */
public static class ExternalRequestContext<T> {
    
    /**
     * Create external request context.
     * @param scopeInstance Scope instance
     */
    public ExternalRequestContext(T scopeInstance);
    
    /**
     * Get the scope instance.
     * @return Scope instance
     */
    public T getInstance();
    
    /**
     * Release the context and associated resources.
     */
    public void release();
}

/**
 * Request scoped initializer for custom initialization logic.
 */
public interface RequestScopedInitializer {
    
    /**
     * Initialize request-scoped components.
     * @param injectionManager Injection manager instance
     */
    void initialize(InjectionManager injectionManager);
}

import org.glassfish.jersey.server.spi.ExternalRequestScope;
import org.glassfish.jersey.server.spi.ExternalRequestContext;
import org.glassfish.jersey.server.spi.RequestScopedInitializer;

// Custom external request scope implementation
public class CustomRequestScope implements ExternalRequestScope<CustomScopeData> {
    
    private final ThreadLocal<CustomScopeData> scopeData = new ThreadLocal<>();
    
    @Override
    public ExternalRequestContext<CustomScopeData> open() {
        CustomScopeData data = new CustomScopeData();
        scopeData.set(data);
        return new ExternalRequestContext<>(data);
    }
    
    @Override
    public void close() {
        scopeData.remove();
    }
    
    public CustomScopeData getCurrentScope() {
        return scopeData.get();
    }
}

// Custom request-scoped initializer
public class CustomRequestScopedInitializer implements RequestScopedInitializer {
    
    @Override
    public void initialize(InjectionManager injectionManager) {
        // Initialize request-scoped components
        injectionManager.register(new AbstractBinder() {
            @Override
            protected void configure() {
                bindFactory(CustomRequestScopedFactory.class)
                    .to(CustomService.class)
                    .in(RequestScoped.class);
            }
        });
    }
}

// Usage in resource
@Path("/scoped")
public class ScopedResource {
    
    @Inject
    private CustomRequestScope requestScope;
    
    @GET
    public String getScopedData() {
        try (ExternalRequestContext<CustomScopeData> context = requestScope.open()) {
            CustomScopeData data = context.getInstance();
            return "Scoped data: " + data.getValue();
        }
    }
}

/**
 * Validation interceptor SPI for custom validation logic.
 */
public interface ValidationInterceptor {
    
    /**
     * Called before validation occurs.
     * @param context Validation context
     */
    void onValidate(ValidationInterceptorContext context);
}

/**
 * Validation interceptor context providing access to validation information.
 */
public interface ValidationInterceptorContext {
    
    /**
     * Get the object being validated.
     * @return Object to validate
     */
    Object getValidatedObject();
    
    /**
     * Get the validation groups.
     * @return Array of validation groups
     */
    Class<?>[] getGroups();
    
    /**
     * Get the resource method being validated.
     * @return ResourceMethod instance
     */
    ResourceMethod getResourceMethod();
    
    /**
     * Get validation constraint violations.
     * @return Set of constraint violations
     */
    Set<ConstraintViolation<Object>> getConstraintViolations();
    
    /**
     * Set validation constraint violations.
     * @param violations Set of violations to set
     */
    void setConstraintViolations(Set<ConstraintViolation<Object>> violations);
}

/**
 * Response error mapper SPI for custom error handling.
 */
public interface ResponseErrorMapper {
    
    /**
     * Map an error to a response.
     * @param error Error to map
     * @param context Request context
     * @return Response for the error or null to use default handling
     */
    Response toResponse(Throwable error, ContainerRequest context);
    
    /**
     * Check if this mapper can handle the given error type.
     * @param errorType Error type to check
     * @return true if this mapper can handle the error type
     */
    boolean isMappable(Class<? extends Throwable> errorType);
}

/**
 * Web server interface for Jersey integration.
 */
public interface WebServer {
    
    /**
     * Start the web server.
     */
    void start();
    
    /**
     * Stop the web server.
     */
    void stop();
    
    /**
     * Get server port.
     * @return Server port number
     */
    int getPort();
    
    /**
     * Check if server is running.
     * @return true if server is running
     */
    boolean isRunning();
}

/**
 * Web server provider SPI for creating web server instances.
 */
public interface WebServerProvider {
    
    /**
     * Create a web server instance.
     * @param application JAX-RS application
     * @param configuration Server configuration
     * @return WebServer instance or null if not supported
     */
    WebServer createServer(Application application, Map<String, Object> configuration);
    
    /**
     * Get the server type name.
     * @return Server type identifier
     */
    String getServerType();
}

import org.glassfish.jersey.server.spi.WebServer;
import org.glassfish.jersey.server.spi.WebServerProvider;

// Custom web server implementation
public class CustomWebServer implements WebServer {
    
    private final Application application;
    private final int port;
    private boolean running = false;
    
    public CustomWebServer(Application application, int port) {
        this.application = application;
        this.port = port;
    }
    
    @Override
    public void start() {
        if (!running) {
            // Start server implementation
            startServerImplementation();
            running = true;
        }
    }
    
    @Override
    public void stop() {
        if (running) {
            // Stop server implementation
            stopServerImplementation();
            running = false;
        }
    }
    
    @Override
    public int getPort() {
        return port;
    }
    
    @Override
    public boolean isRunning() {
        return running;
    }
}

// Custom web server provider
public class CustomWebServerProvider implements WebServerProvider {
    
    @Override
    public WebServer createServer(Application application, Map<String, Object> configuration) {
        Integer port = (Integer) configuration.get("server.port");
        if (port == null) {
            port = 8080; // Default port
        }
        
        return new CustomWebServer(application, port);
    }
    
    @Override
    public String getServerType() {
        return "custom";
    }
}

// Usage
public class ServerLauncher {
    
    public static void main(String[] args) {
        ResourceConfig config = new ResourceConfig()
            .packages("com.example.resources");
            
        Map<String, Object> serverConfig = new HashMap<>();
        serverConfig.put("server.port", 9090);
        
        CustomWebServerProvider provider = new CustomWebServerProvider();
        WebServer server = provider.createServer(config, serverConfig);
        
        server.start();
        System.out.println("Server started on port " + server.getPort());
        
        // Shutdown hook
        Runtime.getRuntime().addShutdownHook(new Thread(server::stop));
    }
}