Weld SiteCommunity Documentation

Chapter 19. Configuration

19.1. Weld configuration
19.1.1. Relaxed construction
19.1.2. Concurrent deployment configuration
19.1.3. Thread pool configuration
19.1.4. Non-portable mode during application initialization
19.1.5. Proxying classes with final methods
19.1.6. Bounding the cache size for resolved injection points
19.1.7. Debugging generated bytecode
19.1.8. Injectable reference lookup optimization
19.1.9. Bean identifier index optimization
19.1.10. Rolling upgrades ID delimiter
19.1.11. Development Mode
19.1.12. Conversation timeout and Conversation concurrent access timeout
19.1.13. Veto types without bean defining annotation
19.2. Defining external configuration
19.3. Excluding classes from scanning and deployment
19.4. Mapping CDI contexts to HTTP requests

Weld can be configured per application through the set of properties. All the supported configuration properties are described in the following subsections.

Each configuration property can be specified (by priority in descending order):

If a configuration key is set in multiple sources (e.g. as a system property and in a properties file), the value from the source with higher priority is taken, other values are ignored. Unsupported configuration keys are ignored. If an invalid configuration property value is set, the container automatically detects the problem and treats it as a deployment problem.

For certain types of tasks Weld uses its own thread pool. The thread pool is represented by the ExecutorServices service.

First of all, let’s see what types of thread pools are available:

Thread pool typeDescription

FIXED

Uses a fixed number of threads. The number of threads remains the same throughout the application.

FIXED_TIMEOUT

Uses a fixed number of threads. A thread will be stopped after a configured period of inactivity.

SINGLE_THREAD

A single-threaded thread pool

NONE

No executor is used by Weld

COMMON

The default ForkJoinPool.commonPool() is used by Weld. See link for more details

Now let’s see how to configure Weld to use a particular thread pool type:


Note

It’s possible to alter the thread pool configuration using the deprecated org.jboss.weld.executor.properties file located on the classpath. The keys are threadPoolType, threadPoolSize, threadPoolKeepAliveTime and threadPoolDebug.

Some features of the development mode may have negative impact on the performance and/or functionality of the application. The following configuration properties allow to tune or disable these features, e.g. to specify the set of components which will be monitored.


Tip

To disable the monitoring entirely set org.jboss.weld.probe.invocationMonitor.excludeType and org.jboss.weld.probe.eventMonitor.excludeType properties to .*.

Sometimes it might be useful to process all types during bootstrap, i.e. fire/observe ProcessAnnotatedType event for each Java class discovered, but veto types which are not annotated with a bean defining annotation. The main reason is that not all classes that meet all of the necessary conditions are intended to become beans. And so vetoing such types helps to conserve memory used by the container. Note that if you use bean-discovey-mode=annotated (implicit bean archive) then no ProcessAnnotatedType will be fired for any such type because it’s not discovered at all. And there might be portable extensions which use ProcessAnnotatedType to extract some important information from classes which are not beans.

Therefore, Weld allows to use bean-discovey-mode=all (explicit bean archive) and veto types without a bean defining annotation whose AnnotatedType#getJavaClass().getName() matches a regular expression. In other words, a type is vetoed if its name matches a regular expression and at the same time is not annotated with a bean defining annotation. The functionality is implemented as a built-in portable extension processing all types from all bean archives.


Weld allows integrators to provide an external configuration - a class which implements org.jboss.weld.configuration.spi.ExternalConfiguration interface. This interface has getConfigurationProperties method which returns a Map with provided configuration and also inherits a cleanup method because it extends org.jboss.weld.bootstrap.api.Service. Below is a short example of ExternalConfiguration implementation:

public class MyExternalConfiguration implements ExternalConfiguration {

