tessl/maven-org-apache-tomcat-embed--tomcat-embed-core

Embedded Apache Tomcat servlet container with Jakarta Servlet API, HTTP connectors, and lifecycle management for Java web applications

Overview

Eval results

Files

Catalina Core Containers

Name: tessl/maven-org-apache-tomcat-embed--tomcat-embed-core
Author: tessl

The Catalina servlet engine provides the hierarchical container architecture that manages web applications and servlets. This includes Server, Service, Engine, Host, Context, and Wrapper containers with full lifecycle management, nested component relationships, and request processing through pipelines.

Capabilities

Container Hierarchy

The base container interface and hierarchy for all Tomcat components.

public interface Container extends Lifecycle {
    // Container identification
    String getName();
    void setName(String name);
    String getLogName();
    String getDomain();
    String getMBeanKeyProperties();
    ObjectName getObjectName();
    
    // Container hierarchy
    Container getParent();
    void setParent(Container container);
    void setParentClassLoader(ClassLoader parent);
    ClassLoader getParentClassLoader();
    void addChild(Container child);
    void removeChild(Container child);
    Container findChild(String name);
    Container[] findChildren();
    
    // Background processing
    int getBackgroundProcessorDelay();
    void setBackgroundProcessorDelay(int delay);
    void backgroundProcess();
    
    // Pipeline and valves
    Pipeline getPipeline();
    
    // Realm (authentication)
    Realm getRealm();
    void setRealm(Realm realm);
    
    // Clustering
    Cluster getCluster();
    void setCluster(Cluster cluster);
    
    // Event listeners
    void addContainerListener(ContainerListener listener);
    void removeContainerListener(ContainerListener listener);
    ContainerListener[] findContainerListeners();
    void fireContainerEvent(String type, Object data);
    
    // Property change support
    void addPropertyChangeListener(PropertyChangeListener listener);
    void removePropertyChangeListener(PropertyChangeListener listener);
    
    // Logging
    Log getLogger();

    // Access logging
    void logAccess(Request request, Response response, long time, boolean useDefault);
    AccessLog getAccessLog();
    
    // Child start/stop configuration
    int getStartStopThreads();
    void setStartStopThreads(int startStopThreads);
}

public interface Contained {
    Container getContainer();
    void setContainer(Container container);
}

Server

Top-level container representing the entire Tomcat instance.

public interface Server extends Lifecycle {
    // Global naming resources
    NamingResourcesImpl getGlobalNamingResources();
    void setGlobalNamingResources(NamingResourcesImpl globalNamingResources);
    javax.naming.Context getGlobalNamingContext();
    
    // Shutdown configuration
    int getPort();
    void setPort(int port);
    int getPortOffset();
    void setPortOffset(int portOffset);
    int getPortWithOffset();
    String getAddress();
    void setAddress(String address);
    String getShutdown();
    void setShutdown(String shutdown);
    
    // Catalina reference
    Catalina getCatalina();
    void setCatalina(Catalina catalina);
    
    // Directory configuration
    File getCatalinaBase();
    void setCatalinaBase(File catalinaBase);
    File getCatalinaHome();
    void setCatalinaHome(File catalinaHome);
    
    // Classloader
    ClassLoader getParentClassLoader();
    void setParentClassLoader(ClassLoader parent);
    
    // Thread configuration
    int getUtilityThreads();
    void setUtilityThreads(int utilityThreads);
    
    // Services
    void addService(Service service);
    void removeService(Service service);
    Service findService(String name);
    Service[] findServices();
    
    // Server lifecycle
    void await();
    
    // JNDI token
    Object getNamingToken();
    
    // Utility executor
    ScheduledExecutorService getUtilityExecutor();
}

Service

Groups Connectors with an Engine, managing protocol handlers and the servlet engine.

public interface Service extends Lifecycle {
    // Engine (container)
    Engine getContainer();
    void setContainer(Engine engine);
    
