JBoss Seam Integration

The EJB3 cartridge now has the ability to enable your EJB 3.0 components as Seam components. The JBoss Online Booking example tries to illustrate how you can use the EJB3 cartridge with Seam enabled features.

Please note that the EJB3 cartridge will NOT generate any view components. A Seam cartridge is planned which will do this job and can be used with the EJB3 cartridge.

This howto will presume you have an understanding of the JBoss Seam framework. Read about JBoss Seam and try out the examples.

Remember: You must set the seamEnabled and persistenceProviderExtensions namespace properties such that Seam specific project settings are generated and Hibernate validator specific annotations are generated.

Seam Version

The cartridge will generate the Seam components using JBoss Seam 1.1.0-GA. Read the JBoss Seam Getting Started guide to learn how to download and setup your Seam environment, plus play around with the examples.

Project Generator

The AndroMDApp project generator from 3.3-SNAPSHOT in CVS onwards supports JBoss Seam for EJB3 and JSF for web project only. As long as you select these components, all the necessary JBoss Seam properties will be enabled in your project.

Once you run the project generator mvn org.andromda.maven.plugins:andromdapp-maven-plugin:generate, you must select EJB 3.0 as the persistence framework and JSF as the web framework. You will then be prompted to enable JBoss Seams.

Seam Profile

There exists a separate Seam profile that needs to be imported into your project UML. This profile contains the Seam specific tags and stereotypes you need to model on your components.

You can get this profile by if you have checked out the latest andromda-plugins project from HEAD (follow Installation) and build the Profiles project. Once this is done, the profile will be copied to your M2 repository under M2_REPO/org/andromda/profiles/uml14/andromda-profile-seam/VERSION/. You can then import this andromda-profile-seam-VERSION.xml.zip profile into your model to utilize the Seam components.

Seam Quick Start Guide

Because we are not going to replace the existing JBoss tutorials here, it is assumed you have followed the links above to understand the Seam framework and where you need the appropriate annotation or metadata. The following sections will briefly explain the more common Seam stereotypes and tagged values. You can always find more documentation on these within the andromda-profile-seam.

Seam Component

Every entity or session bean which is to be modeled as a Seam component must have an extra <<Seam>> stereotype, along with the traditional <<Entity>> or <<Service>> stereotypes. However, now you can also model a value object with the <<ValueObject>> stereotype as a Seam component in the same way.

Component Name

If you model the <<Seam>> stereotype, the @Name annotation will be generated with the value being the class name. You can override this by modeling the andromda_seam_component_name tagged value.

Component Scope

The andromda_seam_component_scope tagged value on Seam component classes provides enumerated values to set the scope of the component. The default scope depends on the component type.

If you have modeled roles for the component, then you can use the andromda_seam_component_role_scope tagged value where the list of scopes must be in the same order as the role names.

Logger

To make use of the JBoss Seam logger, you can model a component attribute of Object type with stereotype <<Logger>>. You can further specify the name of the log category with andromda_seam_bijection_logger_value tagged value.

Bijection

The @In and @Out annotations for bijection are rendered on attributes defined on session bean classes where <<In>> and <<Out>> stereotypes are modeled respectively.

If attribute multiplicity is 0, 0..1, 0..*, the require property is defined in both annotations.

If attribute multiplicity is 1, 1..* the create property is defined on the @In annotation. You can explicitly specify this using the andromda_seam_bijection_in_create tagged value.

To explicitly specify the name of the context variable for the @In annotation, model the andromda_seam_bijection_in_value tagged value. This can also be used to specify the JSF EL expression. If not specified, the name will default to the component attribute. The andromda_seam_bijection_out_value tagged value can be used for the @Out annotation.

Creating Seam Component

The @Create annotation is rendered on session bean operations if a <<Create>> stereotype is modeled on this method, indicating that the method should be called when an instance of the component is instantiated by Seam.

Destruction of Context Variables

The @Destroy annotation is rendered on a session bean operation if a <<Destroy>> stereotype is modeled on it. Otherwise, by default, a Destroy method is generated with this annotation.

Not Null Validation

The @NotNull annotation will be rendered on getters based on attribute multiplicity.

Length Validation

The @Length annotation's max property is taken from andromda_persistence_column_length tagged value. It is planned to specify a min length, set via the same tagged value with format x,y where x is min, y is max. This has currently not been implemented.

Component Validation

