CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-io-quarkus--quarkus-undertow

Quarkus extension providing servlet support through Undertow web server for cloud-native Java applications

—

Pending
Overview
Eval results
Files

build-time-api.mddocs/

Build-time API

The build-time API provides extension points for registering servlets, filters, listeners, and other servlet components during application build. This API is primarily used by extension developers and advanced application developers who need to programmatically configure servlet components.

Core Imports

import io.quarkus.undertow.spi.ServletBuildItem;
import io.quarkus.undertow.spi.FilterBuildItem;
import io.quarkus.undertow.spi.ListenerBuildItem;
import io.quarkus.undertow.spi.ServletExtensionBuildItem;
import io.quarkus.undertow.spi.UndertowBuildItem;
import io.quarkus.deployment.annotations.BuildStep;
import io.quarkus.deployment.builditem.MultiBuildItem;

Build Items

ServletBuildItem

Build item for registering servlets during application build.

public class ServletBuildItem extends MultiBuildItem {
    /**
     * Create a builder for ServletBuildItem
     */
    public static Builder builder(String name, String servletClass);
    
    /**
     * Get servlet name
     */
    public String getName();
    
    /**
     * Get servlet class name
     */
    public String getServletClass();
    
    /**
     * Get URL mappings
     */
    public List<String> getMappings();
    
    /**
     * Get load on startup value
     */
    public int getLoadOnStartup();
    
    /**
     * Check if async is supported
     */
    public boolean isAsyncSupported();
    
    /**
     * Get initialization parameters
     */
    public Map<String, String> getInitParams();
    
    /**
     * Get instance factory for servlet creation
     */
    public InstanceFactory<? extends Servlet> getInstanceFactory();
    
    /**
     * Get multipart configuration
     */
    public MultipartConfigElement getMultipartConfig();
}

ServletBuildItem.Builder

Builder class for creating ServletBuildItem instances.

public static class Builder {
    /**
     * Set load on startup order
     */
    public Builder setLoadOnStartup(int loadOnStartup);
    
    /**
     * Enable or disable async support
     */
    public Builder setAsyncSupported(boolean asyncSupported);
    
    /**
     * Set URL mappings
     */
    public Builder setMappings(List<String> mappings);
    
    /**
     * Add single URL mapping
     */
    public Builder addMapping(String mapping);
    
    /**
     * Add initialization parameter
     */
    public Builder addInitParam(String name, String value);
    
    /**
     * Set instance factory for servlet creation
     */
    public Builder setInstanceFactory(InstanceFactory<? extends Servlet> instanceFactory);
    
    /**
     * Set multipart configuration
     */
    public Builder setMultipartConfig(MultipartConfigElement multipartConfig);
    
    /**
     * Build the ServletBuildItem
     */
    public ServletBuildItem build();
}

Usage Example

@BuildStep
ServletBuildItem createApiServlet() {
    return ServletBuildItem.builder("api-servlet", ApiServlet.class.getName())
            .addMapping("/api/*")
            .setAsyncSupported(true)
            .setLoadOnStartup(1)
            .addInitParam("debug", "true")
            .build();
}

FilterBuildItem

Build item for registering filters during application build.

public class FilterBuildItem extends MultiBuildItem {
    /**
     * Create a builder for FilterBuildItem
     */
    public static Builder builder(String name, String filterClass);
    
    /**
     * Get filter name
     */
    public String getName();
    
    /**
     * Get filter class name
     */
    public String getFilterClass();
    
    /**
     * Get filter mappings
     */
    public List<FilterMappingInfo> getMappings();
    
    /**
     * Get load on startup value
     */
    public int getLoadOnStartup();
    
    /**
     * Check if async is supported
     */
    public boolean isAsyncSupported();
    
    /**
     * Get initialization parameters
     */
    public Map<String, String> getInitParams();
    
    /**
     * Get instance factory for filter creation
     */
    public InstanceFactory<? extends Filter> getInstanceFactory();
}

FilterBuildItem.FilterMappingInfo

Information about filter mappings.

public static class FilterMappingInfo {
    /**
     * Constructor for filter mapping
     */
    public FilterMappingInfo(MappingType mappingType, String mapping, DispatcherType dispatcher);
    
    /**
     * Get mapping type (URL or SERVLET)
     */
    public MappingType getMappingType();
    
    /**
     * Get mapping value
     */
    public String getMapping();
    
    /**
     * Get dispatcher type
     */
    public DispatcherType getDispatcher();
    
    /**
     * Set mapping type
     */
    public void setMappingType(MappingType mappingType);
    
    /**
     * Set mapping value
     */
    public void setMapping(String mapping);
    
