SeamFramework.orgCommunity Documentation
The philosophy of minimizing XML-based configuration is extremely strong in Seam. Nevertheless,
there are various reasons why we might want to configure a Seam component using XML: to isolate
deployment-specific information from the Java code, to enable the creation of re-usable frameworks,
to configure Seam's built-in functionality, etc.
Seam provides two basic approaches to configuring components: configuration via property settings in a
properties file or in web.xml, and configuration via components.xml.
Seam components may be provided with configuration properties either via servlet context parameters,
or via a properties file named seam.properties in the root of the classpath.
The configurable Seam component must expose JavaBeans-style property setter methods for the
configurable attributes. If a Seam component named com.jboss.myapp.settings has a
setter method named setLocale(), we can provide a property named
com.jboss.myapp.settings.locale in the seam.properties file or
as a servlet context parameter, and Seam will set the value of the locale attribute
whenever it instantiates the component.
The same mechanism is used to configure Seam itself. For example, to set the conversation timeout, we
provide a value for org.jboss.seam.core.manager.conversationTimeout in
web.xml or seam.properties. (There is a built-in Seam
component named org.jboss.seam.core.manager with a setter method named
setConversationTimeout().)
The components.xml file is a bit more powerful than property settings. It lets
you:
Configure components that have been installed automatically—including both built-in
components, and application components that have been annotated with the
@Name annotation and picked up by Seam's deployment scanner.
Install classes with no @Name annotation as Seam components—this
is most useful for certain kinds of infrastructural components which can be installed multiple
times 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 may appear in one of three different places:
The WEB-INF directory of a war.
The META-INF directory of a jar.
Any directory of a jar that contains classes with an
@Name annotation.
Usually, Seam components are installed when the deployment scanner discovers a class with a
@Name annotation sitting in an archive with a seam.properties
file or a META-INF/components.xml file. (Unless the component has an
@Install annotation indicating it should not be installed by default.)
The components.xml file lets us handle special cases where we need
to override the annotations.
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>
This example does the same thing:
<components>
<component class="org.jboss.seam.bpm.Jbpm"/>
</components>
This one 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>
As does this one:
<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>
This example creates 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>
It is common to use the auto-create option for infrastructural
objects like persistence contexts, which saves you from having to explicitly
specify create=true when you use 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 lets you specify a value or method binding
expression that will be evaluated to 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>
It is especially common to see the use of auto-create="true" with the
<factory> declaration:
<components>
<factory name="session" value="#{entityManager.delegate}" scope="STATELESS" auto-create="true"/>
</components>
Sometimes we want to reuse the same components.xml file with minor changes during
both deployment and testing. Seam lets you place wildcards of the form @wildcard@ in
the components.xml file which can be replaced either by your Ant build script (at
deployment time) or by providing a file named components.properties in the classpath
(at development time). You'll see this approach used in the Seam examples.
If you have a large number of components that need to be configured in XML, it makes much more sense
to split up the information in components.xml into many small files. Seam lets
you put configuration for a class named, for example, com.helloworld.Hello in a
resource named com/helloworld/Hello.component.xml. (You might be familiar with this
pattern, since it is the same one we use in Hibernate.) The root element of the file may be either a
<components> or <component>
element.
The first option lets you define multiple components in the file:
<components>
<component class="com.helloworld.Hello" name="hello">
<property name="name">#{user.name}</property>
</component>
<factory name="message" value="#{hello.message}"/>
</components>
The second option only lets you define or configure one component, but is less noisy:
<component name="hello">
<property name="name">#{user.name}</property>
</component>
In the second option, the class name is implied by the file in which the component definition appears.
Alternatively, you may put configuration for all classes in the com.helloworld
package in com/helloworld/components.xml.
Properties of string, primitive or primitive wrapper type may be configured just as you would expect:
org.jboss.seam.core.manager.conversationTimeout 60000
<core:manager conversation-timeout="60000"/>
<component name="org.jboss.seam.core.manager">
<property name="conversationTimeout">60000</property>
</component>
Arrays, sets and lists of strings or primitives are also supported:
org.jboss.seam.bpm.jbpm.processDefinitions order.jpdl.xml, return.jpdl.xml, inventory.jpdl.xml
<bpm:jbpm>
<bpm:process-definitions>
<value>order.jpdl.xml</value>
<value>return.jpdl.xml</value>
<value>inventory.jpdl.xml</value>
</bpm:process-definitions>
</bpm:jbpm>
<component name="org.jboss.seam.bpm.jbpm">
<property name="processDefinitions">
<value>order.jpdl.xml</value>
<value>return.jpdl.xml</value>
<value>inventory.jpdl.xml</value>
</property>
</component>
Even maps with String-valued keys and string or primitive values are supported:
<component name="issueEditor">
<property name="issueStatuses">
<key>open</key> <value>open issue</value>
<key>resolved</key> <value>issue resolved by developer</value>
<key>closed</key> <value>resolution accepted by user</value>
</property>
</component>
Finally, you may wire together components using a value-binding expression. Note that this is quite
different to injection using @In, since it happens at component instantiation time
instead of invocation time. It is therefore much more similar to the dependency injection facilities
offered by traditional IoC containers like JSF or Spring.
<drools:managed-working-memory name="policyPricingWorkingMemory" rule-base="#{policyPricingRules}"/>
<component name="policyPricingWorkingMemory"
class="org.jboss.seam.drools.ManagedWorkingMemory">
<property name="ruleBase">#{policyPricingRules}</property>
</component>
Throughout the examples, there have been two competing ways of declaring components: with and without
the use of XML namespaces. The following shows a typical components.xml file
without namespaces:
<?xml version="1.0" encoding="UTF-8"?>
<components xmlns="http://jboss.com/products/seam/components"
xsi:schemaLocation="http://jboss.com/products/seam/components http://jboss.com/products/seam/components-2.1.xsd">
<component class="org.jboss.seam.core.init">
<property name="debug">true</property>
<property name="jndiPattern">@jndiPattern@</property>
</component>
</components>
As you can see, this is somewhat verbose. Even worse, the component and attribute names cannot be validated at development time.
The namespaced version looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<components xmlns="http://jboss.com/products/seam/components"
xmlns:core="http://jboss.com/products/seam/core"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation=
"http://jboss.com/products/seam/core http://jboss.com/products/seam/core-2.1.xsd
http://jboss.com/products/seam/components http://jboss.com/products/seam/components-2.1.xsd">
<core:init debug="true" jndi-pattern="@jndiPattern@"/>
</components>
Even though the schema declarations are verbose, the actual XML content is lean and easy to understand.
The schemas provide detailed information about each component and the attributes available, allowing XML
editors to offer intelligent autocomplete. The use of namespaced elements makes generating and
maintaining correct components.xml files much simpler.
Now, this works great for the built-in Seam components, but what about user components? There are two options.
First, Seam supports mixing the two models, allowing the use of the generic <component>
declarations for user components, along with namespaced declarations for built-in components. But even better,
Seam allows you to quickly declare namespaces for your own components.
Any Java package can be associated with an XML namespace by annotating the package with the
@Namespace annotation. (Package-level annotations are declared in a file named
package-info.java in the package directory.) Here is an example from the seampay demo:
@Namespace(value="http://jboss.com/products/seam/examples/seampay")
package org.jboss.seam.example.seampay;
import org.jboss.seam.annotations.Namespace;
That is all you need to do to use the namespaced style in components.xml!
Now we can write:
<components xmlns="http://jboss.com/products/seam/components"
xmlns:pay="http://jboss.com/products/seam/examples/seampay"
... >
<pay:payment-home new-instance="#{newPayment}"
created-message="Created a new payment to #{newPayment.payee}" />
<pay:payment name="newPayment"
payee="Somebody"
account="#{selectedAccount}"
payment-date="#{currentDatetime}"
created-date="#{currentDatetime}" />
...
</components>
Or:
<components xmlns="http://jboss.com/products/seam/components"
xmlns:pay="http://jboss.com/products/seam/examples/seampay"
... >
<pay:payment-home>
<pay:new-instance>"#{newPayment}"</pay:new-instance>
<pay:created-message>Created a new payment to #{newPayment.payee}</pay:created-message>
</pay:payment-home>
<pay:payment name="newPayment">
<pay:payee>Somebody"</pay:payee>
<pay:account>#{selectedAccount}</pay:account>
<pay:payment-date>#{currentDatetime}</pay:payment-date>
<pay:created-date>#{currentDatetime}</pay:created-date>
</pay:payment>
...
</components>
These examples illustrate the two usage models of a namespaced element. In the first declaration,
the <pay:payment-home> references the paymentHome
component:
package org.jboss.seam.example.seampay;
...
@Name("paymentHome")
public class PaymentController
extends EntityHome<Payment>
{
...
}
The element name is the hyphenated form of the component name. The attributes of the element are the hyphenated form of the property names.
In the second declaration, the <pay:payment> element refers to the
Payment class in the org.jboss.seam.example.seampay package.
In this case Payment is an entity that is being declared as a Seam component:
package org.jboss.seam.example.seampay;
...
@Entity
public class Payment
implements Serializable
{
...
}
If we want validation and autocompletion to work for user-defined components, we will need a schema. Seam does not yet provide a mechanism to automatically generate a schema for a set of components, so it is necessary to generate one manually. The schema definitions for the standard Seam packages can be used for guidance.
The following are the the namespaces used by Seam:
components — http://jboss.com/products/seam/components
core — http://jboss.com/products/seam/core
drools — http://jboss.com/products/seam/drools
framework — http://jboss.com/products/seam/framework
jms — http://jboss.com/products/seam/jms
remoting — http://jboss.com/products/seam/remoting
theme — http://jboss.com/products/seam/theme
security — http://jboss.com/products/seam/security
mail — http://jboss.com/products/seam/mail
web — http://jboss.com/products/seam/web
pdf — http://jboss.com/products/seam/pdf
spring — http://jboss.com/products/seam/spring