Weld SiteCommunity Documentation
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):
weld.propertiesIf 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.
CDI requires that beans that are normal-scoped, intercepted or decorated always define a no-argument constructor.
This requirement applies even if the bean already defines an @Inject annotated constructor with parameters.
This is purely a technical requirement implied by how Java allocates class instances.
Weld is however able to operate fine even if this requirement is not met. Weld uses special non-portable JVM APIs that allow it to allocate proxy instances without calling proxy’s constructor. This mode is not enabled by default. It can be enabled using the following configuration option:
Table 19.1. Supported configuration properties
| Configuration key | Default value | Description |
|---|---|---|
| false (true in weld-se) | If set to |
Note that relaxed construction is enabled by default in Weld SE.
By default Weld supports concurrent loading and deploying of beans. However, in certain deployment scenarios the default setup may not be appropriate.
Table 19.2. Supported configuration properties
| Configuration key | Default value | Description |
|---|---|---|
| true | If set to false, |
|
| Weld is capable of resolving observer methods for container lifecycle events in advance while bean deployer threads are blocked waiting for I/O operations (such as classloading). This process is called preloading and leads to better CPU utilization and faster application startup time. This configuration option specifies the number of threads used for preloading. If set to 0, preloading is disabled. |
The bootstrap configuration may be altered using the deprecated org.jboss.weld.bootstrap.properties file located on the classpath (e.g. WEB-INF/classes/org.jboss.weld.bootstrap.properties in a web archive). The keys are concurrentDeployment and preloaderThreadPoolSize.
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 type | Description |
|---|---|
| Uses a fixed number of threads. The number of threads remains the same throughout the application. |
| Uses a fixed number of threads. A thread will be stopped after a configured period of inactivity. |
| A single-threaded thread pool |
| No executor is used by Weld |
| 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:
An integrator may choose to use custom implementation of org.jboss.weld.manager.api.ExecutorServices. If that’s the case, all configuration described in this section
might be ignored. An example of such integrator is WildFly.
Table 19.3. Supported configuration properties
| Configuration key | Default value | Description |
|---|---|---|
|
| The type of the thread pool. Possible values
are: |
|
| The
number of threads to be used for bean loading and deployment. Only used by |
| 60 seconds | Passed to the constructor of the
ThreadPoolExecutor class, maximum time that excess idle threads will
wait for new tasks before terminating. Only used by |
| false | If set to true, debug timing information is printed to the standard output. |
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.
By default the application initialization is performed in the portable
mode which denotes specification-compliant behaviour. However it’s also
possible to enable the non-portable mode, in which some definition
errors and deployment problems do not cause application initialization
to abort. Currently the non-portable mode allows extension developers to
call all the BeanManager's methods before the
AfterDeploymentValidation event is fired.
Table 19.4. Supported configuration properties
| Configuration key | Default value | Description |
|---|---|---|
| false | If set to |
The main purpose of the non-portable mode is to support some legacy extensions. It’s highly recommended to use the portable mode whenever possible - non-portable mode may lead to unexpected behaviour during initialization process.
Weld offers a non-standard way to create proxies for non-private, non-static final methods. When using this option, such final method will be ignored during proxy generation and the Java type will be proxied (as opposed to classical behavior when there would be an exception thrown). Since the method was ignored during proxy creation, it should never be invoked.
In order to make this work, use the below shown configuration key and pass it a regular expression. When Weld finds an unproxyable type which matches this pattern, the final methods will be ignored and the type will be proxied.
Table 19.5. Supported configuration properties
| Configuration key | Default value | Description |
|---|---|---|
| If defined, matching classes will be proxied and final methods ignored. |
Weld caches already resolved injection points in order to resolve them faster in the future. A separate type-safe resolver exists for beans, decorators, disposers, interceptors and observers. Each of them stores resolved injection points in its cache, which maximum size is bounded by a default value (common to all of them).
Table 19.6. Supported configuration properties
| Configuration key | Default value | Description |
|---|---|---|
| 65536 | The upper bound of the cache. |
For debugging purposes, it’s possible to dump the generated bytecode of client proxies and enhanced subclasses to the filesystem.
Table 19.7. Supported configuration properties
| Configuration key | Default value | Description |
|---|---|---|
| The file path where the files should be stored. |
For certain combinations of scopes, the container is permitted to optimize an injectable reference lookup. Enabling this feature brings some performance boost but causes javax.enterprise.context.spi.AlterableContext.destroy() not to work properly for @ApplicationScoped and @RequestScoped beans. Therefore, the optimization is disabled by default.
Table 19.8. Supported configuration properties
| Configuration key | Default value | Description |
|---|---|---|
| false | If set to |
This optimization is used to reduce the HTTP session replication overhead. However, the inconsistency detection mechanism may cause problems in some development environments. It’s recommended to disable this optimization during the development phase.
Table 19.9. Supported configuration properties
| Configuration key | Default value | Description |
|---|---|---|
| true (false in weld-servlet) | If set to |
This optimization is disabled by default in Servlet containers.
This configuration property should only be used if experiencing problems with rolling upgrades.
The delimiter is used to abbreviate a bean archive identifier (which is usually derived from the archive name) before used as a part of an identifier of an internal component (such as bean).
The abbreviation proceeds as follows:
.war, .ear, etc.) and the final value consists of the part before the delimiter and the archive suffix (if extracted)Note that the delimiter is used for all bean archives forming the application.
An example: Given an application with two versions going by the names test__1-1.war and test__1-2.war.
Weld normally cannot support replication of @SessionScoped beans between these two deployments.
Using this configuration option with delimiter "__" will allow Weld to see both applications simply as test.war, hence allowing for session replication.
Table 19.10. Supported configuration properties
| Configuration key | Default value | Description |
|---|---|---|
| The delimiter used during ID generation. |
Bean archive identifiers are provided by integrators. Therefore, the abbreviation algorithm may not always function properly.
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.
Table 19.11. Supported configuration properties
| Configuration key | Tool | Default value | Description |
|---|---|---|---|
| '' | A regular expression. If a non-empty string and the base type for an AnnotatedType or a declaring type for an AnnotatedMember matches this pattern the type is excluded from monitoring. | |
| true | If set to | |
| '' | A regular expression. If a non-empty string and the runtime class of the event object matches this pattern the event is excluded from monitoring. | |
| false | If set to | |
| true | If set to | |
| false | If set to | |
| '' | If a non-empty string the Probe data will be automatically exported after deployment validation. The value represents the path of the directory where to export the data file. |
To disable the monitoring entirely set org.jboss.weld.probe.invocationMonitor.excludeType and org.jboss.weld.probe.eventMonitor.excludeType properties to .*.
Weld provides configuration properties to override values for default conversation timeout and default conversation concurrent access timeout which represents the maximum time to wait on the conversation concurrent lock.
Table 19.12. Supported configuration properties
| Configuration key | Default value (ms) | Description |
|---|---|---|
| 600000 | Conversation timeout represent the maximum time during which is the conversation active. |
| 1000 | Conversation concurrent access timeout represent the maximum time to wait on the conversation concurrent lock. |
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.
Table 19.13. Supported configuration properties
| Configuration key | Default value | Description |
|---|---|---|
| A regular expression. If a non-empty string, then all annotated types whose |
CDI applications consist of user-defined beans implementing the business logic, but also beans coming from libraries (e.g. DeltaSpike) and integrations (e.g. various Java EE technologies - JSF, Bean Validation, Batch). Most applications actually use only a small part of the beans provided by libraries and integrations. Still, Weld has to retain the metadata for all the beans in memory which can be considerably vast footprint, depending on the application. If Section A.2.13, “Optimized cleanup after bootstrap” is allowed, Weld can remove unused beans after bootstrap.
An unused bean:
Instance<X> injection point.If you run Section 22.2.1, “Probe” and list all the beans in your application, you will almost certainly notice some of them coming from 3rd party libraries which you never use (marked with a trash icon). Those are candidates for unused beans as you can be sure you are not using them.
As usual, there is a trade-off between memory consumption and bootstrap time. The results may vary depending on the application, but you should always expect (most probably negligible) increase of the bootstrap time.
The following properties can be used to restrict the set of beans Weld is going to remove, e.g. to eliminate the false positives.
Table 19.14. Supported configuration properties
| Configuration key | Default value | Description |
|---|---|---|
|
| A regular expression. A bean whose |
|
| A regular expression. A bean is not removed if the corresponding |
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.
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.
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>