    /**
     * Set dispatcher type
     */
    public void setDispatcher(DispatcherType dispatcher);
}

FilterBuildItem.FilterMappingInfo.MappingType

Enumeration of filter mapping types.

public enum MappingType {
    /**
     * URL pattern mapping
     */
    URL,
    
    /**
     * Servlet name mapping
     */
    SERVLET
}

FilterBuildItem.Builder

Builder class for creating FilterBuildItem instances.

public static class Builder {
    /**
     * Set load on startup order
     */
    public Builder setLoadOnStartup(int loadOnStartup);
    
    /**
     * Enable or disable async support
     */
    public Builder setAsyncSupported(boolean asyncSupported);
    
    /**
     * Set instance factory for filter creation
     */
    public Builder setInstanceFactory(InstanceFactory<? extends Filter> instanceFactory);
    
    /**
     * Add filter mapping
     */
    public Builder addMapping(FilterMappingInfo mapping);
    
    /**
     * Add URL pattern mapping
     */
    public Builder addFilterUrlMapping(String urlPattern, DispatcherType dispatcher);
    
    /**
     * Add servlet name mapping
     */
    public Builder addFilterServletNameMapping(String servletName, DispatcherType dispatcher);
    
    /**
     * Insert URL mapping at specific position
     */
    public Builder insertFilterUrlMapping(int index, String urlPattern, DispatcherType dispatcher);
    
    /**
     * Insert servlet name mapping at specific position
     */
    public Builder insertFilterServletNameMapping(int pos, String filterName, String mapping, 
                                                DispatcherType dispatcher);
    
    /**
     * Add initialization parameter
     */
    public Builder addInitParam(String name, String value);
    
    /**
     * Build the FilterBuildItem
     */
    public FilterBuildItem build();
}

Usage Example

@BuildStep
FilterBuildItem createSecurityFilter() {
    return FilterBuildItem.builder("security-filter", SecurityFilter.class.getName())
            .addFilterUrlMapping("/*", DispatcherType.REQUEST)
            .setAsyncSupported(true)
            .addInitParam("enabled", "true")
            .build();
}

ListenerBuildItem

Build item for registering servlet listeners during application build.

public class ListenerBuildItem extends MultiBuildItem {
    /**
     * Constructor for listener build item
     */
    public ListenerBuildItem(String listenerClass);
    
    /**
     * Get listener class name
     */
    public String getListenerClass();
}

Usage Example

@BuildStep
ListenerBuildItem createSessionListener() {
    return new ListenerBuildItem(MySessionListener.class.getName());
}

ServletExtensionBuildItem

Build item for registering servlet extensions.

public class ServletExtensionBuildItem extends MultiBuildItem {
    /**
     * Constructor for servlet extension build item
     */
    public ServletExtensionBuildItem(ServletExtension extension);
    
    /**
     * Get servlet extension instance
     */
    public ServletExtension getValue();
}

ServletContainerInitializerBuildItem

Build item for registering servlet container initializers.

public class ServletContainerInitializerBuildItem extends MultiBuildItem {
    /**
     * Constructor for servlet container initializer
     */
    public ServletContainerInitializerBuildItem(String sciClass, Set<String> handlesTypes);
    
    /**
     * Get servlet container initializer class name
     */
    public String getSciClass();
    
    /**
     * Get handled types
     */
    public Set<String> getHandlesTypes();
}

UndertowBuildItem

Build item providing access to the Undertow server instance.

public class UndertowBuildItem extends SimpleBuildItem {
    /**
     * Constructor for Undertow build item
     */
    public UndertowBuildItem(RuntimeValue<Undertow> undertow);
    
    /**
     * Get Undertow server instance
     */
    public RuntimeValue<Undertow> getUndertow();
}

ServletContextPathBuildItem

Build item for servlet context path configuration.

public class ServletContextPathBuildItem extends SimpleBuildItem {
    /**
     * Constructor for servlet context path
     */
    public ServletContextPathBuildItem(String contextPath);
    
    /**
     * Get context path
     */
    public String getContextPath();
}

Additional Build Items

HttpHandlerWrapperBuildItem

Build item for registering HTTP handler wrappers.

public class HttpHandlerWrapperBuildItem extends MultiBuildItem {
    /**
     * Constructor for HTTP handler wrapper
     */
    public HttpHandlerWrapperBuildItem(HandlerWrapper value);
    
    /**
     * Get handler wrapper
     */
    public HandlerWrapper getValue();
}

ServletContextAttributeBuildItem

Build item for setting servlet context attributes.