    // Service identification
    String getName();
    void setName(String name);
    
    // Server reference
    Server getServer();
    void setServer(Server server);
    
    // Classloader
    ClassLoader getParentClassLoader();
    void setParentClassLoader(ClassLoader parent);
    
    // Domain (JMX)
    String getDomain();
    
    // Connectors
    void addConnector(Connector connector);
    Connector[] findConnectors();
    void removeConnector(Connector connector);
    
    // Executors (thread pools)
    void addExecutor(Executor ex);
    Executor[] findExecutors();
    Executor getExecutor(String name);
    void removeExecutor(Executor ex);
    
    // Mapper
    Mapper getMapper();
}

Engine

Container managing virtual hosts and routing requests.

public interface Engine extends Container {
    // Default host
    String getDefaultHost();
    void setDefaultHost(String defaultHost);
    
    // JVM route (for load balancing)
    String getJvmRoute();
    void setJvmRoute(String jvmRouteId);
    
    // Service reference
    Service getService();
    void setService(Service service);
}

Host

Virtual host container managing web application contexts.

public interface Host extends Container {
    // XML configuration base
    String getXmlBase();
    void setXmlBase(String xmlBase);
    File getConfigBaseFile();
    
    // Application base directory
    String getAppBase();
    void setAppBase(String appBase);
    File getAppBaseFile();
    String getLegacyAppBase();
    void setLegacyAppBase(String legacyAppBase);
    
    // Deployment configuration
    boolean getAutoDeploy();
    void setAutoDeploy(boolean autoDeploy);
    String getConfigClass();
    void setConfigClass(String configClass);
    boolean getDeployOnStartup();
    void setDeployOnStartup(boolean deployOnStartup);
    String getDeployIgnore();
    void setDeployIgnore(String deployIgnore);
    Pattern getDeployIgnorePattern();
    boolean getCreateDirs();
    void setCreateDirs(boolean createDirs);
    boolean getUndeployOldVersions();
    void setUndeployOldVersions(boolean undeployOldVersions);
    
    // Host aliases
    void addAlias(String alias);
    String[] findAliases();
    void removeAlias(String alias);
}

Context (detailed in embedded-tomcat.md)

Represents a web application with servlets, filters, and resources.

// See embedded-tomcat.md for complete Context interface documentation
public interface Context extends Container {
    // Basic configuration
    void setPath(String path);
    String getPath();
    void setDocBase(String docBase);
    String getDocBase();
    
    // Servlet management
    void addServletMappingDecoded(String pattern, String name, boolean jspWildCard);
    
    // Lifecycle
    void reload();
    void backgroundProcess();
}

Wrapper (detailed in embedded-tomcat.md)

Represents an individual servlet.

// See embedded-tomcat.md for complete Wrapper interface documentation
public interface Wrapper extends Container {
    void setServletClass(String servletClass);
    String getServletClass();
    void setLoadOnStartup(int value);
    int getLoadOnStartup();
}

Lifecycle Management

Standard lifecycle interface for all Tomcat components.

public interface Lifecycle {
    // Event type constants
    String BEFORE_INIT_EVENT = "before_init";
    String AFTER_INIT_EVENT = "after_init";
    String START_EVENT = "start";
    String BEFORE_START_EVENT = "before_start";
    String AFTER_START_EVENT = "after_start";
    String STOP_EVENT = "stop";
    String BEFORE_STOP_EVENT = "before_stop";
    String AFTER_STOP_EVENT = "after_stop";
    String AFTER_DESTROY_EVENT = "after_destroy";
    String BEFORE_DESTROY_EVENT = "before_destroy";
    String PERIODIC_EVENT = "periodic";
    String CONFIGURE_START_EVENT = "configure_start";
    String CONFIGURE_STOP_EVENT = "configure_stop";
    
