SeamFramework.orgCommunity Documentation

Chapter 1. Seam XML Introduction

1.1. Getting Started
1.2. The Princess Rescue Example

Seam provides a method for configuring JSR-299 beans using XML. Using XML it is possible to add new beans, override existing beans, and add extra configuration to existing beans.

1.1. Getting Started

No special configuration is required, all that is required is to include the jar file and the weld extensions jar in your deployment.

The first thing we need is some 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 it may be possible that some JSR-299 implementations will not allow this, so seam-beans.xml is provided as an alternative.

Let's start with a simple example. Say we have the following class that 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

  }

}

Our 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-xml's root namespace. This is where the builtin tags 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 our 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 our 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 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

TODO next release