6.2. Configuring components via components.xml
The
components.xml
file is more powerful than property settings. It lets you:
- configure components that have been installed automatically, including built-in components, and application components that have been annotated with
@Name
and picked up by Seam's deployment scanner. - install classes with no
@Name
annotation as Seam components. This is most useful for infrastructural components which can be installed multiple times with different names (for example, Seam-managed persistence contexts). - install components that do have a
@Name
annotation but are not installed by default because of an@Install
annotation that indicates the component should not be installed. - override the scope of a component.
A
components.xml
file appears in one of three locations:
- The
WEB-INF
directory of aWAR
. - The
META-INF
directory of aJAR
. - Any
JAR
directory containing classes with a@Name
annotation.
Seam components are installed when the deployment scanner discovers a class with a
@Name
annotation in an archive with a seam.properties
file, or a META-INF/components.xml
file, unless the component also has an @Install
annotation indicating that it should not be installed by default. The components.xml
file handles special cases where the annotations must be overridden.
For example, the following
components.xml
file installs jBPM:
<components xmlns="http://jboss.com/products/seam/components" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:bpm="http://jboss.com/products/seam/bpm"> <bpm:jbpm/> </components>
The following example also installs jBPM:
<components> <component class="org.jboss.seam.bpm.Jbpm"/> </components>
This example installs and configures two different Seam-managed persistence contexts:
<components xmlns="http://jboss.com/products/seam/components" xmlns:persistence="http://jboss.com/products/seam/persistence"> <persistence:managed-persistence-context name="customerDatabase" persistence-unit-jndi-name="java:/customerEntityManagerFactory"/> <persistence:managed-persistence-context name="accountingDatabase" persistence-unit-jndi-name="java:/accountingEntityManagerFactory"/> </components>
This example also installs and configures two different Seam-managed persistence contexts:
<components> <component name="customerDatabase" class="org.jboss.seam.persistence.ManagedPersistenceContext"> <property name="persistenceUnitJndiName"> java:/customerEntityManagerFactory </property> </component> <component name="accountingDatabase" class="org.jboss.seam.persistence.ManagedPersistenceContext"> <property name="persistenceUnitJndiName"> java:/accountingEntityManagerFactory </property> </component> </components>
The following examples create a session-scoped Seam-managed persistence context. (This is not recommended in practice.)
<components xmlns="http://jboss.com/products/seam/components" xmlns:persistence="http://jboss.com/products/seam/persistence"> <persistence:managed-persistence-context name="productDatabase" scope="session" persistence-unit-jndi-name="java:/productEntityManagerFactory"/> </components>
<components> <component name="productDatabase" scope="session" class="org.jboss.seam.persistence.ManagedPersistenceContext"> <property name="persistenceUnitJndiName"> java:/productEntityManagerFactory </property> </component> </components>
The
auto-create
option is commonly used for infrastructural objects such as persistence contexts, removing the need to specify create=true
explicitly when using the @In
annotation.
<components xmlns="http://jboss.com/products/seam/components" xmlns:persistence="http://jboss.com/products/seam/persistence"> <persistence:managed-persistence-context name="productDatabase" auto-create="true" persistence-unit-jndi-name="java:/productEntityManagerFactory"/> </components>
<components> <component name="productDatabase" auto-create="true" class="org.jboss.seam.persistence.ManagedPersistenceContext"> <property name="persistenceUnitJndiName"> java:/productEntityManagerFactory </property> </component> </components>
The
<factory>
declaration specifies a value- or method-binding expression that will initialize the value of a context variable when it is first referenced.
<components> <factory name="contact" method="#{contactManager.loadContact}" scope="CONVERSATION"/> </components>
You can create an alias (a second name) for a Seam component like so:
<components> <factory name="user" value="#{actor}" scope="STATELESS"/> </components>
You can even create an alias for a commonly used expression:
<components> <factory name="contact" value="#{contactManager.contact}" scope="STATELESS"/> </components>
auto-create="true"
is often used with the <factory>
declaration:
<components> <factory name="session" value="#{entityManager.delegate}" scope="STATELESS" auto-create="true"/> </components>
The same
components.xml
file is sometimes used (with minor changes) during both deployment and testing. Seam allows wildcards of the form @wildcard@
to be placed in components.xml
, which can be replaced at deployment time by either your Ant build script, or providing a file named components.properties
in the classpath. (The latter approach appears in the Seam examples.)