Chapter 15. XML Configuration Introduction

15.1. Getting Started
15.2. The Princess Rescue Example

Solder 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.

15.1. Getting Started

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

/META-INF/beans.xml
/META-INF/seam-beans.xml

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.


<?xml version="1.0" encoding="UTF-8"?>

<beans xmlns="http://java.sun.com/xml/ns/javaee"

ml_plain">       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

ml_plain">       xmlns:s="urn:java:ee" 

       xmlns:r="urn:java:org.example.reports">

ml_plain">

ml_plain">  <r:Report>

ml_plain">   <s:modifies/>

   <r:filename>sales.jrxml<r:filename>

ml_plain">   <r:datasource>

    <r:SalesQualifier/>

   </r:datasource>

  </r:Report>

ml_plain">   

ml_plain">  <r:Report filename="billing.jrxml">

   <s:replaces/>

ml_plain">   <r:datasource>

ml_plain">    <s:Inject/>

    <s:Exact>org.example.reports.BillingDatasource</s:Exact>

   </r:datasource>

   </r:Report>   

</beans>

	The namespace `urn:java:ee` is the XML Config's root namespace. This is where the built-in elements and CDI annotations live.
	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 separating 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.
	The `<Report>` declaration configures an instance of the `Report` class as a bean.
	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.
	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.
	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.
	This is the shorthand syntax for setting a field value.
	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.
	The `<s:Inject>` element is needed as this bean was installed with `<s:replaces>`, so annotations are not read from the class definition.
	The `<s:Exact>` annotation restricts the type of bean that is available for injection without using qualifiers. In this case `BillingDatasource` will be injected. This is provided as part of weld-extensions.

15.2. The Princess Rescue Example

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

mvn -Pjetty 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.