When a method is invoked on a component, its dependencies are injected from the current context. Seam performs a context lookup in the following order of precedence: Event Scope, Page Scope, Conversation Scope, Session Scope, Business Scope, Application Scope.
Component Annotations
Component Definition Annotations
In order for your Seam components to take advantage of bijection, you must register them with the Seam container. Registering your component with Seam is as simple as annotating it with @Name. The following annotations will register your component and define its lifecycle.
AnnotationUseDescription@NameTypeDeclares a Seam component by name. The component is registered with Seam and can be referenced by name through Expression Language (EL), injection, or a context lookup.@ScopeTypeDefines the scope (or context) the Seam component will be placed into by the container when created.@AutoCreateTypeSpecifies that a component should be created when being injected if not available in the current context.@StartupTypeIndicates that an application scoped component should be created when the application is initialized or that a session component should be created when a session is started. Not valid for any other contexts.@InstallTypeDeclares whether a Seam component should be installed based on availability of dependencies or precedence.@RoleTypeDefines an additional name and scope associated with the component. The @Roles annotation allows definition of multiple roles.
Component Bijection Annotations: Once you have defined a component, you can specify the dependencies of your component and what the component contributes back to the context.
AnnotationUseDescription@InField, MethodDeclares a dependency that will be injected from the context, according to context precedence, prior to a method invocation. Note that these attributes will be disinjected (or set to null) after the invocation completes.@OutField, MethodDeclares a value that will be outjected after a method invocation to the context of the component (implicit) or a specified context (explicit).
Component Lifecycle Annotations: The following annotations allow you to control the lifecycle of a component either by reacting to events or wrapping the component entirely.
AnnotationUseDescription@CreateMethodDeclares that a method should be called after component instantiation.@DestroyMethodDeclares that a method should be called just before component destruction.@FactoryMethodMarks a method as a factory method for a context variable. A factory method is called whenever no value is bound to the named context variable and either initializes and outjects the value or simply returns the value to the context.@UnwrapMethodDeclares that the object returned by the annotated getter method is to be injected instead of the component itself. Referred to as the "manager component" pattern.
Component Events Annotations: Through Seam's event model, components can raise events or listen for events raised by other components through simple annotation. In addition, Seam defines a number of built-in events that the application can use to perform special kinds of framework integration (see http://seamframework.org/Documentation, Contextual Events).
AnnotationUseDescription@RaiseEventMethodDeclares that a named event should be raised after the method returns a non-null result without exception.@ObserverMethodDeclares that a method should be invoked on occurrence of a named event or multiple named events.
The Components Namespace
Schema URI
http://jboss.com/products/seam/components
Schema XSD
http://jboss.com/products/seam/components-2.1.xsd
So far we've seen how components can be declared using annotations. In most cases this is the preferred approach, but there are some situations when component definition through annotations is not an option:
- when a class from a library outside of your control is to be exposed as a component
- when the same class is being configured as multiple components
In addition, you may want to configure values into a component that could change by environment, e.g. ip-addresses, ports, etc. In any of these cases, we can use XML to configure the component through the components namespace.
Seam XML Diagram Key
The Seam XML diagrams use the following notations to indicate required elements, cardinality, and containment:
Components Namespace Diagram
Components Namespace Elements
ElementDescription<component>Defines a component in the Seam container.<event>Specifies an event type and the actions to execute on occurrence of the event.<factory>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. Generally used for aliasing.<import>Specifies component namespaces that should be imported globally which allows referencing by unqualified component names. Specified by package.<action>Specifies an action to execute through a method binding expression.<property>Injects a value or reference into a Seam component. Can use a value or method binding expression to inject components.<key>Defines the key for the following value when defining a map.<value>For list values, the value to be added. For map values, the value for the preceding key.
Component Element Attributes: The attributes of the component element are synonymous with component definition through annotations.
ElementDescriptionnameDeclares a component by name; synonymous with @Name.classReferences the Java class of the component implementation.scopeDefines the scope (or context) the Seam component will be placed into by the container when created.precedencePrecedence is used when a name-clash is found between two components (higher precedence wins).installedBoolean indicating whether the component should be installed.auto-createSpecifies that a component should be created when being injected if not available in the current context.startupIndicates that an application scoped component should be created when the application is initialized or that a session component should be created when a session is started. Not valid for any other contexts.startupDependsA list of other application scope components that should be started before this one, if they are installed.jndi-nameEJB components only. The JNDI name used to lookup the component. Only used with EJB components that don't follow the global JNDI pattern.Components Namespace ExampleThe following examples demonstrate how component configuration is possible with Seam. The hotelBooking component is configured for injection of a paymentService instance.
<?xml version="1.0" encoding="UTF-8"?>
<components
xmlns="http://jboss.com/products/seam/components"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation=
"http://jboss.com/products/seam/components
http://jboss.com/products/seam/components-2.1.xsd">
<component name="hotelBooking">
<property name="paymentService">
#{paymentService}
</property>
</component>
<component name="paymentService" scope="APPLICATION"
class="com.othercompany.PaymentServiceClient">
<property name="ipAddress">127.0.0.1
<property name="port">9998
</component>
</components>
Note that we specified a name and class for the PaymentServiceClient instances. This is required as the PaymentServiceClient is a library implementation. The name is always required, but the class can be omitted if you are simply configuring the values of a component with an @Name annotation as shown with the hotelBooking. The scope is restricted to the scopes provided by Seam; here we use APPLICATION.Simplify your component configuration through use of namespaces.
Seam makes this quite simple through use of the @Namespace annotation. Just create a file named package-info.java in the package where your components live:
@Namespace(value="http://solutionsfit.com/example/booking")
package com.solutionsfit.example.booking;
import org.jboss.seam.annotations.Namespace;
Now we can reference the namespace in our components.xml:
<components xmlns=
"http://jboss.com/products/seam/components"
xmlns:payment="http://solutionsfit.com/example/booking">
... ...
<payment:hotel-booking
payment-service="#{paymentService}">
Note that component names and attribute names are specified in hyphenated form when using namespaces. To gain the benefits of auto-completion and validation, a schema can also be created to represent your components. A custom schema can import the components namespace to reuse the defined component types.
{{ parent.title || parent.header.title}}
{{ parent.tldr }}
{{ parent.linkDescription }}
{{ parent.urlSource.name }}