Projects:Seam/Developers Manual
Contents |
Introduction
This developers manual contains a detailed description on how to use the Openbravo Seam integration module. The description starts with discussing the example application included in the module and then dives into more detail describing how the EntityManager configuration is done.
Related Seam Modules
The base Seam module provides the backend integration of Seam with Openbravo. It does not provide user interface (jsf) or other parts. There are two related modules which can be installed for additional Seam functionality:
- Seam Richfaces provides JSF and Richfaces
- Seam Test provides the Seam test environment
Openbravo Version and Install Tips
This module makes use of specific Openbravo api's which are only available in the Openbravo releases after the 20th September 2009 (Openbravo 2.50MP7).
Before installing this module or when installing other modules after the Seam module has been installed set the 'reloadable' attribute in the Tomcat server.xml to false. If you have reloadable to true then tomcat will restart during installing modules. If you accidentally have left this attribute to true then execute the following command in the Openbravo install: ant smartbuild
If you are working with Eclipse then the development project needs to be refreshed after the install/smartbuild (right-click on the project and select refresh).
Example Application
The example application in the module is a relatively simple app which allows a user to login into the application and then view all the records for a certain Entity. By clicking on a record its details can be viewed. The user can also switch role and then view other entities (to which the role has access).
To access the example app, go to the following link after installing the module and restarting the application: http://localhost:8080/openbravo/web/seammodule/page/show-entities.xhtml, and then login with your Openbravo user name and password (Openbravo/openbravo for a standard installation of Openbravo).
The example application consists of the following main classes:
- ShowEntity: this is the backing bean for the show-entities.xhtml file. It keeps track of the selected record to show in the detail view and creates the OBExtendedDataModel.
- OBExtendedDataModel: is the backing bean for the extended data table showing the instances, supports loading of pages of data and computes the rowcount.
EntityManager
Openbravo and Seam have a distinctly different way of handling sessions/entity managers:
- Openbravo: uses the Hibernate Session and a session-in-view transaction/session pattern
- Seam: uses the EntityManager and a conversation managed transaction/session pattern
The Seam integration module ensures that these concepts are completely integrated. This is done by replacing (at runtime) two key classes in Openbravo with Openbravo Seam variants:
- the standard Openbravo SessionFactoryController is replaced by the EntityManagerFactoryController
- the SessionHandler instance is replaced by the SeamSessionHandler instance
This 'replacing' is done through the Application-Scoped PersistenceInitializer component. The EntityManagerFactoryController is responsible for creating EntityManagers. It uses the same mapping information as standard Openbravo. The SeamSessionHandler uses an EntityManager provided by Seam. The EntityManager is in fact a wrapper around the Hibernate Session. As Openbravo uses the standard Session, the Session encapsulated by the EntityManager is used. This makes sure that the Openbravo core code and the code running in Seam make use of the same instances and the same first and second level caches and other Hibernate concepts.
Openbravo session-in-view pattern remains intact and working but it detects if a Session was created as part of a Seam conversation or directly in Openbravo. In the latter case the session-in-view pattern will operate as it is now, if the Session is created as part of a Seam conversation then the session-in-view pattern will disable itself (for that Session).
OBDataProvider
The org.openbravo.base.seam.persistence.OBDataProvider class provides methods to query for Openbravo objects, count them and do direct find/get calls. The methods are simple and can be used as an example for the implementation of a custom class providing more advanced features.
The OBDataProvider shows how to make use of the 'readable-organization-in-clause' and 'readable-client-in-clause' method provided by the OBDal class.
OBUserContext and OBAuthenticator
Two components provide an integration with the Openbravo OBContext class. The OBContext class is the entrance point to access user information (current logged in user, the organization, role, client, etc.). The OBUserContext component (component name: obUserContext) is a simple Session-Scoped component which provides access to the OBContext. In addition the OBUserContext component has some extra convenience methods.
The OBAuthenticator is really more an example component. It shows how to write a component which authenticates against the Openbravo user database.
Seam configuration and initialization
The Openbravo integration components are initialized through the components.xml included in the module. The module also has a pages.xml file which contains the login page definition and the conversation begin statements. In addition the module has a faces config file to set a view-handler and a file to define a webservice (not used/implemented at the moment).
Note that in the web.xml the Seam filter only filters for *.xhtml files so not for all requests. Seam can not be used for .html requests as Seam interferes with Openbravo multi-part requests.
Not used/Work in Progress
The classes in the org.openbravo.base.seam.remote and org.openbravo.base.seam.test packages are work-in-progress and should be ignored.
Logging: log4j.xml
Note the Openbravo Seam module has a log4j.xml file in the root of the src directory. This can interfere with log4j.xml files located in other src directories.
Running Seam Tests
The Seam Test module makes it easy to create test cases which run in a Seam context.
After installing the module do the following:
- add the modules/org.openbravo.base.seam.test/src-test folder as a source folder to the project, right click on the folder and then build-path > Use as Source Folder.
- add all the jar files in modules/org.openbravo.base.seam.test/lib/test to the project, right-click on the project, select project properties, then Java Build Path and the libraries tab
Seam Test uses testng for testing, to run Seam tests directly from Eclipse install the testng eclipse plugin.
To create custom tests extend the OBBaseSeamTest class.
To test that the Seam Test environment is correctly set up you can run the TestEnvironmentTest test which can be found in the src-test folder.
Troubleshooting
When you run tests and you get this exception:
Caused by: java.lang.ClassNotFoundException: [Ljava.lang.Class; at java.net.URLClassLoader$1.run(Unknown Source) at java.security.AccessController.doPrivileged(Native Method) at java.net.URLClassLoader.findClass(Unknown Source) at java.lang.ClassLoader.loadClass(Unknown Source)
then add the following jvm argument to the run configuration or java call:
-Dsun.lang.ClassLoader.allowArraySyntax=true
See here for a post on this topic.