NexOpen Framework - Reference Documentation

scarcehoseΛογισμικό & κατασκευή λογ/κού

14 Ιουλ 2012 (πριν από 4 χρόνια και 11 μήνες)

1.697 εμφανίσεις

NexOpen Framework - Reference Documentation
A guide for JEE developers
0.4.0
Marc Baiges,Toni López and Francesc Xavier Magdaleno
Copyright ©2006,2007 NexOpen Team
Copies of this document may be made for your own use and for distribution to others,provided that you do not
charge any fee for such copies and further provided that each copy contains this Copyright Notice,whether dis-
tributed in print or electronically.
Table of Contents
I.Core Modules................................................................................................................................1
1.NexOpen as a Component Framework....................................................................................3
1.1.Main concepts about Components...............................................................................3
1.2.Hierarchy of Components in NexOpen........................................................................3
1.3.NexOpen Components in JEE Applications.................................................................4
2.Configuration of NexOpen projects........................................................................................5
2.1.The EAR File.............................................................................................................5
2.2.The EJB-JAR 2.x File.................................................................................................5
2.3.The Business File.......................................................................................................6
2.4.The WAR File...........................................................................................................6
2.5.NexOpen and Maven2................................................................................................7
2.5.1.Maven2 configuration......................................................................................7
2.5.2.NexOpen Maven2 Archetypes..........................................................................8
2.6.Deployment...............................................................................................................9
2.6.1.Tomcat 5.0.x,5.5.x and 6.0.x...........................................................................9
2.6.2.JBoss 4.0.x....................................................................................................11
2.6.3.JBoss 4.2.x....................................................................................................11
2.6.4.Bea WebLogic 9.2.x......................................................................................12
3.Attribute Contexts Support..................................................................................................14
3.1.Contexts Framework................................................................................................14
3.2.How to provide a customContext..............................................................................14
3.3.Configuration...........................................................................................................15
4.Events and listeners in NexOpen..........................................................................................16
4.1.Bootstrap events and listeners...................................................................................16
4.2.Event dispacthing.....................................................................................................16
4.3.Configuration...........................................................................................................16
5.Resources Support..............................................................................................................18
5.1.Pooling support for components................................................................................18
5.1.1.Configuration................................................................................................18
II.Business Tier.............................................................................................................................20
6.Service Components...........................................................................................................21
6.1.Business Services.....................................................................................................21
6.1.1.Business Facades...........................................................................................22
6.1.2.Application Services......................................................................................23
6.2.Configurable Business Services.................................................................................24
6.2.1.Dependency of other services.........................................................................25
6.3.Addition of customAOP interceptors........................................................................26
6.4.Injection of components............................................................................................27
6.5.Caching in components.............................................................................................28
6.6.Enhacement Phase....................................................................................................29
6.7.Transactionality in ServiceComponents.....................................................................30
6.8.Authorization in Business Components......................................................................32
6.9.Configuration...........................................................................................................32
7.Service Gateway.................................................................................................................34
7.1.Invokers..................................................................................................................34
7.1.1.Configuration of Invokers..............................................................................35
7.1.2.EJB configuration..........................................................................................35
8.Logging and Auditing in NexOpen.......................................................................................37
NexOpen 0.4.0 ii
8.1.Introduction.............................................................................................................37
8.2.Traditional integration with a RDBMS......................................................................38
8.3.Integration with Oracle FGA.....................................................................................38
8.4.How to extend it to accomodate to your functionalities...............................................38
8.5.Configuration...........................................................................................................38
9.Scheduling in NexOpen.......................................................................................................39
9.1.Introduction.............................................................................................................39
9.2.Using OpenSymphony Quartz Provider.....................................................................39
9.3.Using the CommonJ Provider...................................................................................39
9.4.Configuration of Scheduling Module.........................................................................40
10.Workflow.........................................................................................................................41
10.1.Main concepts........................................................................................................41
10.2.JBoss jBPMintegration..........................................................................................41
10.3.Configuration.........................................................................................................45
10.4.How to Enhace an Entity with a Workflow Process..................................................48
10.5.WorkFlow Annotations...........................................................................................49
10.5.1.Process Definition.......................................................................................49
10.5.2.Process Definitions......................................................................................50
10.5.3.CreateProcess..............................................................................................50
10.5.4.BeginTask...................................................................................................50
10.5.5.ProcessContext............................................................................................51
10.5.6.Transition....................................................................................................51
10.5.7.EndTask......................................................................................................51
11.NexOpen as a Test-Design Driven Framework....................................................................52
11.1.Test support for Service Components using JUnit3...................................................52
11.2.Support for JUnit4..................................................................................................52
12.Web Services Reference....................................................................................................53
12.1.Introduction...........................................................................................................53
12.2.NexOpen and JAX-WS 2.0.....................................................................................53
12.3.XFire 1.2.x integration............................................................................................54
12.4.Test Support..........................................................................................................55
12.5.Configuration.........................................................................................................55
III.Resource Tier...........................................................................................................................57
13.Persistence Manager..........................................................................................................58
13.1.PersistenceManager API.........................................................................................58
13.2.Query API.............................................................................................................60
13.3.Criteria API...........................................................................................................61
13.4.Integration with Hibernate3.....................................................................................62
13.5.Integration with Java Persistence API (JPA).............................................................62
13.6.Integration with EJB3 POJO Validation...................................................................62
13.7.ServiceComponents and common CRUD operations.................................................63
13.8.Test support for Persistence Module........................................................................64
13.9.Configuration of Persistence Module.......................................................................66
14.Asynchronous Tasks.........................................................................................................68
14.1.Main concepts........................................................................................................68
14.2.J2SE Concurrent integration....................................................................................68
14.3.JMS POJO integration............................................................................................68
14.4.Message-Driven Beans 2.x integration.....................................................................69
14.5.Configuration of Tasks Module...............................................................................70
IV.The Web..................................................................................................................................71
15.MVC support in NexOpen.................................................................................................72
15.1.Spring MVC support..............................................................................................72
NexOpen Framework - Reference Documentation
NexOpen 0.4.0 iii
15.2.Struts 1.2.x support.................................................................................................73
15.2.1.Configuration..............................................................................................74
15.3.Struts 2.0.x support.................................................................................................74
15.3.1.Configuration..............................................................................................75
16.Pagination support............................................................................................................77
16.1.ValueList integration..............................................................................................77
16.1.1.ValueList Supported Adapters......................................................................78
16.1.2.Configuration..............................................................................................78
17.AJAX support...................................................................................................................80
17.1.DWR integration....................................................................................................80
17.1.1.Configuration..............................................................................................80
17.2.Simple AJAX calls.................................................................................................82
17.3.Reverse AJAX calls................................................................................................83
17.4.Extended features...................................................................................................85
17.4.1.Autocomplete Tag.......................................................................................85
18.JavaServer Faces (JSF)......................................................................................................86
18.1.NexOpen and JavaServer Faces integration..............................................................86
19.Acegi Security Integration.................................................................................................87
19.1.Introduction...........................................................................................................87
19.2.Relational Database Support...................................................................................87
19.2.1.User-Group-Role model...............................................................................87
19.2.2.General Configuration.................................................................................87
19.2.3.PersistenceManager support.........................................................................90
19.2.4.JPA EntityManager support..........................................................................91
19.2.5.Integration with externals Security models....................................................92
19.3.LDAP Support.......................................................................................................94
19.4.Siteminder Support.................................................................................................94
19.5.OpenID Support.....................................................................................................95
19.6.Different login pages.MultiModule Acegi integration..............................................95
20.Web Services....................................................................................................................98
20.1.Introduction...........................................................................................................98
20.2.NexOpen and XFire integration...............................................................................98
20.3.NexOpen and CXF integration................................................................................98
20.4.NexOpen and Axis2 integration...............................................................................98
20.5.Configuration.........................................................................................................98
21.Signature Module............................................................................................................100
21.1.Introduction.........................................................................................................100
21.2.Apache Signature implementation.........................................................................100
21.3.JSR-105 implementation.......................................................................................100
21.4.Configuration.......................................................................................................100
22.Serialization Module.......................................................................................................101
22.1.Introduction.........................................................................................................101
22.2.Marshaller implementation location in cient side....................................................101
22.3.XStreamimplementation......................................................................................101
22.3.1.Extension of XStreamfunctionalities..........................................................102
22.3.2.Configuration............................................................................................102
22.4.XMLBeans implementation..................................................................................103
22.5.XServices............................................................................................................103
22.6.NexOpen and JAXB2...........................................................................................103
V.Sample applications.................................................................................................................104
23.Simple application..........................................................................................................105
23.1.Introduction.........................................................................................................105
NexOpen Framework - Reference Documentation
NexOpen 0.4.0 iv
23.2.Simple and the business and resource layer............................................................105
23.3.Simple and the presentation layer..........................................................................105
23.4.Build and deployment...........................................................................................105
A.Instrumentation Phase..............................................................................................................106
A.1.Introduction..................................................................................................................106
A.2.Configuration................................................................................................................106
A.3.Configuration in JEE 5.0................................................................................................106
A.4.Frequently Asked Questions...........................................................................................107
B.Exception Handling..................................................................................................................109
B.1.Introduction..................................................................................................................109
B.2.Exception Handling in Business Components..................................................................109
B.3.Exception Handling in WEB..........................................................................................110
NexOpen Framework - Reference Documentation
NexOpen 0.4.0 v
Part I.Core Modules
This initial part of the reference documentation covers all core modules that are absolutely integral to the Nex-
Open Framework.NexOpen Framework is based in Spring Framework 2 and tries to be beneficied of the
Spring philosophy of how to easily develop a JEE project.
Foremost amongst these is the NexOpen Framework's Inversion of Control (IoC) container.A thorough treat-
ment of the Spring Framework's IoC container is closely followed by comprehensive coverage of Spring's As-
pect-Oriented Programming (AOP) technologies.The Spring Framework has its own AOP framework,which is
conceptually easy to understand,and which successfully addresses the 80%sweet spot of AOP requirements in
Java enterprise programming.
Spring also provides an integration with AspectJ (currently the richest - in terms of features - and certainly most
mature AOP implementation in the Java enterprise space).Nevertheless,we have enough for our features with
AOP Alliance
Finally,the adoption of the test-driven-development (TDD) approach to software development is certainly ad-
vocated by the NexOpen team,and so coverage of Spring's support for integration testing is covered (alongside
best practices for unit testing).The NexOpen team have found that the correct use of IoC certainly does make
both unit and integration testing easier (in that the presence of setter methods and appropriate constructors on
classes makes them easier to wire together on a test without having to set up service locator registries and such-
like)...the chapter dedicated solely to testing will hopefully convince you of this as well.
In teh following picture,we would like to introduce a typical structure of a NexOpen project enterprise as is
shown in figure Figure 1
Figure 1.NexOpen typical architecture
Here,we can appreciate the existence of a presentation layer (in the case of figure implemented by Spring
MVC),a service gateway (represented by a EJB 2 Session Bean Stateless as we will mention in the Service
Gateway Section) where it dwells the service components and finally,a reosurce layer represented by our Per-
sistence Manager
1
NexOpen as a Component Framework
NexOpen is based in components.A component could be defined as a object which fulfills a functionality in-
side the application.Examples of components could be Service Componets,Engines or Managed Components
(objects that could be easily managed thru a JMX console for instance).
1.1.Main concepts about Components
NexOpen is a JEE Framework based in components and organized in modules for easy distribution.Therefore,
you do not need all features of Nexopen for your application.You only choose the most suitables for your ap-
plication and skip the rest.In the following picture,we try to explain the NexOpen Nature like a jigsaw,where
you put the components more suitable for your application.
Figure 1.1.NexOpen as a component framework
Therefore,as you have seen,NexOpen besides to have integration with other Open Sources projects and
Frameworks provides several good practices such as profiling,stress-loading and Martin Fowler's Continous
Integration.
1.2.Hierarchy of Components in NexOpen
NexOpen 0.4.0 3
The main interface which fulfills the concept of component is obviously Component as you have guessed.From
this class,we can observe a rich and complex inheritance such as Managed Components,Engines,Service
Components and so on.
1.3.NexOpen Components in JEE Applications
In JEE applications which uses NexOpen as their framework of development,we can observe the presence of
the following components
• Controllers.Represents the flow control in the presentation layer.There are optional,if you use JSF as your
view Framework.
• Business POJOs.The Business Services Objects in NexOpen are just POJOs annotated.The great benefit
for any developer is to hidden complexities such as configuration,environment where are managed (such a
EJB container,EJB3 container or IoC container) and freedom to choice where you would lik to deploy (due
the fact that are JEE-agnostic we can deploy in a J2EE 1.4 or even 1.3 Application Server or in a JEE 5.0
Applicaion Server).
• Entities.The EJB 3.0 (JSR-220) has introduced the concept of POJO entities which are annotated thru JSR-
175 metadata annotations.In this way,we skip the complexity of deployment descriptors,tedious applica-
tion server configuration and other features which was too misleading for J2EE developers of Entity Beans
2.x.
NexOpen as a Component Framework
NexOpen 0.4.0 4
2
Configuration of NexOpen projects
NexOpen is a high-configurable JEE Framework based in Spring2 which is suitable for EAR projects (when the
High Availability,scalability,performance or other systemic qualities are important Non Functional Require-
ments to be fulfilled),simple WAR projects or Business Components projects (JAR projects which follows the
generic principles of Service Oriented Architecture).Independently we have choosen,we must ensure to con-
figure properly our JEE project.Next secti
2.1.The EAR File
Here,we can find several modules (WEB,EJB-JAR,RAR,Client or Application Server specific) which could
be included in the functionalities of our application.
ear
|+META-INF
|+application.xml
....
The application.xml is an standard Deployment Descriptor (aka DD) where we define the modules presents in
our projet.It also coul be present specific DD related to JEE Application Servers.
2.2.The EJB-JAR 2.x File
The ejbapp is the way that is packaged in a typical NexOpen application.It contains the Sun Deployment
Descriptors (ejb-jar.xml) and Spring configuration files
ejbapp
|+beanRefContext.xml
|+hibernate.cfg.xml
|+META-INF
|+spring
|+nexopen-dataAccessContext.xml
|+nexopen-modulesConfigurer.xml
|+ejb-jar.xml
The beanRefContext.xml file represents the main file where we configure all the business tier in NexOpen
projects.Mainly it defines the Spring configuration files related to access to a persistence storage,definition of
messaging and already defined files contained in the NexOpen JAR files.In the ejb-jar.xml file,it contains the
definition of the ServiceGatewayBean,and EJB which represents a Gateway [Fowler2002] to the Business lay-
NexOpen 0.4.0 5
er.An example of beanRefContext is as follows
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:components="http://www.nexopen.org/schema/components"
xsi:schemaLocation="....">
<bean id="nexopen"
class="org.nexopenframework.deployment.context.AnnotationApplicationContext">
<!-- information about project -->
<components:module name="test001War"ejbModule="false"ejb3Module="false"
description="test001War application,which uses NexOpen Framework"/>
......
Look at the NexOpen implementation of ApplicationContext for dealing with custom or standard JSR-175
metadata (such as the JSR-250 metadata that you can define inside the NexOpen components) and the element
components:module which provides information to the runtime Nexopen container (extension of Spring),such
as if the projet does or does not support EJB module or even EJB3 mdoule,module name and a short descrip-
tion.
2.3.The Business File
Usually,the business logic is packaged in a Java JAR file,where you can find all the business objects,model
objects of your application.
business
|+META-INF
|+spring
|+production//folder for configuration related to environment production
|+integration//folder for coniguration related to environment integration
|+openfrwk-module-beans.xml//optional file
|+nexopen.properties
Moreover,if you need to configure some beans in your application,you can add in Spring configuration files
which suffix -beans.xml and explicitely located under META-INF/spring folder.
The importance of nexopen.properties
The nexopen.properties file,it is an empty file which is necessary to load all the classes which are available in
your business JAR.The Scanner class,has the responsability of load classes of a business JAR and pass to a
list of ComponentDefinitionRegistry in order to register into Spring ApplicationContext.
However,the artifact that you are creating in development is completely different from production,usually de-
tails such as RDBMS,Application Server and so on distant fromone environment to other.This could be easily
solved using the Profiles which are well integrated in Maven2.
2.4.The WAR File
Here,we can find the static and dynamic content of your application.The dynamic part,it is formed by control-
Configuration of NexOpen projects
NexOpen 0.4.0 6
lers,such as Struts 1.x,Struts 2.0.x or Spring MVC controllers.Moreover,configuration files for web layer
(views,exception hanlding,value list pagination and so on) are also included.
webapp
|+css
|+img
|+js
|+WEB-INF
|+web.xml
|+applicationContext.xml
|+nexopen-servlet.xml
|+openfrwk-module-controllers.xml//optional file
|+openfrwk-module-eventsDispatcher.xml
The configuration files in the WEB layer applying to controllers and bootstrapping of application.In the De-
ployment Descriptor we must configure the Spring DispatchServlet and the ServletContext listener needed
or bootstrapping the application.
<?xml version="1.0"encoding="UTF-8"?>
<web-app version="2.4"xmlns="http://java.sun.com/xml/ns/j2ee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee....">
.....
<servlet>
<servlet-name>nexopen</servlet-name>
<servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
....
<listener>
<listener-class>org.nexopenframework.web.context.ContextLoaderListener</listener-class>
</listener>
......
Besides,we should mention the presence of the Spring configuration files applicationContext.xml and nexopen-
servlet.xml which contains information for the WEB tier.
2.5.NexOpen and Maven2
NexOpen team recommends highly use of Maven2 as your project modelling tool.Maven2 is a tool for man-
aging the entire build process of a project (including compilation,bytecode instrumentation,running tests and
others).
Dependencies that your application has only need to be uniquely specified in the projects pom.xml configura-
tion files using a groupId,artifactId and version.Before the artifact is needed,a local caching repository as
well as remote organizational repositories and the standard ibiblio.com repositories are searched.If the artifact
is found on a remote repository it is downloaded to local cache and provided to project.As weel as the artifact
you requested,any additional transiive dependencies that are needed by teh requested artifact are also down-
loaded.
2.5.1.Maven2 configuration
Configuration of NexOpen projects
NexOpen 0.4.0 7
In order to properly download the NexOpen modules,you must be sure to include in your pom.xml the follow-
ing repository
<repositories>
......
<repository>
<id>nexopen-plugin-releases</id>
<name>NexOpen repository for Maven2</name>
<url>http://www.nexopen.org/artifactory/repo</url>
</repository>
</repositories>
.....
2.5.2.NexOpen Maven2 Archetypes
Maven2 introduces the concept of Archetype.In short,Archetype is a Maven project templating toolkit.An ar-
chetype is defined as an original pattern or model from which all other things of the same kind are made.The
names fits as we are trying to provide a system that provides a consistent means of generating Maven projects.
Archetype will help authors create Maven project templates for users,and provides users with the means to
generate parameterized versions of those project templates (see also the following address ht-
tp://maven.apache.org/guides/introduction/introduction-to-archetypes.html for more details about archetypes).
NexOpen provides several archetypes for easy-building completely configured projects in J2EE 1.4 and we also
plan to provide archetypes for JEE 5.0 development.We provide EAR,WAR and reusable Business Compon-
ents archetypes for easy startup without worrying about previous mentioned configuration.
In the next example,we show an easy example of generation of a EAR project using Maven2 comamnd line
mvn archetype:create -DarchetypeGroupId=org.nexopenframework.plugins
-DarchetypeArtifactId=openfrwk-archetype-application -DarchetypeVersion=2.0.0
-DgroupId=<my-group-id> -DartifactId=<my-artifact-id>
After execution of archetype,it has been created the next structure,full complaint with Maven2 structures
example
|+business
|+src
|+main
|+java//business logic java files
|+resources
|+test
|+java//JUnit Test java files
|+resources
|+pom.xml
|+ear
|+src
|+main
|+resources//specific deployment descriptors of JEE Application Servers
|+pom.xml
|+ejb
|+src
|+main
Configuration of NexOpen projects
NexOpen 0.4.0 8
|+resources//deployment descriptor and configuration files (Spring,Hibernate,...)
|+pom.xml
|+web
|+src
|+main
|+test
|+pom.xml
|+.classpath
|+.project
|+pom.xml
This generated project is also a configured Eclipse project and could be easily exported into any Eclipse IDE (it
could be great that this Eclipse includes the plugin for Maven2 from http://m2eclipse.codehaus.org/).This
structure is necessary to be completely understood by Maven2.Notice that Spring,Hibernate3 and other con-
figuration files are generated by archetype for easy startup.
Shall we use always Maven2?
NexOpen Teamencourages to developers to use Maven2 for development of projects,because it will efficiently
handle the dependencies of your poject,controls the lifecycle of a project,it incoporates automatically several
common goals of projects (test suites,check style,..).Nevertheless,you can create a NexOpen project without
Maven2 (using the popular ANT for instance) but you should manually add the NexOpen jars,configure the
Spring configuration files and so on.
2.6.Deployment
NexOpen it is a JEE Framework and by its JEE nature could be easily deployed in any Application Server.
However,due the fat of great variety of choices,we have centered into the following options,mainly due their
popularity among developers
2.6.1.Tomcat 5.0.x,5.5.x and 6.0.x
NexOpen is certificated to be compliant with this popular Web Container for staisfaction of Tomcat fans.
However,it is important to notice to be aware with the choice of your Spring PlatformTransactionManager
because Tomcat does not provide any implementation of JTA/JTS (this definition is located into the nexopen-
dataAccessContext.xml file of your business module under folder META-INF/spring).
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="....">
<!-- ========================= RESOURCE DEFINITIONS ========================= -->
<!-- The JTA Spring Transaction Manager implementation -->
<bean id="transactionManager"class="org.springframework.orm.hibernate3.HibernateTransactionManager">
<description>JTA Spring Transaction Manager implementation</description>
<!--
avoid retrieve javax.transaction.UserTransaction
in a EJB CMT environment,otherwise turn on
(for example in a pure web application,only one web module)
-->
<!-- IMPORTANT NOTE:this property does not work with spring version 2.0.3 -->
<!--property name="userTransactionName"><null/></property-->
<property name="sessionFactory"ref="openfrwk.sessionFactory"/>
</bean>
Configuration of NexOpen projects
NexOpen 0.4.0 9
.......
Moreover,you must include a file called context.xml under META-INF folder for properly deployment of your
application into your Tomcat environment
example
|+business
.....
|+web
|+src
|+main
|+webapp
|+META-INF
|+context.xml//Tomcat deployment descriptor
|+WEB-INF
|+web.xml//Sun web Deployment Descriptor
....
|+.classpath
|+.project
|+pom.xml
There you can specify Tomcat properties and define Connection Pooling configuration for your application.
Notice that some differences appears between resource connection pooling definition in Tomcat 5.0.x versions
and Tomcat 5.5.x and higher (see Tomcat documentation for more details)
....
<Context path="/example"docBase="example.war"
debug="2"privileged="true"crossContext="false">
<!-- logging support for example -->
<Logger className="org.apache.catalina.logger.FileLogger"
prefix="localhost_example_log."suffix=".log"
timestamp="true"/>
<!-- definition for Tomcat 5.0.x -->
<!--Resource name="jdbc/exampleDS"auth="Container"
type="javax.sql.DataSource"
description="Employees Database for Example Applications"/>
<ResourceParams name="jdbc/exampleDS">
<parameter>
<name>driverClassName</name>
<value>com.mysql.jdbc.Driver</value>
</parameter>
<parameter>
<name>url</name>
<value>jdbc:mysql://localhost:3306/eclipse?autoReconnect=true</value>
</parameter>
<parameter>
<name>username</name>
<value>user</value>
</parameter>
<parameter>
<name>password</name>
<value>pwd</value>
</parameter>
</ResourceParams-->
<!-- definition for Tomcat 5.5.x and higher -->
<Resource name="jdbc/exampleDS"auth="Container"type="javax.sql.DataSource"
maxActive="100"maxIdle="30"maxWait="10000"
username="user"password="pwd"driverClassName="com.mysql.jdbc.Driver"
url="jdbc:mysql://localhost:3306/eclipse?autoReconnect=true"/>
Configuration of NexOpen projects
NexOpen 0.4.0 10
</Context>
2.6.2.JBoss 4.0.x
NexOpen has been certificated to be complaint with JBoss 4.0.5.ga and other minor releases.In order to satisfy
the resources depedencies of your project (such as Database connections,JMS Queues,...) you must also
provide the suitable deployment descriptors of JBoss which links these resources defined in the Environment
Naming Context (ENC,in other words resources such as javax.sql.DataSource presents into a JNDI Context
under name java:comp/env) and resources defined in the application server.Then,you would find under
META-INF folder of your EJB module the jboss.xml file and the jboss-web.xml under folder WEB-INF in your
WEB module.
example
|+business
.....
|+ear
|+src
|+main
|+resources//specific deployment descriptors of JEE Application Servers
|+pom.xml
|+ejb
|+src
|+main
|+resources
|+META-INF
|+ejb-jar.xml//Sun ejb Deployment Descriptor
|+jboss.xml//JBoss ejb Deployment Descriptor
|+pom.xml
|+web
|+src
|+main
|+webapp
|+WEB-INF
|+web.xml//Sun web Deployment Descriptor
|+jboss-web.xml//JBoss web Deployment Descriptor
....
|+.classpath
|+.project
|+pom.xml
2.6.3.JBoss 4.2.x
NexOpen has been certificated to be complaint with JBoss 4.2.x.ga.Despite the fact that it is not a full com-
plaint Java EE 5.0 Application Server,it provides several features of such specification as EJB 3.0 container.
Nevertheless,we should make some changes due to hibernate3 problems originated by a lower version of hi-
bernate-annotations present in the server classpath.Obviously,one straigh solution could be removed such de-
pendency,but could generate several errors to other applications and violates the JBoss release.Therefore,we
will try to explain the steps in order to avoid the problems presented by this lower version.First of all,we
should write the following propertie,if we want to avoid a ClassCastException,a typical example of a class-
loader problem
<hibernate-configuration>
Configuration of NexOpen projects
NexOpen 0.4.0 11
<!-- a SessionFactory instance listed as/jndi/name -->
<session-factory>
<!-- properties -->
<property name="hibernate.connection.datasource">java:comp/env/jdbc/exampleDS</property>
<!-- avoid registering of validation and search listeners due to classloader problems
in JBoss 4.2.x.ga [in classpath,we find an older version of hibernate-annotations
which incudes the validator and search listeners,now belonging to separate projects] -->
<property name="hibernate.validator.autoregister_listeners">false</property>
<property name="hibernate.search.autoregister_listeners">false</property>
<property name="hibernate.validator.apply_to_ddl">false</property>
<!-- Annotated classes -->
Moreover,we have to add into tthe pom.xml the following dependency in order to avoid a NoSuchMethodEx-
ception
<!-- this dependency is needed if you want to deploy to JBoss 4.2.0.ga -->
<!-- Hibernate validator -->
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-validator</artifactId>
<version>3.0.0.ga</version>
</dependency>
Finally and related to specific deployment descriptors of JBoss,it is same as before section JBoss 4.0.x.
2.6.4.Bea WebLogic 9.2.x
Nexopen is certified to properly deploy into a Bea WebLogic Application Server version 9.2.x.As well as
JBoss,you must add the specific Deployment Descriptors of Bea WebLogic located in the same places as
JBoss.
example
|+business
.....
|+ear
|+src
|+main
|+resources//specific deployment descriptors of JEE Application Servers
|+META-INF
|+weblogic-application.xml
|+pom.xml
|+ejb
|+src
|+main
|+resources
|+META-INF
|+ejb-jar.xml//Sun ejb Deployment Descriptor
|+weblogic-ejb-jar.xml//Bea WebLogic ejb Deployment Descriptor
|+pom.xml
|+web
|+src
|+main
|+webapp
|+WEB-INF
|+web.xml//Sun web Deployment Descriptor
|+weblogic.xml//Bea WebLogic web Deployment Descriptor
....
Configuration of NexOpen projects
NexOpen 0.4.0 12
|+.classpath
|+.project
|+pom.xml
Notice existence of a weblogic-application.xml suitable for dealing with customization of your classloader us-
ing the Filtering Classloader technique (see Bea WebLogic documentation for more details)
<?xml version="1.0"encoding="UTF-8"?>
<wls:weblogic-application
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:wls="http://www.bea.com/ns/weblogic/90"
xsi:schemaLocation="....">
<wls:application-param>
<wls:param-name>webapp.encoding.default</wls:param-name>
<wls:param-value>UTF-8</wls:param-value>
</wls:application-param>
<!--
In WebLogic 9.2 a new feature called Filtering Classloader
(documented in the WebLogic server documentation) has been implemented
-->
<wls:prefer-application-packages>
<wls:package-name>javax.jws.*</wls:package-name>
</wls:prefer-application-packages>
</wls:weblogic-application>
Configuration of NexOpen projects
NexOpen 0.4.0 13
3
Attribute Contexts Support
The way to access in a given context is a complex task when we dealing with a JEE environment.As you prob-
ably know,in a JEE application exists several contexts (javax.servlet.ServletContext,
javax.servlet.ServletRequest,javax.servlet.http.HttpSession and others) and sometimes is misleading
where to look up your attribute.So,the need for a Facade to access to an attribute to all contexts or to an specif-
ic context it is an utility that could be interesting to offer in a JEE Framework.Most modern JEE Frameworks,
for example JBoss Seam,provides this unfied way to access in a similar manner that our Framework.Neverthe-
less,our way it is more extensible that the JBoss Seamway.
It is important to note that Spring Framework has easy ways to access to almost all WEB contexts,but this uni-
fied view,as a Facade,it is not provided.So,our idea it is to integrate the Spring functionalities and allow the
possibility to extend it for other modules of Framework (such as Workflow Module,see the Workflow section
for more details) or even offer the possibility to customize to your JEE application.
3.1.Contexts Framework
We provide a unified way (using the Facade pattern) of to acces to a context or a group of contexts represented
by the class import org.nexopenframework.context.framework.Contexts
.....
import org.nexopenframework.context.framework.Contexts;
......
//access to all contexts registered
Object obj = Contexts.getAttribute("my.attribute");
//acccess to contexts with scope REQUEST
Object obj_req = Contexts.getAttribute("my.request.attribute",Contexts.REQUEST);
Note the presence of a specific method for searching for an attribute in the REQUEST context.
Context REQUEST attributes and distributed architectures
The REQUEST attributes are propagated to the EJB container and then available to the service components.
3.2.How to provide a customContext
The way to provide a customized Context it is just implementing the interface
org.nexopenframework.context.framework.Context
NexOpen 0.4.0 14
.....
import org.nexopenframework.context.framework.Context;
import org.nexopenframework.context.framework.ContextAdaptor;
.....
public class MyContext extends ContextAdaptor implements Context {
public Object getAttribute(String name) {
.......
}
public int getScope() {
return Contexts.APPLICATION;
}
}
3.3.Configuration
You must be sure that in the beanRefContext.xml to be present the following entry into the constructor argu-
ment element
<!-- NexOpen Contexts mdoule -->
<value>classpath*:META-INF/spring/openfrwk-module-contexts.xml</value>
Attribute Contexts Support
NexOpen 0.4.0 15
4
Events and listeners in NexOpen
4.1.Bootstrap events and listeners
One important feature of NexOpen is to provide a nice way to deal wih the events of Spring thru Bootstrap-
Listener
...
import org.nexopenframework.spring.context.BootstrapEvent;
import org.nexopenframework.spring.context.BootstrapListener;
...
public clas MyListener implements BootstrapListener {
public void contextDestroyed(final BootstrapEvent event) {
.......
}
public void contextInitialized(final BootstrapEvent event) {
......
}
......
}
4.2.Event dispacthing
One important feature in NexOpen is the possibility to send events easily thanks to EventDispatcher class.In
this way,you can easily create any event class type following the java onvention (extending from
java.util.EventObject) and fire it.Here,we provide an easy example of use that could be found in any Busi-
ness Service Component class.
....
import org.nexopenframework.context.event.EventDispatcher;
....
EventDispatcher.publishEvent(new NotificationEvent(data));
This is the base in the AJAX-Reverse integration,as you can see in the AJAX chapter.
4.3.Configuration
NexOpen 0.4.0 16
In order to easily configure this module,you must define a file called openfrwk-module-eventsDispatcher.xml
in the WEB tier and define a Spring bean as follows (this file also contains other bean for events but we only
center in the event dispatcher bean)
.....
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="...">
<description>Objects used to publish events</description>
<!-- ========================= RESOURCE DEFINITIONS ========================= -->
<!--
Event dispatcher class.After this is initialized by Spring
could be used in a static way forany class of the
simple application
-->
<bean id="publisher"class="org.nexopenframework.context.event.EventDispatcher">
<description>Event dispatcher for handling notifications</description>
</bean>
......
Afterwards,yo must import the above Spring configuration file in the nexopen-servlet.xml file
<!--
Spring Event support::
1.- sending notifications from any layer of your application
-->
<import resource="openfrwk-module-eventsDispatcher.xml"/>
With this,we can easily fire events for any service component and will be catched in the presentation layer.
Events and listeners in NexOpen
NexOpen 0.4.0 17
5
Resources Support
5.1.Pooling support for components
Pooling is a main characteristic of managed JEE components (such as Servlet Thread Pool,EJBs,
javax.sql.DataSource,...).One of the characteristics of Frameworks such as Spring is the possibilty to obtain
such features easily thru configuration.In NexOpen,we have choosen to offer such features in a transpaent way
or developer and we have though to hide such configuration and offer a set of metadata for easy development.
The way than we can declare that a Business ServiceComponent needs pooling support is thru a JSR-175 an-
notation
.......
import org.nexopenframework.business.annotations.BusinessService;
import org.nexopenframework.business.annotations.BusinessType;
import org.nexopenframework.business.resources.annotations.ObjectPooling;
/**
* <p>Example of use of {@link ObjectPooling} annotation</p>
*/
@ObjectPooling(minSize=2,maxWait=100,maxIdleTime=200)
@BusinessService(type=BusinessType.FACADE)
public class ObjectPoolingFacadeImpl implements ObjectPoolingFacade {
............
}
Pooling of Service Components
Pooling is a technique for performance of applications.In JEE environments where we have choosen to integ-
rate EJB ServiceGateway,this tehnique is not necessary because Application Servers offers such commodity in
a transaparent way for our applications.However,in pure WEB applications,this could be necessary if we
would like to offer a QoS (Quality of Service).Nevertheless,from NexOpen team we encourage the use of a
stress-loading test tools (using Apache JMeter for instance) for observing such performance (you mut make
tests wih and without pool support and observe the differences)
5.1.1.Configuration
In order to use this module,you must provide the following configuration file in your beanRefContext.xml
which is related to easily configuration of service components which could be benfiated from the pooling fea-
ture.
NexOpen 0.4.0 18
<!-- services for j2se 5.0 -->
<value>classpath*:META-INF/spring/openfrwk-module-services-pool-jdk15.xml</value>
Be sure,not include the file openfrwk-module-services-jdk15.xml which is the non-pool aware configuration
file for service components.
Resources Support
NexOpen 0.4.0 19
Part II.Business Tier
This part of the reference documentation is concerned with the business tier,and specifically the separation of
concerns among business components.In NexOpen Framework,we catalog between Facades and Application
Services using standard patterns for such division (GoF and Core J2EE patterns).Inside the Application Ser-
vices exist another division related to Congigurable Services that are called Serices or simplicity (Aplication
Services or Business Services that could be easily mnaged thru a JMX console for instance).
NexOpen's comprehensive transaction management support is covered in detail by the use of the facilities of
Spring Framework.This feature as well others,like exception handling,are hidden to developers by use of As-
pect Oriented Programming (AOP).
1
Service Components
In the OOSE modeling,James Rumbaugh defined a Service Component as a control component such as"repres-
ent coordination,seuqencing,transactions,and control of other objects and are often used to encapsulate con-
trol related to a specific use case".Following this definition,in NexOpen we have structured the business layer
for dealing with POJOs whih fulfills the requeriments before mentioned.Notice that these divisions also are re-
lated with notions of best practices in JEE development.
6.1.Business Services
All the business logic of an application JEE must be located into this tier.However,several mistakes and mis-
concepts could appears if a Service-Oriented architecture it is not well applied in your JEE solution.Therefore,
we should apply some sound patterns in order to easily adopt a systemic quality of manageability and extensib-
ility.
Business Services are an special kind of components inside NexOpen which fulfills the above descibed fea-
tures.The main features that are essencial to be included in these components,are transactionality,concurrency
control and exception handling.Moreover,in environments or solutions that not included EJB container,we
can offer resource pooling support.The J2SE 5.0 annotation of NexOpen which describes this component is
given as follows
@Target(TYPE) @Retention(RUNTIME)
@Documented
public @interface BusinessService {
/**
* Type of business.Mainly,there are <code>FACADE</code> based in the GoF
* Facade pattern and <code>APPLICATION</code> based in the Core J2EE pattern
* Application Services.
*/
BusinessType type() default BusinessType.FACADE;
/**
* <p>The complete name of the Component interface defining the Business
* Service Component contract.</p>
*
* <p>Only applied for implementation classes of a business service
* of type<code>FACADE</code>.In a <code>APPLICATION</code> has nonsense
* due the fact that has not client view (so,it is not necessary
* to specify a interface).</p>
*/
String componentInterface() default"";
}
As you have noticed appears a new attribute componentInterface which is special for FACADE business type.
Stateless ServiceComponents
NexOpen 0.4.0 21
It is important to note that all the ServiceComponents MUST be thread-safe and NOT have a client state associ-
ated it.Therefore,we must be aware to codify all our ServiceComponents as Stateless.Rigth now,we do not
consider to support Stateful ServiceComponents at difference form other frameworks,such as JBoss Seam,of-
fers.
Other important feature of this service components is the possibilty of using the inheritance support of Java as
typical Object Oriented language.usually,you can extend a set of Service Components from other class or
classes which provides several common methods (such as CRUD operations).
Excluded SuperClass and Business ServiceComponentEngine implementation
The ServiceComponentEngine implementation offers transactionality support,exception handling and other
features,but one important characteristic to taken into account,it is the absence of transactionality in any parent
method (usally related to getting information from the class).So,if you do not design carefully your base class
or super class,you can observe the appearence of several errors.In order to avoid that problem,we must use
the ExcludedSuperClass annotation in your superclass (see javadoc for more details).
We can adopt the following catalog refering to ServiceComponents:Business Facades,Application Services
and Configurable Services.
6.1.1.Business Facades
Business Facades classes (using the GoF pattern Facade) provides a unified interface to a group of service com-
ponents in a subsystem.This kind of classes are benefiated of several services,due the fact that are Service
Components,that the surrender container provides,such as transactionality,security,concurrent control or
pooling,in a transparent way for developer.
The way that we declare that a class it is a Business Facade is as follows (see that we assume J2SE 5.0 environ-
ment)
package org.nexopenframework.samples.example.facades;
import org.nexopenframework.business.annotations.BusinessService;
import org.nexopenframework.business.annotations.BusinessType;
/**
* <p>example using NexOpen Framework</p>
*
* <p>Example of BusinessService</p>
*
* @author <a href="mailto:yourname@yourmail.com">Name Surname</a>
* @see BusinessService
* @version 1.0
* @since 1.0
*/
@BusinessService(type = BusinessType.FACADE)
public class ExampleFacadeImpl implements ExampleFacade {
......
}
The Facades are an important entry point to the business logic module of an application.
Service Components
NexOpen 0.4.0 22
NexOpen and Exception Handling
NexOpen avoids the complexity of define exception handling methodologies for each Application.As we have
mentioned,every call to a business method is intercepted thru AOP and there in is where automatically,we deal
with the exception achieved in your component.Usually,this exception could be easily managed thru a JMX
console,where you can easily observe the exceptions arised in your application.
Moreover,you can handle the severity of a given exception (either Application or System exceptions) of a
method of your ServiceComponent,using the annotation @ExceptionHandler or @ExceptionHandlers if you
have more than one exception you would like to handle(see javadoc o such annotations for more information).
6.1.2.Application Services
Application services is based in the Core J2EE pattern [Alur2003] of same name,which mainly is based in
providing a class where the business logic of a component of domain model of your application is located.In
this way,we propouse and easy way to manage your application focusing the business logic into a simple class
(an providing easy manageability of your application).Moreover,as follows from [Alur2003] the benefits of
using Application Services can be enumerated as follows
1.Minimize business logic in Facades
2.You want to provide a coarse-grained service API over existing business-tier components and services.
3.You want to encapsulate use case-specific logic outside of individual Business Objects.
Following,we show how a POJO class could be identified as a Business Application Service
package org.nexopenframework.samples.example.services;
import org.nexopenframework.business.annotations.BusinessService;
import org.nexopenframework.business.annotations.BusinessType;
/**
* <p>example using NexOpen Framework</p>
*
* <p>Example of BusinessService</p>
*
* @author <a href="mailto:yourname@yourmail.com">Name Surname</a>
* @see BusinessService
* @version 1.0
* @since 1.0
*/
@BusinessService(type = BusinessType.APPLICATION)
public class ExampleAppService {
......
}
Here,we define the logic methods associated to a given entity or entities related to our domain model.It is
highly recommended use of Application Services in large applications.For easy applications,specially CRUD
operations the use of Application Services could not be seen as benefitious as large applications and in this case
could be skipped.So,in short and easy applications,we recommend a Facade centric solution.
Service Components
NexOpen 0.4.0 23
NexOpen and Architecture Patterns
NexOpen tries to use the best well-known practices and use of well-known patterns.The use of Facade and Ap-
plication Service is a clear response to this intention to use well-know patterns in J2EE development.
6.2.Configurable Business Services
Configurable Services (hereafter Services) are an special kind of Business Service Components that can config-
ure some properties of these component thru a JMX console.Notice that these componets,offers the possibility
to manage some properties without the need of redeploying an Application Server.
The J2SE 5.0 annotation which describes this component is the following
@Target(TYPE) @Retention(RUNTIME)
@Inherited
@Documented
public @interface Service {
/**name of the service*/
String name();
/**domain*/
String domain();
/** A description of the service*/
String description() default"Service";
/** If the service has the statistics service enabled*/
boolean statistics() default false;
/** If the service is dealing in a distributed environment*/
boolean distributable() default false;
}
Notice that services are prepared to support distributable environemnts,if you specify the attribute distributable
as true,automatically any change done in a node of your cluster is broadcasted to all nodes of such cluster.In
order to properly done this feature,you must not forget to configure the appropiate module in your beanRef-
Context.xml (see Configuration for more details)
Here,we describe an example of a configurable business service with the above mentioned annotation
package org.nexopenframework.samples.example.services;
import org.nexopenframework.core.annotations.Property;
import org.nexopenframework.services.annotations.PropertyOpType;
import org.nexopenframework.services.annotations.Service;
import org.nexopenframework.services.annotations.ServiceConfigProperty;
@Service(name="ExampleService",domain="simple.business",statistics=false,
distributable=true,description="Example Service for simple aplication")
public class ExampleService {
@ServiceConfigProperty(operation=PropertyOpType.READ_WRITE)
@Property(bean="external.sytemProperty")
/**this property could be easily configured from a JMX console*/
private String myProperty;
.....
}
Service Components
NexOpen 0.4.0 24
Notice the presence of ServiceConfigProperty as the annotation responsable to indicate which properties could
be easily configured or not and if framework should create accessors or mutators (you could not define any get-
ter and setter for this proeprty,framework during the instrumentation phase automatically creates for you the
accesors and mutators).
Initial values or properties
Sometimes,we would like to assign a default value for a property of a given service component (either business
facade,applications service or configurable service).This could be easily done,as we show in the above ex-
ample,using the annotation Property and the attribute value.If we would like to refer an already registered
Spring bean,we have to choose the bean attribute.
In this example,the property called myProperty could be easily managed in a read-write style by a JMX con-
sole,because by default,Instrumentation Phase provides getter and setter methods (in the ServiceConfigProp-
erty annotation exists an operation attribute with default value PropertyOpType.READ_WRITE and then auto-
matically creates such accessors and mutators methods).If you want to modify this default behaviour,you must
specify it in this attribute,for instance,if you plan to use only read methods in some properties you have to spe-
cify PropertyOpType.READ,and then the Class Transfomer related with Services,in the Instrumentation
Phase,will generate only accessors methods (getters) but not mutators (setters).
Services as Standard MBeans
In the instrumentation phase such components are transformed to MBeans that in the deployment of your ap-
plication are automatically registered in the Application Server MBeanServer.By default,the suitable Class
Transformer converts the Service in a Standard MBean which fulfills the requirements of the JMX 1.2.1 spe-
cification.The interface associated to this MBean is automatically created and allowed operation types proper-
ties (the getters and setters methods of conigurable properties) are present in this interface
Finally it is important to note,that inheritance is forbidden in this kind of configurable business components,
because in the Intsrumentation Phase is provided a suitable parent to deal with lifecycle methods associated to
this component.The parent class could be the specific ServiceSupport or the customized JBoss serice support
class
Lifecycle in Configurable Services
Configurable serices offers at difference from other business services a lifecyle support associated internally at
its managed nature.You can mark any method with any visibility (public,protected,package or private) with
the annotation @ServiceLifecycle speciying the operation type (CREATE,START,STOP or DESTROY).
6.2.1.Dependency of other services
Sometimes,you need to explicitely start a given service after other ones has been alredy started,because you
want to be benefitied from such services.In this case,a dependency among services.NexOpen provides a JSR-
175 metadata which fulfills these requierements,the Depends annotation.
Service Components
NexOpen 0.4.0 25
package org.nexopenframework.services.annotations;
import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;
@Target(TYPE) @Retention(RUNTIME)
@Documented
public @interface Depends {
/**
* <p>The services classes array that the annotated class depends</p>
*
* @return the services classes whihc the given service depends
*/
Class[] value();
}
The following example show you how to use it
........
@Depends({OtherService.class,AService.class})
@Service(name="easy",domain="test.example")
public class SomeService {
........
}
Therefore,the lifecycle of this service will no be executed till OtherService and AService has been completedly
started (in other words,are in the State START )
6.3.Addition of customAOP interceptors
You have the possibility of addition of custom AOP interceptors in any service component.The way to do is
thru an annotation Interceptors.If any annotation is present,in the enhacement phase,will be recovered and
searching into Spring IoC container or just created as a single instance (take into account that it is injected any
depedency in this phase,if you want to inject something,you must declare such interceptor into a Spring con-
figuration file) and added to the chain of interceptors associated to service components.
package org.nexopenframework.core.interceptors.annotations;
import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;
import org.aopalliance.aop.Advice;
@Target(TYPE) @Retention(RUNTIME)
@Inherited
public @interface Interceptors {
Service Components
NexOpen 0.4.0 26
/**
* <p>The interceptors to be added to a service component.The class must be an AOP alliance
* {@link Advice}</p>
*
* @return the interceptors class objects to be added to a given ServiceComponent
*/
Class<?extends Advice>[] value();
}
Notice the dependency with AOP Alliance,an easy to use implementation of the AOP philosophy.Following
we show an example o using this annotation
.....
@Interceptors({EasyInterceptor.class,PerformanceMonitorInterceptor.class})
@BusinessService(type=BusinessType.FACADE)
public class ExampleFacade implements ExampleFacadeIf {
@Component OtherFacadeIf other;
/* (non-Javadoc)
* @see org.nexopenframework.example.business.ExampleFacadeIf#doBusiness()
*/
public void doBusiness() {
System.out.println("ExampleFacade.doBusiness()");
}
}
Interceptors in Facades and JSR-250
One of the features of NexOpen in the current release,and in labs state,it is the possibility of to be instru-
mented as a EJB 3.0 Stateless Session Bean.One of the characteristics of this new specification,it is also the
possibility to add interceptors thru the JSR-250 annotations Interceptors.Therefore,if we would like to trans-
formthe NexOpen interceptors into JSR-250 annotations be sure that the JEE 5.0 transformers are present.
In next releases,we probably relax such dependency with AOP Alliance Advice class,in order to inrodce other
AOP Frameworks such as AspectJ which is widely supported by Spring2.
6.4.Injection of components
Usually,Service Components could depend of other components or resources.The usual way to access to these
components is thru injection using the fact that components are managed thru a IoC container (in this case
Spring Framework IoC container).NexOpen provides an annotation tha is defined as follows
package org.nexopenframework.core.annotations;
import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
import java.lang.annotation.Documented;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
Service Components
NexOpen 0.4.0 27
import java.lang.annotation.Target;
@Target({TYPE,METHOD,FIELD}) @Retention(RUNTIME)
@Documented
@Inherited
public @interface Component {
/**
*
* @return
*/
String name() default"";
/**
* <p>The type of the Service Component</p>
* @return
*/
Class<?> type() default Object.class;
}
An example of how to inject components (service components or even resources managed by any JEE applica-
tion server) is given as follows
....
import javax.annotation.Resource;
...
import org.nexopenframework.core.annotations.Component;
@BusinessService(type = BusinessType.FACADE)
public class MyFacade implements MyFacadeIf {
/**Access to a ApplicationServer component*/
@Resource javax.transaction.UserTransaction ut;
/**Access to a Component managed by Spring IoC container*/
@Component mypackage.service.MyAppService appService;
}
As we notice,there two main annotations in order to access to Components.The first one,it is a component
managed by an JEE Application Server (a JTA/JTS User Transaction implementation of such Application Serv-
er) and the second one is managed by a IoC container,such as Spring Framework.Notice that all of these com-
ponents,they will be injected during the deployment phase.
@Resource and ServiceComponents
In the first release of NexOpen,we could access to components thru the JSR-250 @javax.annotation.Resource.
Nowdays,this practice it has been deprecated and we encourage to developers to use the
@org.nexopenframework.core.annotations.Component annotation instead.The main reason is the posibility of
Facades to be instrumented as EJB 3.0 Stateless Session Beans and all the @Resoure wil be understood by the
given JEE 5.0 Application Server.
6.5.Caching in components
One important feature of ServiceComponents is the possibility of caching values in a structure Map type.A typ-
ical example could be the next one,we have a service component which uses the OCSP certificate revocation,
if we do not use cache of the response,every time we would like to know if a certificate it is revoked,we
Service Components
NexOpen 0.4.0 28
should make an HTTP invocation in order to ensure it.However,if we can ensure that during an among of time
this reponse would not change,it is not necessary to make an HTTP invocation and increasing performance of
the application.
The way that we inject a cache,it is as follows using the annotations
@org.nexopenframework.cache.annotations.Cache.Look that we are injecting a proxy which deals with a
suitable configured provider (such as EhCache or JBossCache) and hides the complexities of Cache API offer-
ing a well-known interface to operate.Features such as cache eviction,policies and others they are hidden and
could be adminsitered using a JMX console.
....
import static org.nexopenframework.cache.annotations.CacheConcurrency.NONSTRICT_READ_WRITE;
....
import java.util.Map;
import org.nexopenframework.cache.annotations.Cache;
....
public class MyAppService {
/**represents a proxy of a selected cache*/
@Cache(concurrency=NONSTRICT_READ_WRITE)
Map cache;
.....
}
In order o use this feature,we must add into our beanRefContext.xml the following entry
<!-- cache services -->
<value>classpath*:META-INF/spring/openfrwk-module-cache.xml</value>
Internally,it looks for a suitable implemnetations of org.nexopenframework.cache.providers.CacheProvider.If
no one is provided,first tries to load the EhCache provider if it is found in classpath and in negative case
provides a naive implementation based in an implementation of java.util.Map.However,you can provide your
customprovider just declaring into your business spring files
6.6.Enhacement Phase
The Enhacement Phase it is an important phase in the lifecyle of deployment of a NexOpen application,in
which all the Service Components,presents in the Spring IoC container,will be enhaced thru the addition of
fixed and custom AOP interceptors.The fixed interceptors deals with transactionality support,exception hand-
ling and performance monitoring.Therefore,this components will be translated to proxies which can deal in a
transparent way with features that could be tought to developers.
Auto-detection of ServiceComponents
One main feature of NexOpen is absence or at least to minimize XML configuration.So,all the ServiceCom-
poents of your application could be not defined in any Spring XML configuration file and it will be detected by
the suitable implementations of ComponentDefintionRegistry at bootstrap (see javadoc for more information).
It is important to note that in the current release,we only support addition of AOP Alliance interceptors.
Service Components
NexOpen 0.4.0 29
6.7.Transactionality in ServiceComponents
Transactionality in ServiceComponents is managed internally by framework thru AOP which intercepts a call
and pass the invocation to ServiceComponentEngine.This is an internal component of NexOpen which guaran-
tees to execute the invoked methods in a transactional environment thanks to Spring Transactional module.In-
ternally this engine has an ordered list of Spring TransactionAttributeSource implementations
• AnnotationTransactionAttributeSource.Spring implementation which checks existence of Spring annota-
tion Transactional.
• EJB3AnnotationTransactionAttributeSource.NexOpen implementation which checks existence of JEE 5.0
annotation TransactionAttribute.
• NameMatchTransactionAttributeSource.Spring implementation whcih checks matching wwith the method
name of your Business Service Component.
The name matches,of this last TransactionAttributeSource option,are the following (as it is carried into the
services spring configuration files).Therefore,if your method begins with one of this name,you can not declare
any specific annotation for dealing with tx behaviour
......
<bean id="nameMatchAttributeSource"
class="org.springframework.transaction.interceptor.NameMatchTransactionAttributeSource">
<description>Name Match attribute source</description>
<property name="properties">
<props>
<prop key="get*">PROPAGATION_SUPPORTS,readOnly</prop>
<prop key="find*">PROPAGATION_SUPPORTS,readOnly</prop>
<prop key="exits*">PROPAGATION_SUPPORTS,readOnly</prop>
<prop key="retrieve*">PROPAGATION_SUPPORTS,readOnly</prop>
<prop key="query*">PROPAGATION_SUPPORTS,readOnly</prop>
<prop key="update*">PROPAGATION_REQUIRED</prop>
<prop key="store*">PROPAGATION_REQUIRED</prop>
<prop key="handle*">PROPAGATION_REQUIRED</prop>
<prop key="save*">PROPAGATION_REQUIRED</prop>
<prop key="insert*">PROPAGATION_REQUIRED</prop>
<prop key="create*">PROPAGATION_REQUIRED</prop>
<prop key="persist*">PROPAGATION_REQUIRED</prop>
<prop key="set*">PROPAGATION_REQUIRED</prop>
<prop key="add*">PROPAGATION_REQUIRED</prop>
<prop key="make*">PROPAGATION_REQUIRED</prop>
<prop key="delete*">PROPAGATION_REQUIRED</prop>
<prop key="remove*">PROPAGATION_REQUIRED</prop>
<prop key="erase*">PROPAGATION_REQUIRED</prop>
<prop key="execute*">PROPAGATION_REQUIRED</prop>
</props>
</property>
</bean>
......
Following caption,shows examples of the before mentioned mechanisms of transactionality
/**
* this method will be executed in a tx environment due the fact of matching
* with internal rules
*/
public void createPerson(final Person p) {
Service Components
NexOpen 0.4.0 30
this.pm.persist(p);
}
/**
* this method will not be executed in a tx environment
*/
public void doSomeBusiness(final Person p) {
this.pm.persist(p);
}
/**
* this method will execute in a tx environment using Spring Transactional
* annotations support
*/
@org.springframework.transaction.annotation.Transactional
public void doBusiness(final Person p) {
this.pm.persist(p);
}
/**
* <p>Client customs the tx using EJB3</p>
*
*/
@javax.ejb.TransactionAttribute(javax.ejb.TransactionAttributeType.REQUIRED)
public void doOperationWithTx() {
}
As you can see,from a Name Pattern strategy to EJB 3.0 annotations specs strategy are contempled in Nex-
Open.Notice the inhered Container Managed Transaction (CMT) nature of Service Components,you only de-
clare the transaction and other will do the hard work (beyond scenes,the transactional engine interceptor com-
municates to Spring PlatormTransactionManager which finally performs the transactional operations).
However,if you would like to deal with transactionality in your Service Components,either by JTA/JTS of just
JDBC or even with a custom way,such as the interfaces offered by JPA or Hibernate3,in other words being a
Bean Managed Transaction Component (BMT),you must indicate using a JEE 5.0 annotation as follows
import javax.ejb.TransactionManagement;
import javax.ejb.TransactionManagementType;
@TransactionManagement(TransactionManagementType.BEAN)
@BusinessService(type=BusinessType.FACADE)
public class DummyBeanFacadeImpl implements DummyBeanFacade {
/**using JTA/JTS support*/
@Resource javax.transaction.UserTransaction ut;
/**Application Server managed DataSource*/
@Resource(name="jdbc/myDs") javax.sql.DataSource ds;
public void methodJdbcTx() {
//if you use this choice,you do not need
//the javax.transaction.UserTransaction object
Connection conn = null;
try {
conn = ds.getConenction();
conn.setAutomCommit(false);
//do business operations
....
conn.commit();
} finally {
//close transaction
}
}
Service Components
NexOpen 0.4.0 31
public void methodJtaTx() {
ut.begin();
//do business operations
....
ut.commit();
}
}
Internally,the ServiceComponent Engine suspends a current transaction,if any it is in process,and invokes the
method without transactionality.After the invocation of method,the Engine resumes this transaction
6.8.Authorization in Business Components
Usually,we would like to perform authorization constraints in business components.There two ways o deal
with it in NexOpen Framework,one programmatic and teh other one declarative.
The programmatic way,is to obtain n instance of Actor and perform teh operations such as obatine the current
User,or if a given role is allowed
.....
import org.nexopenframework.security.context.Actor;
.....
public void doBusinessMethod (final Map<String,Serializable> filter) {
final Actor actor = Actor.getInstance();
//retrieve the current User
final User user = actor.getCurrentUser();
....
//of perform programatic authz
if (actor.isUserInRole("ROLE_ADMIN") {
........
}
......
}
The declarative way,is to use JEE 5.0 RolesAllowed annotation.This annotation should be declared at method
level and in the specific case of Facades,it must be declared at the interface level,as follows in the given ex-
ample
...
import javax.annotation.security.RolesAllowed;
...
@RolesAllowed("ROLE_ADMIN")
void createPerson(final Person person);
....
6.9.Configuration
Service Components
NexOpen 0.4.0 32
In order to use such module you must be sure that the Spring configuration file for services it si included in
your beanRefContext.xml
<!-- services for j2se 5.0 -->
<value>classpath*:META-INF/spring/openfrwk-module-services-jdk15.xml</value>
Moreover,you must include such dependency in your pom.xml
<dependency>
<groupId>org.nexopenframework</groupId>
<artifactId>openfrwk-services-jdk15</artifactId>
<version>${nexopen.version}</version>
<exclusions>
<exclusion>
<artifactId>commonj-twm</artifactId>
<groupId>com.bea.wlplatform</groupId>
</exclusion>
<exclusion>
<artifactId>junit</artifactId>
<groupId>junit</groupId>
</exclusion>
<exclusion>
<artifactId>commons-logging</artifactId>
<groupId>commons-logging</groupId>
</exclusion>
</exclusions>
</dependency>
We should exclude such dependencies in order not to be included in the artifact (ear,war,...)
Configuration for J2SE 1.4.x
At the begining,we promote the idea to be compliants with J2EE 1.3 as well as Spring.Therefore,we started
two lines of development for services one for J2SE 1.4.x (based in open sorce project backport175,see ht-
tp://backport175.codehaus.org/for more information) and other for J2SE 5.0.Nowdays,we realize that this
could be a serious problems of management of the project and we have decided that in future releases we will
focus on J2SE 5.0 allowing the development of j2Se 1.4.x using agile solutions such as Retrotranslator (see ht-
tp://retrotranslator.sourceforge.net/for more information)
Service Components
NexOpen 0.4.0 33
2
Service Gateway
The access to the business layer from the presentation tier is thru a Service Gateway component which hides a
container (a EJB 3.0 container,a EJB 2.x container or a IoC container such as Spring Framework).
At first design of this module,NexOpen team considered the possibility of hidden calls,using AOP,thru a EJB
remote or local container.Nevertheless,we have assumed that this scenario is erroneous and does not offer
solutions to developers which would like to use web containers such as Tomcat 5.0.x or 5.5.x or Jetty 5.x or 6.x
7.1.Invokers
Invokers are a chain of implementations of ServiceGatewayInvoker which are able to communicate to a given
container.In this sense,for a developer point of view always see the same code from a client class,but the way
of how to performinvocation to business components,it is different depending the deployment configuration.
.....
public class MyController implements Controller {
/**
* Proxy which hides a call to MyFacade in a given
* container.For instance,an EJB container or a POJO container such as Spring,
* or even a EJB3 container could be examples of invoked containers.
* Expose always your applications business methods
* thru Business Facades patterns.
*/
@ServiceGatewayRef MyFacade myFacade;
......
}
The metadata ServiceGatewayRef makes possible the communication with a given container.This one,it is
defined as follows
package org.nexopenframework.core.runtime.annotations;
.....
@Target({TYPE,METHOD,FIELD}) @Retention(RUNTIME)
@Inherited
@Documented
public @interface ServiceGatewayRef {
/**the business service to be proxied*/
Class businessService() default Object.class;
/**JNDI name of the Service Gateway component*/
String jndiName() default"";
/**if must include the prefix java:comp/env to previous JNDI name*/
boolean resourceRef() default true;
/**if we use the local or remote call*/
/**This attribute has been deprecated*/
NexOpen 0.4.0 34
@Deprecated
boolean localEJB() default false;
/**additional interceptors [now support for AOP Alliance]*/
Class<?extends Advice>[] interceptors() default {};
}
Elements such as jndiName and resourceRef are necessary when we deal with communication to EJB 3.0 State-
less Session Beans.Finally,element interceptors is suitable when you would like to enhace the chain of AOP
advices to be applied to invocation of Business Facade (very useful,if you want to performauthorization mech-
anisms,for isntance)
7.1.1.Configuration of Invokers
We can configure a list of suitable invokers in the applicationContext.xml available under WEB-INF folder
....
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:jee="http://www.springframework.org/schema/jee"
xsi:schemaLocation="....">
....
<!-- ========================= RESOURCE DEFINITIONS ========================= -->
<bean id="servGatewayProcessor"
class="org.nexopenframework.deployment.processor.ServiceGatewayProcessor">
<description>
Processor which deals with service gateway references in controllers
</description>
<!-- Invokers -->
<property name="invokers">
<list>
<value>org.nexopenframework.core.runtime.invokers.EJBLocalInvoker</value>
<value>org.nexopenframework.core.runtime.invokers.EJBRemoteInvoker</value>
</list>
</property>
</bean>
....
There,we can define a list of invokers to be proceeded,when a controller or some client,which dwells in the
presentation tier,tries to invoke a service component (usually a Facade) in the business tier.
EJB Local or Remote?
Sometimes,we do not know which is the best choice when we are dealing with EJBs.Local invocation are suit-
able when you do not have a cluster environment and the EJB container and WEB container are allocated in the
same JVM.However,sometimes is desirable to have another redundance layer and EJB remotes helps to
achieve scalable solutions in High Availability (HA) applications.In NexOpen you have this freedom of