⁠7.2. Configuring components via components.xml

The components.xml file is more powerful than property settings. It allows you to:
  • 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 have a @Name annotation but are not installed by default because of an @Install annotation that indicates that the component should not be installed.
  • override the scope of a component.
The components.xml file appears in one of the following three locations:
  • The WEB-INF directory of a WAR.
  • The META-INF directory of a JAR.
  • 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.
The following example installs and configures two different Seam-managed persistence contexts: 
​<components xmlns="http://jboss.org/schema/seam/components" xmlns:persistence="http://jboss.org/schema/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>
The following 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 creates a session-scoped Seam-managed persistence context. (This is not recommended in practice.) 
​<components xmlns="http://jboss.org/schema/seam/components" xmlns:persistence="http://jboss.org/schema/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.org/schema/seam/components" xmlns:persistence="http://jboss.org/schema/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-binding or method-binding expression that initializes the value of a context variable when the variable 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 as follows: 
​<components> 
​  <factory name="user" value="#{actor}" scope="STATELESS"/>
​</components>
You can create an alias for a commonly used expression as follows: 
​<components> 
​  <factory name="contact" value="#{contactManager.contact}" scope="STATELESS"/>
​</components>
auto-create="true" is often used with the <factory> declaration as follows: 
​<components> 
​  <factory name="session" value="#{entityManager.delegate}" scope="STATELESS" auto-create="true"/> 
​</components>
The 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 the components.xml file. This can be replaced at deployment time by your Ant build script, or by providing a file named components.properties in the classpath. (The latter approach appears in the Seam examples.)