    @Override
    public void cleanup() {
    // cleanup code
    }
    @Override
    public Map<String, Object> getConfigurationProperties() {
        Map<String, Object> properties = new HashMap<String, Object>();
        properties.put(ConfigurationKey.CONCURRENT_DEPLOYMENT.get(), false);
        properties.put(ConfigurationKey.PRELOADER_THREAD_POOL_SIZE.get(), 200);
        properties.put(ConfigurationKey.PROXY_DUMP.get(), "/home/weld");
        return properties;
    }
}

Bear in mind that because ExternalConfiguration extends a Service it is required that any custom external configuration implementation is explicitly registered. See Section A.1, “The Weld SPI” for more information.

Last but not least external configuration is considered a source with the lowest priority which means that the properties specified there can be overriden by other sources such as system properties. For information on supported configuration keys, see Section 19.1, “Weld configuration”. Also note that entries with unsupported properties will be ignored while invalid property values will lead to deployment problem.

CDI 1.1 allows you to exclude classes in your archive from being scanned, having container lifecycle events fired, and being deployed as beans. See also 12.4.2 Exclude filters.

Note

Weld still supports the original non-portable way of excluding classes from discovery. The formal specification can be found in the xsd, located at http://jboss.org/schema/weld/beans_1_1.xsd. Unlike Weld, the CDI specification does not support regular expression patterns and ! character to invert the activation condition.

All the configuration is done in the beans.xml file. For more information see Section 15.6, “Packaging and deployment”.


<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://xmlns.jcp.org/xml/ns/javaee">

    <scan>

        <!-- Don't deploy the classes for the swing app! -->
        <exclude name="com.acme.swing.**" />

        <!-- Don't include GWT support if GWT is not installed -->
        <exclude name="com.acme.gwt.**">
            <if-class-not-available name="com.google.GWT"/>
        </exclude>

        <!--
            Exclude types from com.acme.verbose package if the system property verbosity is set to low
            i.e.
              java ... -Dverbosity=low
        -->
        <exclude name="com.acme.verbose.*">
            <if-system-property name="verbosity" value="low"/>
        </exclude>

        <!--
             Don't include JSF support if Wicket classes are present, and the viewlayer system
             property is set
        -->
        <exclude name="com.acme.jsf.**">
            <if-class-available name="org.apache.wicket.Wicket"/>
            <if-system-property name="viewlayer"/>
        </exclude>
    </scan>

</beans>

In this example we show the most common use cases for exercising fine control over which classes Weld scans. The first filter excludes all types whose package name starts with com.acme.swing, and in most cases this will be sufficient for your needs.

However, sometimes it’s useful to be able to activate the filter depending on the environment used. In this case, Weld allows you to activate (or deactivate) a filter based on either system properties or whether a class is available. The second filter shows the use case of disabling scanning of certain classes depending on the capabilities of the environment you deploy to - in this case we are excluding GWT support (all types whose package name starts with com.acme.gwt) if GWT is not installed.

Note

If you specify just a system property name, Weld will activate the filter if that system property has been set (with any value). If you also specify the system property value, then Weld will only activate the filter if the system property’s value matches exactly.

The third filter shows how to exclude all types from a specific package (note the name attribute has suffix ".*").

The fourth filter shows more a advanced configurations, where we use multiple activation conditions to decide whether to activate the filter.

You can combine as many activation conditions as you like (all must be true for the filter to be activated). If you want to a filter that is active if any of the activation conditions are true, then you need multiple identical filters, each with different activation conditions.

By default, CDI contexts are activated at the beginning of an HTTP request processing and deactivated once the processing finishes. This may represent an unnecessary overhead in certain situations, for example static resource serving.

Weld allows CDI context support to be mapped to a certain subset of requests only. A regular expression may be used for filtering HTTP requests that should have CDI contexts active during their processing.


<web-app version="3.1" xmlns="http://xmlns.jcp.org/xml/ns/javaee/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd">

    <context-param>
        <param-name>org.jboss.weld.context.mapping</param-name>
        <param-value>.*\.html</param-value>
    </context-param>

</web-app>