public class ServletContextAttributeBuildItem extends MultiBuildItem {
    /**
     * Constructor for servlet context attribute
     */
    public ServletContextAttributeBuildItem(String key, Object value);
    
    /**
     * Get attribute key
     */
    public String getKey();
    
    /**
     * Get attribute value
     */
    public Object getValue();
}

ServletDeploymentManagerBuildItem

Build item providing access to the deployment manager.

public class ServletDeploymentManagerBuildItem extends SimpleBuildItem {
    /**
     * Constructor for servlet deployment manager
     */
    public ServletDeploymentManagerBuildItem(DeploymentManager deploymentManager);
    
    /**
     * Get deployment manager
     */
    public DeploymentManager getDeploymentManager();
}

ServletInitParamBuildItem

Build item for setting servlet initialization parameters.

public class ServletInitParamBuildItem extends MultiBuildItem {
    /**
     * Constructor for servlet init parameter
     */
    public ServletInitParamBuildItem(String key, String value);
    
    /**
     * Get parameter key
     */
    public String getKey();
    
    /**
     * Get parameter value
     */
    public String getValue();
}

IgnoredServletContainerInitializerBuildItem

Build item for ignoring specific servlet container initializers during scanning.

public class IgnoredServletContainerInitializerBuildItem extends MultiBuildItem {
    /**
     * Constructor for ignored servlet container initializer
     */
    public IgnoredServletContainerInitializerBuildItem(String sciClass);
    
    /**
     * Get servlet container initializer class name
     */
    public String getSciClass();
}

WebMetadataBuildItem

Build item providing access to web application metadata.

public class WebMetadataBuildItem extends SimpleBuildItem {
    /**
     * Constructor for web metadata build item
     */
    public WebMetadataBuildItem(WebMetaData webMetaData);
    
    /**
     * Get web metadata
     */
    public WebMetaData getWebMetaData();
}

GeneratedWebResourceBuildItem

Build item for generated static resources that will be served by the web container.

public class GeneratedWebResourceBuildItem extends MultiBuildItem {
    /**
     * Constructor for generated web resource
     */
    public GeneratedWebResourceBuildItem(String name, byte[] classData);
    
    /**
     * Get resource name
     */
    public String getName();
    
    /**
     * Get resource data
     */
    public byte[] getClassData();
}

KnownPathsBuildItem

Build item containing known paths for static resource optimization.

public class KnownPathsBuildItem extends SimpleBuildItem {
    /**
     * Constructor for known paths build item (package-private)
     */
    KnownPathsBuildItem(Set<String> knownFiles, Set<String> knownDirectories);
    
    /**
     * Set of known file paths
     */
    public final Set<String> knownFiles;
    
    /**
     * Set of known directory paths
     */
    public final Set<String> knownDirectories;
}

Extension Development Example

Complete example of a Quarkus extension that registers servlet components:

@BuildStep
void registerServletComponents(BuildProducer<ServletBuildItem> servlets,
                              BuildProducer<FilterBuildItem> filters,
                              BuildProducer<ListenerBuildItem> listeners) {
    
    // Register a servlet
    servlets.produce(ServletBuildItem.builder("api", "com.example.ApiServlet")
            .addMapping("/api/*")
            .setAsyncSupported(true)
            .build());
    
    // Register a filter
    filters.produce(FilterBuildItem.builder("cors", "com.example.CorsFilter")
            .addFilterUrlMapping("/*", DispatcherType.REQUEST)
            .build());
    
    // Register a listener
    listeners.produce(new ListenerBuildItem("com.example.AppContextListener"));
}

Types

// Core servlet types
import jakarta.servlet.Servlet;
import jakarta.servlet.Filter;
import jakarta.servlet.ServletExtension;
import jakarta.servlet.DispatcherType;
import jakarta.servlet.MultipartConfigElement;

// Quarkus build-time types
import io.quarkus.deployment.builditem.SimpleBuildItem;
import io.quarkus.deployment.builditem.MultiBuildItem;
import io.quarkus.deployment.BuildProducer;
import io.quarkus.runtime.RuntimeValue;

// Undertow types
import io.undertow.Undertow;
import io.undertow.servlet.api.InstanceFactory;
import io.undertow.servlet.api.DeploymentManager;
import io.undertow.server.HandlerWrapper;

// Web metadata types
import org.jboss.metadata.web.spec.WebMetaData;

// Standard Java types
import java.util.List;
import java.util.Map;
import java.util.Set;

Install with Tessl CLI

npx tessl i tessl/maven-io-quarkus--quarkus-undertow

docs

build-time-api.md

configuration.md

index.md

runtime-api.md

tile.json