    // Lifecycle methods
    void addLifecycleListener(LifecycleListener listener);
    LifecycleListener[] findLifecycleListeners();
    void removeLifecycleListener(LifecycleListener listener);
    void init() throws LifecycleException;
    void start() throws LifecycleException;
    void stop() throws LifecycleException;
    void destroy() throws LifecycleException;
    
    // State management
    LifecycleState getState();
    String getStateName();
}

public interface LifecycleListener {
    void lifecycleEvent(LifecycleEvent event);
}

public class LifecycleEvent extends EventObject {
    public LifecycleEvent(Lifecycle lifecycle, String type, Object data);

    public Object getData();
    public Lifecycle getLifecycle();
    public String getType();
}

public enum LifecycleState {
    NEW(false, null),
    INITIALIZING(false, Lifecycle.BEFORE_INIT_EVENT),
    INITIALIZED(false, Lifecycle.AFTER_INIT_EVENT),
    STARTING_PREP(false, Lifecycle.BEFORE_START_EVENT),
    STARTING(true, Lifecycle.START_EVENT),
    STARTED(true, Lifecycle.AFTER_START_EVENT),
    STOPPING_PREP(true, Lifecycle.BEFORE_STOP_EVENT),
    STOPPING(false, Lifecycle.STOP_EVENT),
    STOPPED(false, Lifecycle.AFTER_STOP_EVENT),
    DESTROYING(false, Lifecycle.BEFORE_DESTROY_EVENT),
    DESTROYED(false, Lifecycle.AFTER_DESTROY_EVENT),
    FAILED(false, null);
    
    public boolean isAvailable();
    public String getLifecycleEvent();
}

public final class LifecycleException extends Exception {
    public LifecycleException();
    public LifecycleException(String message);
    public LifecycleException(Throwable throwable);
    public LifecycleException(String message, Throwable throwable);
}

Pipeline and Valve

Request processing pipeline for each container.

public interface Pipeline extends Contained {
    // Basic valve
    Valve getBasic();
    void setBasic(Valve valve);
    
    // Valve chain
    void addValve(Valve valve);
    Valve[] getValves();
    void removeValve(Valve valve);
    Valve getFirst();
    
    // Async support
    boolean isAsyncSupported();
    void findNonAsyncValves(Set<String> result);
}

public interface Valve {
    // Next valve in chain
    Valve getNext();
    void setNext(Valve valve);
    
    // Processing
    void invoke(Request request, Response response) throws IOException, ServletException;
    boolean isAsyncSupported();
    
    // Background processing
    void backgroundProcess();
}

Request and Response (Catalina Internal)

Internal Catalina request and response objects wrapping Coyote objects.

// Catalina Request (wraps Coyote Request)
public class Request implements HttpServletRequest {
    public Request(Connector connector);
    
    // Coyote request
    public void setCoyoteRequest(org.apache.coyote.Request coyoteRequest);
    public org.apache.coyote.Request getCoyoteRequest();
    
    // Components
    public Connector getConnector();
    public Context getContext();
    public void setContext(Context context);
    public Host getHost();
    public Wrapper getWrapper();
    public void setWrapper(Wrapper wrapper);
    public Response getResponse();
    public void setResponse(Response response);
    
    // Facade
    public HttpServletRequest getRequest();
    public void setRequest(HttpServletRequest applicationRequest);
    
    // Filter chain
    public FilterChain getFilterChain();
    public void setFilterChain(FilterChain filterChain);
    
    // Lifecycle
    public void recycle();
    public void finishRequest() throws IOException;
    
    // Async support
    public boolean isAsync();
    public void setAsyncSupported(boolean asyncSupported);
    
    // Notes (internal attributes)
    public Object getNote(String name);
    public void setNote(String name, Object value);
    public void removeNote(String name);
    
    // Mapping data
    public MappingData getMappingData();
    
    // Discard facades
    public boolean getDiscardFacades();
}

// Catalina Response (wraps Coyote Response)
public class Response implements HttpServletResponse {
    public Response();
    public Response(int outputBufferSize);
    
