SeamFramework.orgCommunity Documentation

Chapter 1. Seam Config Introduction

1.1. Getting Started
1.2. The Princess Rescue Example

Seam provides a method for configuring CDI beans using alternate metadata sources, such as XML configuration. Currently, the XML provider is the only alternative available. Using a "type-safe" XML syntax, it is possible to add new beans, override existing beans, and add extra configuration to existing beans.

1.1. Getting Started

Simply include the JAR file and the Seam Solder JAR in your project. For Maven projects, that means adding the following dependencies to your pom.xml: 




         <dependency>

            <groupId>org.jboss.seam.config</groupId>

            <artifactId>seam-config-xml</artifactId>

            <version>${seam.config.version}</version>

            <scope>runtime</scope>

         </dependency>



         <dependency>

            <groupId>org.jboss.seam.solder</groupId>

            <artifactId>seam-solder</artifactId>

            <version>${weld.extensions.version}</version>

         </dependency>

      

To take advantage of Seam Config, you need metadata sources in the form of XML files. By default these are discovered from the classpath in the following locations:

The beans.xml file is the preferred way of configuring beans via XML; however some CDI implementations will not allow this, so seam-beans.xml is provided as an alternative.

Here is a simple example. The following class represents a report: 

class Report {

    String filename;

    

    @Inject

    Datasource datasource;

    

    //getters and setters

}

And the following support classes: 

interface Datasource {

    public Data getData();

}


@SalesQualifier

class SalesDatasource implements Datasource {

  public Data getData()

  {

    //return sales data

  }

}


class BillingDatasource implements Datasource {

  public Data getData()

  {

    //return billing data

  }

}

The Report bean is fairly simple. It has a filename that tells the report engine where to load the report definition from, and a datasource that provides the data used to fill the report. We are going to configure up multiple Report beans via xml.

Example 1.1. 

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://java.sun.com/xml/ns/javaee"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:s(1)="urn:java:ee" 
       xmlns:r(2)="urn:java:org.example.reports">

 	<r:Report>  (3)
 		<s:modifies(4)/>
 		<r:filename(5)>sales.jrxml<r:filename>
 		<r:datasource>
 			<r:SalesQu(6)alifier/>
 		</r:datasource>
  	</r:Report>
  	
 	<r:Report fi(7)lename="billing.jrxml">
 		<s:replaces(8)/>
 		<r:datasource>
 			<s:Inject/(9)>
 			<s:Exact>o(10)rg.example.reports.BillingDatasource</s:Exact>
 		</r:datasource>
  	</r:Report>  	
</beans>

1

The namespace urn:java:ee is Seam Config's root namespace. This is where the built-in elements and CDI annotations live.

2

There are now multiple namespaces in the beans.xml file. These namespaces correspond to java package names.

The namespace urn:java:org.example.reports corresponds to the package org.example.reports, where the reporting classes live. Multiple java packages can be aggregated into a single namespace declaration by seperating the package names with colons, e.g. urn:java:org.example.reports:org.example.model. The namespaces are searched in the order they are specified in the xml document, so if two packages in the namespace have a class with the same name, the first one listed will be resolved. For more information see Namespaces.

3

The <Report> declaration configures an instance of the Report class as a bean.

4

Beans installed using <s:modifies> read annotations from the existing class, and merge them with the annotations defined via xml. In addition, if a bean is installed with <s:modifies>, it prevents the original class being installed as a bean. It is also possible to add new beans and replace beans altogether. For more information see Adding, modifying and replacing beans.

5

The <r:filename> element sets the initial value of the filename field. For more information on how methods and fields are resolved see Configuring Methods, and Configuring Fields.

6

The <r:SalesQualifier> element applies the @SalesQualifier to the datasource field. As the field already has an @Inject on the class definition this will cause the SalesDatasource bean to be injected.

7

This is the shorthand syntax for setting a field value.

8

Beans installed using <s:replaces> do not read annotations from the existing class. In addition, if a bean is installed with <s:replaces> it prevents the original class being installed as a bean.

9

The <s:Inject> element is needed as this bean was installed with <s:replaces>, so annotations are not read from the class definition.

10

The <s:Exact> annotation restricts the type of bean that is availible for injection without using qualifiers. In this case BillingDatasource will be injected. This is provided as part of weld-extensions.


1.2. The Princess Rescue Example

The princess rescue example is a sample web app that uses Seam Config. Run it with the following command: 

mvn jetty:run

And then navigate to http://localhost:9090/princess-rescue. The XML configuration for the example is in src/main/resources/META-INF/seam-beans.xml.