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.properties
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.
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 | If set to |
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.
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. |
| 60 seconds | Passed to the constructor of the ThreadPoolExecutor class, maximum time that excess idle threads will wait for new tasks before terminating. |
| 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.
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.10. 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 |
To disable the monitoring entirely set org.jboss.weld.probe.invocationMonitor.excludeType
and org.jboss.weld.probe.eventMonitor.excludeType
properties to .*
.
There was a bug in Weld where the default name of a bean did not met the CDI specification requirements. This bug is fixed in Weld 2.2.14.Final and later versions. However, this fix is not backward compatible. Therefore, a special cofiguration option may be used to switch to the legacy strategy to infer the default bean names.
Table 19.11. Supported configuration properties
Configuration key | Default value | Description |
---|---|---|
| false | If set to |
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. Bean discovery.
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>