    // Coyote response
    public void setCoyoteResponse(org.apache.coyote.Response coyoteResponse);
    public org.apache.coyote.Response getCoyoteResponse();
    
    // Context
    public Context getContext();
    public void setContext(Context context);
    
    // Request
    public Request getRequest();
    public void setRequest(Request request);
    
    // Facade
    public HttpServletResponse getResponse();
    public void setResponse(HttpServletResponse applicationResponse);
    
    // Lifecycle
    public void recycle();
    public void finishResponse() throws IOException;
    
    // Status
    public boolean isCommitted();
    public boolean isError();
    public boolean setError();
    public boolean isErrorReportRequired();
    public boolean setErrorReported();
    public void resetError();
    
    // Suspension
    public void setSuspended(boolean suspended);
    public boolean isSuspended();
    public boolean isClosed();
    
    // Application commit
    public void setAppCommitted(boolean appCommitted);
    public boolean isAppCommitted();
    
    // Content
    public List<Cookie> getCookies();
    public long getContentWritten();
    public long getBytesWritten(boolean flush);
}

Usage Examples

Lifecycle Listener

import org.apache.catalina.Lifecycle;
import org.apache.catalina.LifecycleEvent;
import org.apache.catalina.LifecycleListener;

public class CustomLifecycleListener implements LifecycleListener {
    @Override
    public void lifecycleEvent(LifecycleEvent event) {
        if (Lifecycle.BEFORE_START_EVENT.equals(event.getType())) {
            System.out.println("Container starting: " + event.getLifecycle());
        } else if (Lifecycle.AFTER_START_EVENT.equals(event.getType())) {
            System.out.println("Container started: " + event.getLifecycle());
        } else if (Lifecycle.BEFORE_STOP_EVENT.equals(event.getType())) {
            System.out.println("Container stopping: " + event.getLifecycle());
        } else if (Lifecycle.AFTER_STOP_EVENT.equals(event.getType())) {
            System.out.println("Container stopped: " + event.getLifecycle());
        }
    }
}

Container Listener

import org.apache.catalina.Container;
import org.apache.catalina.ContainerEvent;
import org.apache.catalina.ContainerListener;

public class CustomContainerListener implements ContainerListener {
    @Override
    public void containerEvent(ContainerEvent event) {
        Container container = event.getContainer();
        String type = event.getType();
        Object data = event.getData();
        
        if ("addChild".equals(type)) {
            System.out.println("Child added to " + container.getName() + ": " + data);
        } else if ("removeChild".equals(type)) {
            System.out.println("Child removed from " + container.getName() + ": " + data);
        }
    }
}

Accessing Container Hierarchy

import org.apache.catalina.startup.Tomcat;
import org.apache.catalina.*;

public class ContainerHierarchyExample {
    public static void main(String[] args) throws Exception {
        Tomcat tomcat = new Tomcat();
        tomcat.setPort(8080);
        
        // Access hierarchy
        Server server = tomcat.getServer();
        Service service = tomcat.getService();
        Engine engine = tomcat.getEngine();
        Host host = tomcat.getHost();
        
        Context ctx = tomcat.addContext("/myapp", "/path/to/webapp");
        
        // Navigate hierarchy
        System.out.println("Context parent: " + ctx.getParent().getName()); // Host
        System.out.println("Host parent: " + host.getParent().getName()); // Engine
        System.out.println("Engine service: " + engine.getService().getName());
        
        // Enumerate children
        Container[] hosts = engine.findChildren();
        for (Container h : hosts) {
            System.out.println("Host: " + h.getName());
            Container[] contexts = h.findChildren();
            for (Container c : contexts) {
                System.out.println("  Context: " + c.getName());
            }
        }
        
        tomcat.start();
    }
}

Install with Tessl CLI

npx tessl i tessl/maven-org-apache-tomcat-embed--tomcat-embed-core

docs

session-management.md