The <<Valid>> stereotype can be modeled on session bean component attributes to render the @Valid annotation for Hibernate Validator to recursively validate this and related objects.

The <<Validator>> stereotype can be modeled on Seam component operations indicating the validator must validate the component before invoking the method.

This component operation can now model the andromda_seam_validation_outcome tagged value to indicate the JSF outcome when validation fails.

The andromda_seam_validation_refreshEntities tagged value can also optionally be modeled with values 'true' or 'false' and if defined, adds the refreshEntities property to the annotation. This will indicate any invalid entity in the managed state be refreshed from the database when validation fails. This is used in conjunction with extended persistence context.

Stateful Session Bean Components

As soon as you introduce session bean attributes, the cartridge defines the bean as a stateful session bean only if none of the attributes are modeled with Seam related stereotypes or tagged values. If you have only Seam component attributes in the session bean (which by the way, is a Seam component), the bean is not defined as a SFSB. If you wish to explicitly define this bean as a SFSB you can do this via the tagged value andromda_service_type.

Data Model

The <<DataModel>> stereotype can be modeled on component attributes of type List, Map, Set or Object[]. This will render @DataModel on the attribute.

An optional tagged value andromda_seam_data_datamodel_value can be modeled on such attributes to defined the context variable name if more than one datamodel exists.

The exposed attribute will have the scope of the owning component, or the EVENT scope if the owning component itself has a STATELESS scope. You can optionally explicitly define the scope using andromda_seam_data_datamodel_scope tagged value.

Data Model Selection

The <<DataModelSelection>> stereotype can be modeled on component attributes to inject the selected value from the DataModel into the attribute. The JSF DataModel is the underlying collection or map value. This will render @DataModelSelection on the attribute.

An optional tagged value andromda_seam_data_datamodelselection_value can define the name of the context variable specified by the appropriate @DataModel. This tagged value is not needed is there is only one @DataModel element in the Seam component.

Initializing Context Variable

The <<Factory>> stereotype can be modeled on session bean component operations with the optional andromda_seam_bijection_factory_value tagged value which can be modeled on the operation to set the context variable name. If this tagged value is NOT set, the default value is the property name. You can optionally explicitly specify the scope of the context variable by using the andromda_seam_bijection_factory_scope tagged value.

Request Parameters

The <<RequestParameter>> stereotype can be modeled on session bean component attributes to indicate an attribute is to be injected with the value of a request parameter.

The optional tagged value andromda_seam_component_requestparameter_value will define the request parameter name. If this is NOT set, the name will default to the name of the component attribute.

Transaction Rollback

You can model the <<Rollback>> stereotype on component method, which will set the transaction to rollback when the method completes, if the outcome of the method matches any of the listed outcomes or when no outcomes are listed. You set the list of outcomes using the following tagged value.

The tagged value andromda_seam_transaction_rollback_ifoutcome which can be set on bean component operations that have the <<Rollback>> stereotype, can have multiple values to indicate the list of outcomes that trigger a rollback.

Action Outcome in Absence of a Conversation

The tagged value andromda_seam_component_conversational_ifnotbegunoutcome can be set to render the ifNotBegunOutcome property on the @Conversational annotation to indicate the JSF outcome for the action, if no long-running conversation is active when the component is invoked.

Beginging a Conversation

The<<Begin>> stereotype can be modeled on Seam component operations to indicate a long-running conversation has started. This will render a @Begin annotation on the operation. The following tagged values can be defined within the context of this component:

  • andromda_seam_conversation_begin_flushmode
  • andromda_seam_conversation_begin_ifoutcome - Can have multiple values
  • andromda_seam_conversation_begin_join
  • andromda_seam_conversation_begin_nested
  • andromda_seam_conversation_begin_pageflow

Ending a Conversation

The <<End>> stereotype can be modeled on Seam component operations to indicate the end of a long running conversation. The following tagged values can be defined within the context of this component:

  • andromda_seam_conversation_end_ifoutcome - can have multiple values
  • andromda_seam_conversation_end_evenifexception
  • andromda_seam_conversation_end_beforeredirect

jBPM Tasks and Processes

Refer to seam profile for docs on stereotypes/tags for jBPM tasks/processes.

Unwrap Stereotype

The stereotype <<Unwrap>> can be modeled on attributes but is rendered on getter method of bean components.

Next

To read about the test framework using TestNG and JBoss Embeddable microcontainer, click here.