The beans.xml file supports declaration of application level metadata.
The file format is typesafe and extensible:
Multiple namespaces are accommodated, each representing a Java package.
XML elements belonging to these namespaces represent Java types, fields and methods.
Each namespace may declare an XML schema.
If a beans.xml file contains any XML element without a declared namespace, the container automatically detects the problem and treats it as a definition error, as defined in Section 11.3, “Problems detected automatically by the container”.
Note that it is possible for the XML schema for a namespace to be generated by a tool from the Java classes.
Open issue: it is proposed to add a set of XML elements to the namespace urn:java:ee that allow beans to be declared in a more traditional (nontypesafe) manner.
Every Java package has a corresponding XML namespace. The namespace URN consists of the package name, with the prefix urn:java:. For example, the package com.mydomain.myapp has the XML namespace urn:java:com.mydomain.myapp.
<Beans xmlns="urn:java:ee"
xmlns:myapp="urn:java:com.mydomain.myapp">
...
</Beans>Each namespace may, optionally, have a schema.
<Beans xmlns="urn:java:ee"
xmlns:myapp="urn:java:com.mydomain.myapp"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:java:ee http://java.sun.com/jee/ee/schema-1.0.xsd
urn:java:com.mydomain.myapp http://mydomain.com/myapp/schema-1.2.xsd">
...
</Beans>An XML element belonging to such a namespace represents a Java type in the corresponding Java package, or a method or field of a type in that package. If there is a Java type in the package with the same name as the XML element, the XML element can be interpreted to represent that Java type.
For example, the element <List> in the namespace urn:java:java.util represents java.util.List.
Type parameters may be specified by child elements of the element that represents the type. For example:
<List>
<myapp:Product/>
</List>Members of a type may be specified by child elements of the element that represents the type, in the same namespace as the element that represents the type. For example:
<myapp:ShoppingCart>
<myapp:paymentProcessor>
...
</myapp:paymentProcessor>
</myapp:ShoppingCart>Alternatively, a namespace may represent several Java packages. Such a namespace must have a URN consisting of the prefix urn:java: followed by a period-separated list of valid Java identifiers. The list of packages for such a namespace must be defined in a classpath resource named namespace in the path named by the identifier list. For example, the packages for the namespace urn:java:org.myframework must be listed in the resource /org/myframework/namespace. The format of this file is a list of packages, separated by whitespace.
An XML element belonging to such a namespace represents a Java type in one of the listed packages, or a method or field of a type in one of the listed packages. If there are multiple packages containing a Java type with the same name as the XML element, the container automatically detects the problem and treats it as a definition error, as defined in Section 11.3, “Problems detected automatically by the container”. If there is exactly one Java type in the listed packages with the same name as the XML element, the XML element can be interpreted to represent that Java type.
The Java EE namespace urn:java:ee represents the following packages:
java.lang
java.util
javax.annotation
javax.inject
javax.context
javax.interceptor
javax.decorator
javax.event
javax.ejb
javax.persistence
javax.xml.ws
javax.jms
javax.sql
Several elements in this special namespace do not represent Java types.
The root <Beans> element, together with the <Deploy>, <Interceptors> and <Decorators> elements belong to the namespace urn:java:ee and do not represent Java types nor members of Java types.
Java array types may be represented by an <Array> element in the namespace urn:java:ee, with a child element representing the element type. For example:
<Array>
<myapp:Product/>
</Array>The element <value> which represents a collection element belongs to the namespace urn:java:ee.
Primitive types may be represented by the XML element that represents the corresponding wrapper type in java.lang, since primitive and wrapper types are considered identical for the purposes of typesafe resolution, and assignable for the purposes of injection. For example, the element <Integer> in the namespace urn:java:ee represents both int and java.lang.Integer.
The container must validate all namespaces for which schemas are available in the classpath. The container searches for a schema for each namespace in the classpath directory corresponding to the namespace. The schema must be named schema.xsd. For example, the container will validate the namespace urn:com.mydomain.myapp against the resource /com/mydomain/myapp/schema.xsd if any such resource exists.
An XML element that appears as a direct child of the root <Beans> element is interpreted as a binding type, interceptor binding type or stereotype declaration if it has a direct child <BindingType>, <InterceptorBindingType> or <Stereotype> element in the Java EE namespace, as defined in Section 2.3.2, “Defining new binding types”, Section A.3.5, “Interceptor bindings” and Section 2.7.1, “Defining new stereotypes”.
The XML element is interpreted as a Java type. If no such Java type exists in the classpath, the container automatically detects the problem and treats it as a definition error, as defined in Section 11.3, “Problems detected automatically by the container”. If the type is not an annotation type, the container automatically detects the problem and treats it as a definition error, as defined in Section 11.3, “Problems detected automatically by the container”.
If the annotation type is already declared as a binding type, interceptor binding type or stereotype using annotations, the annotations are ignored by the container and the XML-based declaration is used.
If a certain annotation type is declared more than once as a binding type, interceptor binding type or stereotype using XML, the container automatically detects the problem and treats it as a definition error, as defined in Section 11.3, “Problems detected automatically by the container”.
Every direct child element of a stereotype declaration is interpreted as a Java type. If no such Java type exists in the classpath, the container automatically detects the problem and treats it as a definition error, as defined in Section 11.3, “Problems detected automatically by the container”. If the type is not an annotation type, the container automatically detects the problem and treats it as a definition error, as defined in Section 11.3, “Problems detected automatically by the container”.
If the annotation type is a scope type, the default scope of the stereotype was declared.
If the annotation type is a deployment type, the default scope of the stereotype was declared.
If the annotation type is a interceptor binding type, an interceptor binding of the stereotype was declared.
If the annotation type is javax.annotation.Named, a stereotype with name defaulting was declared.
Otherwise, the container automatically detects the problem and treats it as a definition error, as defined in Section 11.3, “Problems detected automatically by the container”.
Every direct child element of an interceptor binding type declaration is interpreted as a Java type. If no such Java type exists in the classpath, the container automatically detects the problem and treats it as a definition error, as defined in Section 11.3, “Problems detected automatically by the container”. If the type is not an annotation type, the container automatically detects the problem and treats it as a definition error, as defined in Section 11.3, “Problems detected automatically by the container”.
If the annotation type is an interceptor binding type, an inherited interceptor binding was declared, as defined in Section A.3.5.1, “Interceptor binding types with additional interceptor bindings”.
Otherwise, the container automatically detects the problem and treats it as a definition error, as defined in Section 11.3, “Problems detected automatically by the container”.
The <Deploy>, <Interceptors> and <Decorators> elements in the Java EE namespace determine which beans, interceptors and decorators are enabled in a particular deployment.
Each direct child element of a <Deploy> element is interpreted as the declaring an enabled deployment type, as specified in Section 2.5.5, “Enabled deployment types”.
Each child element is interpreted as a Java annotation type. If no such Java type exists in the classpath, the container automatically detects the problem and treats it as a definition error, as defined in Section 11.3, “Problems detected automatically by the container”. If the type is not a deployment type, the container automatically detects the problem and treats it as a definition error, as defined in Section 11.3, “Problems detected automatically by the container”.
If the same deployment type is declared more than once, the container automatically detects the problem and treats it as a definition error, as defined in Section 11.3, “Problems detected automatically by the container”.
Each direct child element of an <Interceptors> element is interpreted as the declaring an enabled interceptor, as specified in Section A.3.8, “Interceptor enablement and ordering”.
Each child element is interpreted as a Java class. If no such Java class exists in the classpath, the container automatically detects the problem and treats it as a definition error, as defined in Section 11.3, “Problems detected automatically by the container”.
If the same interceptor is declared more than once, the container automatically detects the problem and treats it as a definition error, as defined in Section 11.3, “Problems detected automatically by the container”.
Each direct child element of a <Decorators> element is interpreted as the declaring an enabled decorator, as specified in Section A.5.4, “Decorator enablement and ordering”.
Each child element is interpreted as a Java class. If no such Java class exists in the classpath, the container automatically detects the problem and treats it as a definition error, as defined in Section 11.3, “Problems detected automatically by the container”.
If the same decorator is declared more than once, the container automatically detects the problem and treats it as a definition error, as defined in Section 11.3, “Problems detected automatically by the container”.