NexOpen Framework - Reference...

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 notcharge any fee for such copies and further provided that each copy contains this Copyright Notice, whether dis-

tributed in print or electronically.

Table of ContentsI. Core Modules ................................................................................................................................ 1

1. NexOpen as a Component Framework .................................................................................... 31.1. Main concepts about Components ............................................................................... 31.2. Hierarchy of Components in NexOpen ........................................................................ 31.3. NexOpen Components in JEE Applications ................................................................. 4

2. Configuration of NexOpen projects ........................................................................................ 52.1. The EAR File ............................................................................................................. 52.2. The EJB-JAR 2.x File ................................................................................................. 52.3. The Business File ....................................................................................................... 62.4. The WAR File ........................................................................................................... 62.5. NexOpen and Maven2 ................................................................................................ 7

2.5.1. Maven2 configuration ...................................................................................... 72.5.2. NexOpen Maven2 Archetypes .......................................................................... 8

2.6. Deployment ............................................................................................................... 92.6.1. Tomcat 5.0.x, 5.5.x and 6.0.x ........................................................................... 92.6.2. JBoss 4.0.x .................................................................................................... 112.6.3. JBoss 4.2.x .................................................................................................... 112.6.4. Bea WebLogic 9.2.x ...................................................................................... 12

3. Attribute Contexts Support .................................................................................................. 143.1. Contexts Framework ................................................................................................ 143.2. How to provide a custom Context .............................................................................. 143.3. Configuration ........................................................................................................... 15

4. Events and listeners in NexOpen .......................................................................................... 164.1. Bootstrap events and listeners ................................................................................... 164.2. Event dispacthing ..................................................................................................... 164.3. Configuration ........................................................................................................... 16

5. Resources Support .............................................................................................................. 185.1. Pooling support for components ................................................................................ 18

5.1.1. Configuration ................................................................................................ 18II. Business Tier ............................................................................................................................. 20

6. Service Components ........................................................................................................... 216.1. Business Services ..................................................................................................... 21

6.1.1. Business Facades ........................................................................................... 226.1.2. Application Services ...................................................................................... 23

6.2. Configurable Business Services ................................................................................. 246.2.1. Dependency of other services ......................................................................... 25

6.3. Addition of custom AOP interceptors ........................................................................ 266.4. Injection of components ............................................................................................ 276.5. Caching in components ............................................................................................. 286.6. Enhacement Phase .................................................................................................... 296.7. Transactionality in ServiceComponents ..................................................................... 306.8. Authorization in Business Components ...................................................................... 326.9. Configuration ........................................................................................................... 32

7. Service Gateway ................................................................................................................. 347.1. Invokers .................................................................................................................. 34

7.1.1. Configuration of Invokers .............................................................................. 357.1.2. EJB configuration .......................................................................................... 35

8. Logging and Auditing in NexOpen ....................................................................................... 37

NexOpen 0.4.0 ii

8.1. Introduction ............................................................................................................. 378.2. Traditional integration with a RDBMS ...................................................................... 388.3. Integration with Oracle FGA ..................................................................................... 388.4. How to extend it to accomodate to your functionalities ............................................... 388.5. Configuration ........................................................................................................... 38

9. Scheduling in NexOpen ....................................................................................................... 399.1. Introduction ............................................................................................................. 399.2. Using OpenSymphony Quartz Provider ..................................................................... 399.3. Using the CommonJ Provider ................................................................................... 399.4. Configuration of Scheduling Module ......................................................................... 40

10. Workflow ......................................................................................................................... 4110.1. Main concepts ........................................................................................................ 4110.2. JBoss jBPM integration .......................................................................................... 4110.3. Configuration ......................................................................................................... 4510.4. How to Enhace an Entity with a Workflow Process .................................................. 4810.5. WorkFlow Annotations ........................................................................................... 49

10.5.1. Process Definition ....................................................................................... 4910.5.2. Process Definitions ...................................................................................... 5010.5.3. CreateProcess .............................................................................................. 5010.5.4. BeginTask ................................................................................................... 5010.5.5. ProcessContext ............................................................................................ 5110.5.6. Transition .................................................................................................... 5110.5.7. EndTask ...................................................................................................... 51

11. NexOpen as a Test-Design Driven Framework .................................................................... 5211.1. Test support for Service Components using JUnit3 ................................................... 5211.2. Support for JUnit4 .................................................................................................. 52

12. Web Services Reference .................................................................................................... 5312.1. Introduction ........................................................................................................... 5312.2. NexOpen and JAX-WS 2.0 ..................................................................................... 5312.3. XFire 1.2.x integration ............................................................................................ 5412.4. Test Support .......................................................................................................... 5512.5. Configuration ......................................................................................................... 55

III. Resource Tier ........................................................................................................................... 5713. Persistence Manager .......................................................................................................... 58

13.1. PersistenceManager API ......................................................................................... 5813.2. Query API ............................................................................................................. 6013.3. Criteria API ........................................................................................................... 6113.4. Integration with Hibernate3 ..................................................................................... 6213.5. Integration with Java Persistence API (JPA) ............................................................. 6213.6. Integration with EJB3 POJO Validation ................................................................... 6213.7. ServiceComponents and common CRUD operations ................................................. 6313.8. Test support for Persistence Module ........................................................................ 6413.9. Configuration of Persistence Module ....................................................................... 66

14. Asynchronous Tasks ......................................................................................................... 6814.1. Main concepts ........................................................................................................ 6814.2. J2SE Concurrent integration .................................................................................... 6814.3. JMS POJO integration ............................................................................................ 6814.4. Message-Driven Beans 2.x integration ..................................................................... 6914.5. Configuration of Tasks Module ............................................................................... 70

IV. The Web .................................................................................................................................. 7115. MVC support in NexOpen ................................................................................................. 72

15.1. Spring MVC support .............................................................................................. 72


NexOpen 0.4.0 iii

15.2. Struts 1.2.x support ................................................................................................. 7315.2.1. Configuration .............................................................................................. 74

15.3. Struts 2.0.x support ................................................................................................. 7415.3.1. Configuration .............................................................................................. 75

16. Pagination support ............................................................................................................ 7716.1. ValueList integration .............................................................................................. 77

16.1.1. ValueList Supported Adapters ...................................................................... 7816.1.2. Configuration .............................................................................................. 78

17. AJAX support ................................................................................................................... 8017.1. DWR integration .................................................................................................... 80

17.1.1. Configuration .............................................................................................. 8017.2. Simple AJAX calls ................................................................................................. 8217.3. Reverse AJAX calls ................................................................................................ 8317.4. Extended features ................................................................................................... 85

17.4.1. Autocomplete Tag ....................................................................................... 8518. JavaServer Faces (JSF) ...................................................................................................... 86

18.1. NexOpen and JavaServer Faces integration .............................................................. 8619. Acegi Security Integration ................................................................................................. 87

19.1. Introduction ........................................................................................................... 8719.2. Relational Database Support ................................................................................... 87

19.2.1. User-Group-Role model ............................................................................... 8719.2.2. General Configuration ................................................................................. 8719.2.3. PersistenceManager support ......................................................................... 9019.2.4. JPA EntityManager support .......................................................................... 9119.2.5. Integration with externals Security models .................................................... 92

19.3. LDAP Support ....................................................................................................... 9419.4. Siteminder Support ................................................................................................. 9419.5. OpenID Support ..................................................................................................... 9519.6. Different login pages. MultiModule Acegi integration .............................................. 95

20. Web Services .................................................................................................................... 9820.1. Introduction ........................................................................................................... 9820.2. NexOpen and XFire integration ............................................................................... 9820.3. NexOpen and CXF integration ................................................................................ 9820.4. NexOpen and Axis2 integration ............................................................................... 9820.5. Configuration ......................................................................................................... 98

21. Signature Module ............................................................................................................ 10021.1. Introduction ......................................................................................................... 10021.2. Apache Signature implementation ......................................................................... 10021.3. JSR-105 implementation ....................................................................................... 10021.4. Configuration ....................................................................................................... 100

22. Serialization Module ....................................................................................................... 10122.1. Introduction ......................................................................................................... 10122.2. Marshaller implementation location in cient side .................................................... 10122.3. XStream implementation ...................................................................................... 101

22.3.1. Extension of XStream functionalities .......................................................... 10222.3.2. Configuration ............................................................................................ 102

22.4. XMLBeans implementation .................................................................................. 10322.5. XServices ............................................................................................................ 10322.6. NexOpen and JAXB2 ........................................................................................... 103

V. Sample applications ................................................................................................................. 10423. Simple application .......................................................................................................... 105

23.1. Introduction ......................................................................................................... 105


NexOpen 0.4.0 iv

23.2. Simple and the business and resource layer ............................................................ 10523.3. Simple and the presentation layer .......................................................................... 10523.4. Build and deployment ........................................................................................... 105

A. Instrumentation Phase .............................................................................................................. 106A.1. Introduction .................................................................................................................. 106A.2. Configuration ................................................................................................................ 106A.3. Configuration in JEE 5.0 ................................................................................................ 106A.4. Frequently Asked Questions ........................................................................................... 107

B. Exception Handling .................................................................................................................. 109B.1. Introduction .................................................................................................................. 109B.2. Exception Handling in Business Components .................................................................. 109B.3. Exception Handling in WEB .......................................................................................... 110


NexOpen 0.4.0 v

Part I. Core ModulesThis 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 theSpring 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 isconceptually easy to understand, and which successfully addresses the 80% sweet spot of AOP requirements inJava enterprise programming.

Spring also provides an integration with AspectJ (currently the richest - in terms of features - and certainly mostmature AOP implementation in the Java enterprise space). Nevertheless, we have enough for our features withAOP 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 (alongsidebest practices for unit testing). The NexOpen team have found that the correct use of IoC certainly does makeboth unit and integration testing easier (in that the presence of setter methods and appropriate constructors onclasses 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 isshown 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 SpringMVC), a service gateway (represented by a EJB 2 Session Bean Stateless as we will mention in the ServiceGateway Section) where it dwells the service components and finally, a reosurce layer represented by our Per-sistence Manager

1NexOpen 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, whereyou 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 andFrameworks provides several good practices such as profiling, stress-loading and Martin Fowler's ContinousIntegration.

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. Fromthis class, we can observe a rich and complex inheritance such as Managed Components, Engines, ServiceComponents 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 ofthe following components

• Controllers.Represents the flow control in the presentation layer. There are optional, if you use JSF as yourview Framework.

• Business POJOs. The Business Services Objects in NexOpen are just POJOs annotated. The great benefitfor any developer is to hidden complexities such as configuration, environment where are managed (such aEJB container, EJB3 container or IoC container) and freedom to choice where you would lik to deploy (duethe fact that are JEE-agnostic we can deploy in a J2EE 1.4 or even 1.3 Application Server or in a JEE 5.0Applicaion 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 Beans2.x.

NexOpen as a Component Framework

NexOpen 0.4.0 4

2Configuration of NexOpen projects

NexOpen is a high-configurable JEE Framework based in Spring2 which is suitable for EAR projects (when theHigh 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 thegeneric 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 couldbe 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 inour 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 DeploymentDescriptors (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 NexOpenprojects. Mainly it defines the Spring configuration files related to access to a persistence storage, definition ofmessaging and already defined files contained in the NexOpen JAR files. In the ejb-jar.xml file, it contains thedefinition 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">

<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-175metadata (such as the JSR-250 metadata that you can define inside the NexOpen components) and the elementcomponents:module which provides information to the runtime Nexopen container (extension of Spring), suchas 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, modelobjects 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 fileswhich 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 inyour business JAR. The Scanner class, has the responsability of load classes of a business JAR and pass to alist 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 from one environment to other. This could be easilysolved 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 neededor 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 andothers).

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 aswell as remote organizational repositories and the standard ibiblio.com repositories are searched. If the artifactis found on a remote repository it is downloaded to local cache and provided to project. As weel as the artifactyou requested, any additional transiive dependencies that are needed by teh requested artifact are also down-loaded.

2.5.1. Maven2 configuration


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 . Thenames 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 togenerate 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 alsoplan 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


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 (itcould be great that this Eclipse includes the plugin for Maven2 from http://m2eclipse.codehaus.org/). Thisstructure 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 Team encourages to developers to use Maven2 for development of projects, because it will efficientlyhandle the dependencies of your poject, controls the lifecycle of a project, it incoporates automatically severalcommon goals of projects (test suites, check style,..). Nevertheless, you can create a NexOpen project withoutMaven2 (using the popular ANT for instance) but you should manually add the NexOpen jars, configure theSpring 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 theirpopularity 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="....">

<bean id="transactionManager" class="org.springframework.orm.hibernate3.HibernateTransactionManager"><description>JTA Spring Transaction Manager implementation</description><property name="sessionFactory" ref="openfrwk.sessionFactory"/>

</bean>


NexOpen 0.4.0 9

.......

Moreover, you must include a file called context.xml under META-INF folder for properly deployment of yourapplication 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 versionsand Tomcat 5.5.x and higher (see Tomcat documentation for more details)

....<Context path="/example" docBase="example.war"

debug="2" privileged="true" crossContext="false"><Logger className="org.apache.catalina.logger.FileLogger"

prefix="localhost_example_log." suffix=".log"timestamp="true"/>

<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"/>


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 satisfythe resources depedencies of your project (such as Database connections, JMS Queues,...) you must alsoprovide the suitable deployment descriptors of JBoss which links these resources defined in the EnvironmentNaming Context (ENC, in other words resources such as javax.sql.DataSource presents into a JNDI Contextunder name java:comp/env) and resources defined in the application server. Then, you would find underMETA-INF folder of your EJB module the jboss.xml file and the jboss-web.xml under folder WEB-INF in yourWEB module.


|+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, wewill try to explain the steps in order to avoid the problems presented by this lower version. First of all, weshould write the following propertie, if we want to avoid a ClassCastException, a typical example of a class-loader problem

<hibernate-configuration>


NexOpen 0.4.0 11

<session-factory><property name="hibernate.connection.datasource">java:comp/env/jdbc/exampleDS</property>

<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>

Moreover, we have to add into tthe pom.xml the following dependency in order to avoid a NoSuchMethodEx-

ception

<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 asJBoss, you must add the specific Deployment Descriptors of Bea WebLogic located in the same places asJBoss.


|+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

....


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-applicationxmlns: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><wls:prefer-application-packages><wls:package-name>javax.jws.*</wls:package-name>

</wls:prefer-application-packages></wls:weblogic-application>


NexOpen 0.4.0 13

3Attribute 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 misleadingwhere 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 Seam way.

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 thepossibility to extend it for other modules of Framework (such as Workflow Module, see the Workflow sectionfor 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 representedby the class import org.nexopenframework.context.framework.Contexts

.....import org.nexopenframework.context.framework.Contexts;......//access to all contexts registeredObject obj = Contexts.getAttribute("my.attribute");//acccess to contexts with scope REQUESTObject 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 custom Context

The way to provide a customized Context it is just implementing the interfaceorg.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

<value>classpath*:META-INF/spring/openfrwk-module-contexts.xml</value>

Attribute Contexts Support

NexOpen 0.4.0 15

4Events 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. Inthis way, you can easily create any event class type following the java onvention (extending fromjava.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.xmlin the WEB tier and define a Spring bean as follows (this file also contains other bean for events but we onlycenter 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><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

<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

5Resources 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 obtainsuch features easily thru configuration. In NexOpen, we have choosen to offer such features in a transpaent wayor 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 ina transaparent way for our applications. However, in pure WEB applications, this could be necessary if wewould like to offer a QoS (Quality of Service). Nevertheless, from NexOpen team we encourage the use of astress-loading test tools (using Apache JMeter for instance) for observing such performance (you mut maketests 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.xmlwhich is related to easily configuration of service components which could be benfiated from the pooling fea-ture.

NexOpen 0.4.0 18

<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 configurationfile for service components.

Resources Support

NexOpen 0.4.0 19

Part II. Business TierThis part of the reference documentation is concerned with the business tier, and specifically the separation ofconcerns among business components. In NexOpen Framework, we catalog between Facades and ApplicationServices 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 (AplicationServices 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 ofSpring Framework. This feature as well others, like exception handling, are hidden to developers by use of As-pect Oriented Programming (AOP).

1Service 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 layerfor 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, concurrencycontrol and exception handling. Moreover, in environments or solutions that not included EJB container, wecan offer resource pooling support. The J2SE 5.0 annotation of NexOpen which describes this component isgiven as follows

@Target(TYPE) @Retention(RUNTIME)@Documentedpublic @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 notconsider 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 astypical Object Oriented language. usually, you can extend a set of Service Components from other class orclasses which provides several common methods (such as CRUD operations).

Excluded SuperClass and Business ServiceComponentEngine implementation

The ServiceComponentEngine implementation offers transactionality support, exception handling and otherfeatures, but one important characteristic to taken into account, it is the absence of transactionality in any parentmethod (usally related to getting information from the class). So, if you do not design carefully your base classor super class, you can observe the appearence of several errors. In order to avoid that problem, we must usethe ExcludedSuperClass annotation in your superclass (see javadoc for more details).

We can adopt the following catalog refering to ServiceComponents : Business Facades, Application Servicesand 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 ServiceComponents, that the surrender container provides, such as transactionality, security, concurrent control orpooling, 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:[email protected]">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 havementioned, every call to a business method is intercepted thru AOP and there in is where automatically, we dealwith the exception achieved in your component. Usually, this exception could be easily managed thru a JMXconsole, 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 amethod of your ServiceComponent, using the annotation @ExceptionHandler or @ExceptionHandlers if youhave 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 inproviding a class where the business logic of a component of domain model of your application is located. Inthis 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 ofusing 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:[email protected]">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 ishighly recommended use of Application Services in large applications. For easy applications, specially CRUDoperations the use of Application Services could not be seen as benefitious as large applications and in this casecould 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 possibilityto 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@Documentedpublic @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 distributableas true, automatically any change done in a node of your cluster is broadcasted to all nodes of such cluster. Inorder 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 couldbe 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 theaccesors and mutators).

Initial values or properties

Sometimes, we would like to assign a default value for a property of a given service component (either businessfacade, 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 registeredSpring 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 mustspecify 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 InstrumentationPhase, 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 ClassTransformer 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 tothis component. The parent class could be the specific ServiceSupport or the customized JBoss serice supportclass

Lifecycle in Configurable Services

Configurable serices offers at difference from other business services a lifecyle support associated internally atits managed nature. You can mark any method with any visibility (public, protected, package or private) withthe 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 youwant 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)@Documentedpublic @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 completedlystarted (in other words, are in the State START )

6.3. Addition of custom AOP interceptors

You have the possibility of addition of custom AOP interceptors in any service component. The way to do isthru an annotation Interceptors. If any annotation is present, in the enhacement phase, will be recovered andsearching into Spring IoC container or just created as a single instance (take into account that it is injected anydepedency 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 java.lang.annotation.Inherited;import java.lang.annotation.Retention;import java.lang.annotation.Target;

import org.aopalliance.aop.Advice;

@Target(TYPE) @Retention(RUNTIME)@Inheritedpublic @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. Followingwe 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 thepossibility to add interceptors thru the JSR-250 annotations Interceptors. Therefore, if we would like to trans-form the 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 otherAOP 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 thesecomponents is thru injection using the fact that components are managed thru a IoC container (in this caseSpring 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@Inheritedpublic @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 componentmanaged 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 [email protected] annotation instead. The main reason is the posibility ofFacades to be instrumented as EJB 3.0 Stateless Session Beans and all the @Resoure wil be understood by thegiven 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 timethis reponse would not change, it is not necessary to make an HTTP invocation and increasing performance ofthe application.

The way that we inject a cache, it is as follows using the [email protected]. Look that we are injecting a proxy which deals with asuitable 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 andcould 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

<value>classpath*:META-INF/spring/openfrwk-module-cache.xml</value>

Internally, it looks for a suitable implemnetations of org.nexopenframework.cache.providers.CacheProvider. Ifno one is provided, first tries to load the EhCache provider if it is found in classpath and in negative caseprovides a naive implementation based in an implementation of java.util.Map. However, you can provide yourcustom provider 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, inwhich all the Service Components, presents in the Spring IoC container, will be enhaced thru the addition offixed 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 atransparent 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 bythe 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 calland 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.0annotation TransactionAttribute.

• NameMatchTransactionAttributeSource. Spring implementation whcih checks matching wwith the methodname of your Business Service Component.

The name matches, of this last TransactionAttributeSource option, are the following (as it is carried into theservices spring configuration files).Therefore, if your method begins with one of this name, you can not declareany 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 method will execute in a tx environment using Spring Transactional* annotations support*/@org.springframework.transaction.annotation.Transactionalpublic void doBusiness(final Person 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 justJDBC or even with a custom way, such as the interfaces offered by JPA or Hibernate3, in other words being aBean 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 objectConnection 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 themethod 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 dealwith 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 currentUser, 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 Userfinal User user = actor.getCurrentUser();....//of perform programatic authzif (actor.isUserInRole("ROLE_ADMIN") {........

}......

}

The declarative way, is to use JEE 5.0 RolesAllowed annotation. This annotation should be declared at methodlevel 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 inyour beanRefContext.xml

<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 startedtwo 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 thiscould be a serious problems of management of the project and we have decided that in future releases we willfocus 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

2Service Gateway

The access to the business layer from the presentation tier is thru a Service Gateway component which hides acontainer (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 EJBremote or local container. Nevertheless, we have assumed that this scenario is erroneous and does not offersolutions 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 givencontainer. In this sense, for a developer point of view always see the same code from a client class, but the wayof how to perform invocation 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 isdefined as follows

package org.nexopenframework.core.runtime.annotations;.....@Target({TYPE,METHOD,FIELD}) @Retention(RUNTIME)@Inherited@Documentedpublic @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

@Deprecatedboolean 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 AOPadvices to be applied to invocation of Business Facade (very useful, if you want to perform authorization 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="....">

....

<bean id="servGatewayProcessor"class="org.nexopenframework.deployment.processor.ServiceGatewayProcessor"><description>

Processor which deals with service gateway references in controllers</description><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 thepresentation 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 thesame JVM. However, sometimes is desirable to have another redundance layer and EJB remotes helps toachieve scalable solutions in High Availability (HA) applications. In NexOpen you have this freedom ofchoice, and you can easily change the invocation from the client view using a JMX console.

7.1.2. EJB configuration

We must ensure that in the pom.xml of the ejb module must present the ollowing dependency

Service Gateway

NexOpen 0.4.0 35

<dependency>

<groupId>org.nexopenframework</groupId><artifactId>openfrwk-ejbgateway</artifactId><version>${nexopen.version}</version><exclusions>

<exclusion><groupId>commons-logging</groupId><artifactId>commons-logging</artifactId>


</dependency>

Service Gateway

NexOpen 0.4.0 36

3Logging and Auditing in NexOpen

in this section, we will introduce NexOpen Audting module

8.1. Introduction

Logging/Auditing are common modules which appears in traditional JEE developments

.....import org.nexopenframework.audit.annotations.Auditable;import org.nexopenframework.audit.intercept.AuditMethodInterceptor;import org.nexopenframework.core.interceptors.annotations.Interceptors;.....@Interceptors(AuditMethodInterceptor.class)@BusinessService(type=BusinessType.FACADE)public class MyFacadeImpl implements MyFacade {

/*** <p>audit will be invoked after doBusiness invocation</p>*/@Auditable(perform=PerformType.AFTER_INVOCATION)public void doBusiness() {......

}

/*** <p>audit will be invoked before doBusiness invocation</p>*/@Auditablepublic void doMoreBusiness() {......

}}

As you can observe, you do not need to perform

....@Auditablepublic class MyFacadeImpl implements MyFacade {

...}

in this case, all the methods are auditable

NexOpen 0.4.0 37

8.2. Traditional integration with a RDBMS

8.3. Integration with Oracle FGA

NexOpen provides a way to deal with Oracle FGA support

8.4. How to extend it to accomodate to your functionalities

However, several times you need a particular auditing that it is not contempleted by our implementations or ex-tend it. In order to integrate it, you must implement the Provider interafce as follows

....import org.nexopenframework.audit.AuditContext;import org.nexopenframework.audit.AuditException;import org.nexopenframework.audit.Provider;....public class MyCustomProvider implements Provider {

.....

public void audit(AuditContext context) throws AuditException {........

}}

Moreover, you must also create you custom configuration file

8.5. Configuration

In order to use the audit module, you must be sure to correctly introduce the next entrance into the beanRefCon-text.xml as follows

...<value>classpath*:META-INF/spring/openfrwk-module-audit-jdk15.xml</value><value>classpath*:META-INF/spring/openfrwk-module-audit-fga.xml</value>...

Moreover, you can also configure several properties such as execution in synchronous mode or asynchronous

Logging and Auditing in NexOpen

NexOpen 0.4.0 38

4Scheduling in NexOpen

Scheduling is a feature commonly used in traditional JEE developments

9.1. Introduction

Independently of the scheduler provider that we are using, the way to declare that a method must be scheduledis as follows

....import org.nexopenframework.core.scheduling.annotations.Scheduler;....@Scheduler(delay=1000,period=5000,executeOnStartup=true)public void simpleScheduler() {

System.out.println("EasyFacadeImpl.simpleScheduler()");}

As you have notice is the common way to deal in NexOpen, thru J2Se 5.0 annotations. This annotationprovides support for common periodic schedulings as well cron expressions (you must be sure that your pro-vider supports such feature)

Schedulers and Management using JMX

Moreover, to easily create a scheduling task, NexOpen allows to developers to easily manage such schedulerexposing common operations of pause, resume or delete an scheduler thru an Standard MBean. This MBean iscreated by the provider and registered in the MBeanServer of your Application Server.

9.2. Using OpenSymphony Quartz Provider

9.3. Using the CommonJ Provider

Besides Quartz, we have integrate with CommonJ, a specification developed by IBM and Bea WebLogic in or-der to stablish an standard of development of scheduled tasks (an te base of JSR-)

CommonJ on JBoss

CommonJ is an specification from bea WebLogic and IBM WebSphere, so it has been implemented in theseApplication Servers. In the case of JBoss, it is not implemented byd efault and you should use any implementa-

NexOpen 0.4.0 39

tion of this spec.

9.4. Configuration of Scheduling Module

In the beanRefContext.xml MUST exists an entry in order to ensure the use of the Scheduling Module in Nex-Open applications.


xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xmlns:components="http://www.nextret.org/schema/components"xsi:schemaLocation=".....">


<constructor-arg><list>......<value>classpath*:META-INF/spring/openfrwk-module-scheduler-quartz.xml</value>.......</list></constructor-arg>......</bean>

Here, we have selected the use of Quartz provider, in the case of Commonj we should specify its spring config-uration file instead.

<value>classpath*:META-INF/spring/openfrwk-module-scheduler-commonj.xml</value>

Scheduling in NexOpen

NexOpen 0.4.0 40

5Workflow

Nowadays workflows is one of the most important features that usually appears in projects. A workflow couldbe defined as the movement of documents and/or tasks through a work process. NexOpen Workflow Moduleencapsulates the complexity of a workflow implementation, JBoss jBPM, in order to provide an easy solutionto deal with document movements and tasks.

10.1. Main concepts

More specifically, workflow is the operational aspect of a work procedure: how tasks are structured, who per-forms them, what their relative order is, how they are synchronized, how information flows to support the tasksand how tasks are being tracked.

NexOpen Workflow Module offers a business process management engine for any Java EE environment.Based on JBoss jBPM, Workflow Module lets you represent a business process as a graph of nodes represent-ing wait states, decision, tasks, etc... NexOpen Workflow module offers you a simply way to enhace your Busi-ness Services to interact with the business process management engine.

JBoss jBPM and Nexopen Workflow Module use JPDL (JBpm Process Definition Language) as a language todefine business process. These Business Process are defined using XML documents written in JPDL. TheseXMLs specify entities such as the various states in the process (known as nodes), the task associated with eachnode, the transitions from one node to the next, the actions associated to the events on nodes and more. You canfind information about JPDL on http://www.jboss.com/products/jbpm/docs/jpdl and in the jBPM referenceguide http://docs.jboss.com/jbpm/v3/userguide/jpdl.html

10.2. JBoss jBPM integration

We've designed our integration with JBoss jBPM using Spring Modules in order to make jBPM Call Backs,that allow code to be executed directly on jBPMContext. The relationship between Process Instance and Asso-ciated Entities is made throught saving Primary Key at Process Context. We use NexOpen Context Module inorder to perfom this Integration. The Current Process Context is loaded using Hiberante Listeners. When abusiness service method load an Entity the Workflow module is responsible to load the process Instances bind-ed to this Entity

We have implemented the above interfaces with the Open Source project JBoss jBPM 3.1.x

NexOpen 0.4.0 41

Figure 10.1. NexOpen Workflow Integration with jBPM 3.1.x

Workflow

NexOpen 0.4.0 42

Figure 10.2. NexOpen Workflow

Workflow

NexOpen 0.4.0 43

Figure 10.3. NexOpen Workflow Context

Now we're gonna comment the most significative classes that help us to integrate JBoss jBPM.

JbpmContextHolder

This interface allow to access the Jbpm Current Process Context. Thank to this JbpmCurrentProcessContext wecan access to native JBoss Jbpm configuration, and provides convenient access to the most common jbpm oper-ations.

ContextAttributePostInsertEventListener

Hibernate Listener. Put in Contexts the inserted Entity and his primary Key only if the entity is annotated withContextAttribute Annotation. This Event Listener is the key that allow to work with the Process Instance bind-ed to the Entity. The main concept of the Jbpm Integration is that bind, between an entity and a Process In-stance.

Workflow

NexOpen 0.4.0 44

ContextAttributePostLoadEventListener

Hibernate Listener. Put in Contexts the loaded Entity and his primary Key only if the entity is annotated withContextAttribute Annotation

ProcessManagerInterceptor

Aspect Oriented Programming (AOP) Interceptor which process a workflow action that belongs to a businessstate machine. This Interceptor resolves the existence of ProcessManagerDefinition from a method call. Lookup the corresponding Process Instance and the Process Instance Context from the contexts, and then performsthe Workflow Action that it's indicated in the method call Intercepted. Works with the AnnotationProcessMan-agerResolver.

AnnotationProcessManagerResolver

Process Manager Definition Resolver from Annotations. Builds the Process Manager Definition from the cur-rent Annotated method. Gives the needed information to the corresponding Process Manager Interceptor, in or-der to allow it to perform the Workflow Action.

AnnotationContextAttributeResolver

Context Attribute Resolver from Annotation Information. Builds the Context Attribute from the current Annot-ated method. As the AnnotationProcessManagerResolver gives information to the corresponding Process Man-ager Interceptor in order to allow perform the Workflow Action.

10.3. Configuration

The way to configure WorkFlow module in your project is by adding workflow module dependency to yourbusiness pom file

<dependencies><dependency>

<groupId>org.nexopenframework</groupId><artifactId>openfrwk-workflow</artifactId><version>${nexopen.version}</version>

</dependency></dependencies>

If you are planning to work with jdk15 you should use WorkFlow Module with Annotation Support

<dependencies><dependency>

<groupId>org.nexopenframework</groupId><artifactId>openfrwk-workflow-jdk15</artifactId><version>${nexopen.version}</version>

Workflow

NexOpen 0.4.0 45

</dependency></dependencies>

The next step is update the beanRefContext.xml File. In that file MUST exists an entry in order to ensure theuse of the Workflow Module in NexOpen applications.

......<beans xmlns="http://www.springframework.org/schema/beans"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation=".....">


<constructor-arg><list>......<value>classpath*:META-INF/spring/openfrwk-module-workflow-jbpm.xml</value>.......</list></constructor-arg>......</bean>

</beans>

In you prefer to use WorkFlow module with Annotation Support and with Hibernate Integration you should ref-erence one of these files

.......<value>classpath*:META-INF/spring/openfrwk-module-workflow-jbpm-jdk15.xml</value><value>classpath*:META-INF/spring/openfrwk-module-workflow-jbpm-hb-jdk15.xml</value>

.......

It's also necessary to include jbpm Mapping files in Hibernate Configuration file hibernate.cfg.xml

.......<mapping resource="org/jbpm/db/hibernate.queries.hbm.xml" />

<mapping resource="org/jbpm/graph/def/ProcessDefinition.hbm.xml"/><mapping resource="org/jbpm/graph/def/Node.hbm.xml"/><mapping resource="org/jbpm/graph/def/Transition.hbm.xml"/><mapping resource="org/jbpm/graph/def/Event.hbm.xml"/><mapping resource="org/jbpm/graph/def/Action.hbm.xml"/><mapping resource="org/jbpm/graph/def/SuperState.hbm.xml"/><mapping resource="org/jbpm/graph/def/ExceptionHandler.hbm.xml"/><mapping resource="org/jbpm/instantiation/Delegation.hbm.xml"/>

<mapping resource="org/jbpm/graph/node/StartState.hbm.xml"/><mapping resource="org/jbpm/graph/node/EndState.hbm.xml"/><mapping resource="org/jbpm/graph/node/ProcessState.hbm.xml"/><mapping resource="org/jbpm/graph/node/Decision.hbm.xml"/>

Workflow

NexOpen 0.4.0 46

<mapping resource="org/jbpm/graph/node/Fork.hbm.xml"/><mapping resource="org/jbpm/graph/node/Join.hbm.xml"/><mapping resource="org/jbpm/graph/node/State.hbm.xml"/><mapping resource="org/jbpm/graph/node/TaskNode.hbm.xml"/>

<mapping resource="org/jbpm/context/def/ContextDefinition.hbm.xml"/><mapping resource="org/jbpm/context/def/VariableAccess.hbm.xml"/>

<mapping resource="org/jbpm/taskmgmt/def/TaskMgmtDefinition.hbm.xml"/><mapping resource="org/jbpm/taskmgmt/def/Swimlane.hbm.xml"/><mapping resource="org/jbpm/taskmgmt/def/Task.hbm.xml"/><mapping resource="org/jbpm/taskmgmt/def/TaskController.hbm.xml"/>

<mapping resource="org/jbpm/module/def/ModuleDefinition.hbm.xml"/>

<mapping resource="org/jbpm/bytes/ByteArray.hbm.xml"/>

<mapping resource="org/jbpm/file/def/FileDefinition.hbm.xml"/>

<mapping resource="org/jbpm/scheduler/def/CreateTimerAction.hbm.xml"/><mapping resource="org/jbpm/scheduler/def/CancelTimerAction.hbm.xml"/>

<mapping resource="org/jbpm/graph/exe/Comment.hbm.xml"/><mapping resource="org/jbpm/graph/exe/ProcessInstance.hbm.xml"/><mapping resource="org/jbpm/graph/exe/Token.hbm.xml"/><mapping resource="org/jbpm/graph/exe/RuntimeAction.hbm.xml"/>

<mapping resource="org/jbpm/module/exe/ModuleInstance.hbm.xml"/>

<mapping resource="org/jbpm/context/exe/ContextInstance.hbm.xml"/><mapping resource="org/jbpm/context/exe/TokenVariableMap.hbm.xml"/><mapping resource="org/jbpm/context/exe/VariableInstance.hbm.xml"/><mapping resource="org/jbpm/context/exe/variableinstance/ByteArrayInstance.hbm.xml"/><mapping resource="org/jbpm/context/exe/variableinstance/DateInstance.hbm.xml"/><mapping resource="org/jbpm/context/exe/variableinstance/DoubleInstance.hbm.xml"/><mapping resource="org/jbpm/context/exe/variableinstance/HibernateLongInstance.hbm.xml"/><mapping resource="org/jbpm/context/exe/variableinstance/HibernateStringInstance.hbm.xml"/><mapping resource="org/jbpm/context/exe/variableinstance/LongInstance.hbm.xml"/><mapping resource="org/jbpm/context/exe/variableinstance/NullInstance.hbm.xml"/><mapping resource="org/jbpm/context/exe/variableinstance/StringInstance.hbm.xml"/>

<mapping resource="org/jbpm/msg/Message.hbm.xml"/><mapping resource="org/jbpm/msg/db/TextMessage.hbm.xml"/><mapping resource="org/jbpm/command/ExecuteActionCommand.hbm.xml"/><mapping resource="org/jbpm/command/ExecuteNodeCommand.hbm.xml"/><mapping resource="org/jbpm/command/SignalCommand.hbm.xml"/><mapping resource="org/jbpm/command/TaskInstanceEndCommand.hbm.xml"/>

<mapping resource="org/jbpm/taskmgmt/exe/TaskMgmtInstance.hbm.xml"/><mapping resource="org/jbpm/taskmgmt/exe/TaskInstance.hbm.xml"/><mapping resource="org/jbpm/taskmgmt/exe/PooledActor.hbm.xml"/><mapping resource="org/jbpm/taskmgmt/exe/SwimlaneInstance.hbm.xml"/>

<mapping resource="org/jbpm/scheduler/exe/Timer.hbm.xml"/>

<mapping resource="org/jbpm/logging/log/ProcessLog.hbm.xml"/><mapping resource="org/jbpm/logging/log/MessageLog.hbm.xml"/><mapping resource="org/jbpm/logging/log/CompositeLog.hbm.xml"/>

Workflow

NexOpen 0.4.0 47

<mapping resource="org/jbpm/graph/log/ActionLog.hbm.xml"/><mapping resource="org/jbpm/graph/log/NodeLog.hbm.xml"/><mapping resource="org/jbpm/graph/log/ProcessInstanceCreateLog.hbm.xml"/><mapping resource="org/jbpm/graph/log/ProcessInstanceEndLog.hbm.xml"/><mapping resource="org/jbpm/graph/log/ProcessStateLog.hbm.xml"/><mapping resource="org/jbpm/graph/log/SignalLog.hbm.xml"/><mapping resource="org/jbpm/graph/log/TokenCreateLog.hbm.xml"/><mapping resource="org/jbpm/graph/log/TokenEndLog.hbm.xml"/><mapping resource="org/jbpm/graph/log/TransitionLog.hbm.xml"/><mapping resource="org/jbpm/context/log/VariableLog.hbm.xml"/><mapping resource="org/jbpm/context/log/VariableCreateLog.hbm.xml"/><mapping resource="org/jbpm/context/log/VariableDeleteLog.hbm.xml"/><mapping resource="org/jbpm/context/log/VariableUpdateLog.hbm.xml"/><mapping resource="org/jbpm/context/log/variableinstance/ByteArrayUpdateLog.hbm.xml"/><mapping resource="org/jbpm/context/log/variableinstance/DateUpdateLog.hbm.xml"/><mapping resource="org/jbpm/context/log/variableinstance/DoubleUpdateLog.hbm.xml"/><mapping resource="org/jbpm/context/log/variableinstance/HibernateLongUpdateLog.hbm.xml"/><mapping resource="org/jbpm/context/log/variableinstance/HibernateStringUpdateLog.hbm.xml"/><mapping resource="org/jbpm/context/log/variableinstance/LongUpdateLog.hbm.xml"/><mapping resource="org/jbpm/context/log/variableinstance/StringUpdateLog.hbm.xml"/><mapping resource="org/jbpm/taskmgmt/log/TaskLog.hbm.xml"/><mapping resource="org/jbpm/taskmgmt/log/TaskCreateLog.hbm.xml"/><mapping resource="org/jbpm/taskmgmt/log/TaskAssignLog.hbm.xml"/><mapping resource="org/jbpm/taskmgmt/log/TaskEndLog.hbm.xml"/><mapping resource="org/jbpm/taskmgmt/log/SwimlaneLog.hbm.xml"/><mapping resource="org/jbpm/taskmgmt/log/SwimlaneCreateLog.hbm.xml"/><mapping resource="org/jbpm/taskmgmt/log/SwimlaneAssignLog.hbm.xml"/>

.......

Now the Workflow module it's ready to work

10.4. How to Enhace an Entity with a Workflow Process

Due to business reasons it could be interesting to you to enhance some of your entities by binding an specificWorkflow to them. This workflow must be in charge of perform some cross operations that allow to your Anal-ist to detach workflow business logic from your entity logic. By this way we could add a Process Event Dis-patcher Bean to dispatch the events defined in the Workflow Process Definition, a Process Decision ManagerBean in charge of manage the decisions in the Workflow Process Definition and so on.

Now we're gonna show in a few steps how to enhace one of your business Entity with a Workflow Process

Step 1. Add the Process Definition reference to your Application business Service

import org.nexopenframework.workflow.annotations.ProcessDefinition;import es.example.Example;

@ProcessDefinition(entity = Example.class, name = "example-process-definition")</para>

Step 2. You must configure a jBPM process definition as a Spring Bean to be referenced by your ApplicationService

<bean id="example-process-definition"

Workflow

NexOpen 0.4.0 48

class="org.springmodules.workflow.jbpm31.definition.ProcessDefinitionFactoryBean"><property name="definitionLocation"

value="classpath:META-INF/bpm/example-process-definition/processdefinition.xml"></property>

</bean>

Step 3. Add the Process Manager Interceptor to Interact with your Application Business Service

import org.nexopenframework.core.interceptors.annotations.Interceptors;import org.nexopenframework.workflow.intercept.ProcessManagerInterceptor;

@Interceptors( { ProcessManagerInterceptor.class }}

Step 4. Add Spring Configuration for the business Entity

<bean id="serviceContext"class="org.nexopenframework.workflow.providers.jbpm31.JbpmProcessInstanceContext"><description>Custom context related with business logic</description><property name="order" value="1"/><property name="entityClass" value="es.exanple.Example"/><property name="queryHints">

<map><entry key="org.nexopenframework.persistence.hibernate3.cacheEnabled" value="true" /><entry key="org.nexopenframework.persistence.hibernate3.cacheRegion" value="jbpm" />

</map></property>

</bean>

Step 5. Now you can annotate your Business Methods with the Workflow Module Annotations

@org.nexopenframework.workflow.annotations.ProcessDefinitions{@ProcessDefiniton(), @ProcessDefinition()}@org.nexopenframework.workflow.annotations.ProcessDefinition(name=“”, entity=Object.class)@org.nexopenframework.workflow.annotations.CreateProcess(name=“”, transition=“”)@org.nexopenframework.workflow.annotations.BeginTask(process=“”, name=“”, id=“”)@org.nexopenframework.workflow.annotations.ProcessContext(value=“”)@org.nexopenframework.workflow.annotations.Transition(process=“”, name=“”)@org.nexopenframework.workflow.annotations.EndTask(process=“”, name=“”, id=“”, transition=“”)

10.5. WorkFlow Annotations

10.5.1. Process Definition

Type Annotation to define a Process Definition. The basis of a process definition is a graph that is made up ofnodes and transitions. That information is expressed in an xml file called processdefinition.xml . You can findmore information about how to define a Business Process using Java Process Definition Language on ht-tp://www.jboss.com/products/jbpm/docs/jpdl Using Process Definition Annotation we're binding the process-

Workflow

NexOpen 0.4.0 49

definition referenced by the process-definition.xml, the Entity Class and the Business Service.

@BusinessService(type = BusinessType.APPLICATION)@ProcessDefinition(entity = Example.class, name = "example-process-definition")public class ExampleAppService {

//}....public class Example {

//}

10.5.2. Process Definitions

Type Annotation to define a set of Process Definition that binds to this Business Service. We usually use thisAnnotation when we're moving two process definitions with the same Business Service. After that, in the busi-ness service methods, you could the choose between differents process definitions using ProcessContext an-notation.

@BusinessService(type = BusinessType.APPLICATION)@ProcessDefinitions{

@ProcessDefinition(entity = Example.class, name = "example-process-definition"),@ProcessDefinition(entity = AnotherExample.class, name = "another-example-process-definition")

}public class ExampleAppService {

//}....public class AnotherExample{

//}

public class Example {//

}

10.5.3. CreateProcess

Method Annotation to create a Process Instance. Those methods annotated with CreateProcess creates a newProcess Instance of the process-definition binded with the Business Service. You could force a transition or notafter the creation of a process definition using the boolean property transition.

@CreateProcess(transition=true)public void create(Example ex) {

//}

10.5.4. BeginTask

Workflow

NexOpen 0.4.0 50

Method Annotation that Marks a method as causing jBPM Task associated to the process-definition binded tothe Business Service to be started. You can identify the task using the name of the task defined in the processdefinition. If there's more than a process definition binded to the business service you can choose the processdefinition to work on using the property process of the BeginTask annotation.

@BeginTask(name="exampleTask", process="processDefinition")public void create(Example ex) {

//}

10.5.5. ProcessContext

Process Context Annotation marks a Business Service method to be used in a Workflow Process Context andloads the Entity binded to the Process Context associated to the Business Service.

@ProcessContext(name="exampleTask")public void doSomething(Example ex) {

//}

10.5.6. Transition

Annotation method that marks as causing a jBPM transition to the Process-definition binded to the BusinessService.

@Transition(name="nextStep")public void update (Example ex){

//}

10.5.7. EndTask

Method Annotation to mark as Ended a Task Instance.

@EndTask(name="exampleTask")public void done(Example ex) {

//}

Workflow

NexOpen 0.4.0 51

6NexOpen as a Test-Design Driven Framework

Nowdays, a well defined application has to provide tests suites for checking unitary and functionality features.In java and JEE applications JUnit has the reference test framework for fulfilling these features.

11.1. Test support for Service Components using JUnit3

NexOpen extends the JUnit3 TestCase for providing a development mark to easily test your complex funtional-ities of yours JEE applications.

11.2. Support for JUnit4

NexOpen 0.4.0 and higher release also offer support for dealing with test annotation-driven frameworks such asJUnit4.

...import org.junit.Test;import org.junit.runner.RunWith;import org.nexopenframework.test.junit4.NexOpenJUnit4ClassRunner;import org.nexopenframework.test.junit4.annotations.TestCallbackListeners;import org.nexopenframework.test.junit4.support.PerformanceCallbackListener;.....@TestCallbackListeners(PerformanceCallbackListener.class)@RunWith(NexOpenJUnit4ClassRunner.class)public class MBeanServerManagerTest {

....@Test(imeout=60)public void doSomeTestOp() {

..........}

}

NexOpen and TestNG

NexOpen 0.4.0 52

7Web Services Reference

Sometimes, in the Business Layer, we must integrate with one or several third party Web Services

12.1. Introduction

In order to deal with this feature, exists the JAX-WS 2.0 specification in order to provide a common way todeal with Web Services integration

12.2. NexOpen and JAX-WS 2.0

NexOpen uses JAX-WS 2.0 in order to integrate with Web Services. Following the nice practices developed bySpring Team, we use AOP and we leave to develoeprs to define properly the interface which provides the gate-way to invoke the methods exposed by the foreign Web Service which would like to integrate. Next, we showhow to develope the before mentioned ideas, just following the JAX-WS 2.0 specs

....import javax.jws.WebMethod;import javax.jws.WebParam;import javax.jws.WebResult;import javax.jws.WebService;import javax.jws.soap.SOAPBinding;import javax.xml.ws.WebServiceClient;import javax.xml.ws.WebServiceRef;....

@Business(type=BusinessType.APPLICATION)public class MyAppService {

/***/@WebServiceRef(ExampleServiceService.class)private ExampleService wsref;

......}

@WebService(targetNamespace = "http://ws.nexopenframework.org/example",name="ExampleWS")

@SOAPBinding(style=SOAPBinding.Style.RPC)public interface ExampleService {

@WebMethodpublic String sayHello();@WebMethod@WebResult(name="user")public User findUserByPrimaryKey(@WebParam(name="id") long id)

throws UserNotFoundException;}......@WebServiceClient(targetNamespace = "http://ws.nexopenframework.org/example",

name="ExampleWS")public class ExampleServiceService extends javax.xml.ws.Service {

NexOpen 0.4.0 53

public ExampleServiceService() throws java.net.MalformedURLException {super(new java.net.URL("http://my.domain.com/services/ExampleWSService?wsdl"),

new javax.xml.namespace.QName("http://ws.nexopenframework.org/example","ExampleWSService"));

}

public ExampleServiceService(java.net.URL wsdlDocumentLocation,javax.xml.namespace.QName serviceName) {

super(wsdlDocumentLocation, serviceName);}

}.....

As we can observe, from our Business component, in this case an Application Service, but it is also possible tobe defined in a Facade or Configurable Service, we define the needed to integrate with a foreign Web Service

Despite the fact that we write at code level the wsdl URL location, this can be easily changed because NexOpenprovides an Standard MBean in order to manage this integration.

12.3. XFire 1.2.x integration

Moreover of the specification annotations and nexOpen custom annotations, in the case of XFire NexOpenprovides also the possibility to integrate with common features developed by XFire when client would like toinvoke a Web Service

XFire 1.2.x and JAX-WS 2.0

In versions 1.2.x Xfire is not full compliant with JAX-WS 2.0 specification. In order to avoid problems, inNexOpen we have extended the JAX-WS 2.0 Provider in order to achieve several aspects of specification. Ifyou want to use this provider, you must be sure to define a file called javax.xml.ws.spi.Provider in the tradition-al META-INF/services location. See configuration section for more details where to place it in a EAR o WARartifact

.....import javax.jws.WebMethod;import javax.jws.WebParam;import javax.jws.WebResult;import javax.jws.WebService;import javax.jws.soap.SOAPBinding;

import org.codehaus.xfire.annotations.EnableMTOM;import org.codehaus.xfire.annotations.InHandlers;import org.codehaus.xfire.annotations.OutHandlers;......@WebService(targetNamespace = "http://ws.nexopenframework.org/example",

name="ExampleWS")@SOAPBinding(style=SOAPBinding.Style.RPC)@EnableMTOM@InHandlers(handlers={"org.nexopenframework.example.xfire.DummyHandler"})@OutHandlers(handlers={"org.nexopenframework.example.xfire.LoggerHandler"})public interface ExampleService {.......

}

Web Services Reference

NexOpen 0.4.0 54

12.4. Test Support

NexOpen provides support for using JUnit3 as test Framework support. using NexOpen facilities we can easilytest if the call related to Web Service is correct or not

.....import org.nexopenframework.core.ws.WebServiceException;import org.nexopenframework.jaxws.test.xfire.AbstractXFireWebServiceTestCase;.....public class ClassificationWSTest extends AbstractXFireWebServiceTestCase {

/*** <p>Here, we initialize our test providing the* Service Endpoint Interface (SEI) to be tested.</p>*/public ClassificationWSTest() {

//the service endpoint interface to be tested//you must be aware that this interface has JSR-181 annotations//Also supports NexOpen WS Reference annotations such as//Credentials for BASIC authentication and ProxySettings//if you have behind a proxy.this.setServiceEndpointInterface(ClassificationWS.class);//HTTP wsdl locationthis.setWsdlLocation("http://www.mydomain.com/mycontext/"+

"services/ClassificationWSService?wsdl");}

/*** <p>Unique method to be invoked by JUnit3 for

* test the ClassificationWS interface. Here,* you will perform the invocations to publish* web service methods</p>

*/public void testWebService() throws WebServiceException, IOException {

if (logger.isDebugEnabled()) {logger.debug("WSDL location to be tested :: "+ wsdlLocation);

}//retrieve the client to communicate to the external//web servicefinal Object client = getClient();assertNotNull(client);

assertTrue(client instanceof ClassificationWS);final ClassificationWS sei = (ClassificationWS) client;

if (logger.isDebugEnabled()) {logger.debug("Service Endpoint Interface :: "+ sei);

}//invoke the published methods by external web service

....}

}

12.5. Configuration

In case of XFire integration, we must ensure to


NexOpen 0.4.0 55

Finally, we specify where to place the javax.xml.ws.spi.Provider if you plan to use NexOpen-XFire extension.This file conatins only one line, where we exlicetly specify the NexOpen Provider extension

org.nexopenframework.xfire.jaxws.Provider

In a EAR you must be sure to place at root in a folder META-INF/services as indicate the specs. In a NexOpen-maven2 structure the correct place is

+earProject|+ear|+src|+main

|+resources|+META-INF|+services|+javax.xml.ws.spi.Provider

.....

In the case of a WAR artifact you should place into the classpath also in same folder but under WEB-INF/classes location

+webProject.....|+web|+src|+main

|+resources|+META-INF|+services|+javax.xml.ws.spi.Provider

.....


NexOpen 0.4.0 56

Part III. Resource TierThis part of the reference documentation is concerned with how NexOpen covers the rersource tier, and wemainly focus with Persistence Manager, a Facade unified interface which it is the main point of dealing withORM operations. NexOpen mainly focus with ORM approach and provides an intgeration with Hibernate3 orJPA and the JSR-220 specification for to implement, using the javax.entity.Entity annotation and others,the domain model of your application.

Finally, we will deal with how Asynchronous tasks are done in NexOpen Framework. For this kind of feature,we provide a Facade, defined by TaskExecutor class, which hides the complexities of JMS 1.1 and even theEJB Message-Driven Bean. Thru this class we can easily

1Persistence Manager

Nowdays, the use of a Data Access Object Pattern (DAO) it could be a tedious maintenance problem due to thegreat number of classes that apparently have the same pattern (Create, Retrieve, Update and Delete). However,we do not say that it is unseful, because sometimes the use of this Core J2EE pattern allows to decouple the re-source layer and the business layer avoiding the existence of a OQL or SQL (for example a dynamic query ifwe do not want to use teh Criteria facility explained after) in your code. Nevertheless, it exists other patternslike the Domain Store pattern that simplifies the number of classes and recently has appeared the JSR-220 spe-cification with the javax.persistence.EntityManager which provides a Facade to the resource layer avoidinga great number of classes and then simplifying the maintenance of your application.

In this section, we will try to explain why NexOpen has selected this option of a unified interface in order todeal with the persistence and when it is recommended to use the famous Core J2EE pattern DAO

13.1. PersistenceManager API

Persistence Manager is based in the Object Relational Mapping (ORM) philosophy. It is important to note thatNexOpen Framework does not provide a implementation of a new ORM, NexOpen only try to integrate severalknow ORM OpenSource, like Hibernate3 or any JPA Open Source provider, trying to simplify the knowlodge-ment of these implementations. Besides having a several CRUD operations like persist, delete, update andsimple finders, it is also a Query factory and Criteria Factory. The main point it is to consider this interface as apart of the integration or resource layer. DAO's will be needed,as we have mentioned before, if we have querystrings that compromises and couples the business layer. Just persisting, deleting or easy retrieval includingquery finder with named queries could be kept in a Service Component (business layer) without need of DAOs.The SPI it is based in the javax.persistence.EntityManager interface from JSR-220 spec (EJB 3.0). It is im-portant to note that all the POJO classes which represents the entities in a persistence storage should be annot-ated with the JSR-220 annotation javax.persistence.Entity

The way that it is used in a J2SE 5.0 environment, it is as easy as we can see in the following example, where aService Component use this API for ORM operations

import org.nexopenframework.persistence.PersistenceManager;

....

/**The PersistenceManager SPI for persistence storage operations*/@PersistenceManagerContextPersistenceManager pm;

/*** <p>PersistenceManager is a Facade which hides the complexities* of deal with ORM providers (such as Hibernate3, JPA and so on)</p>** @param pm*/

public void setPersistenceManager(PersistenceManager pm) {

NexOpen 0.4.0 58

this.pm = pm;}

public void persistIssue(Issue issue) {//way that we persist a POJO entitythis.pm.persist(issue);

}

Looks the presence of the annotation PersistenceManagerContext which tell to NexOpen Framework the needof injection of a PersistenceManager. The PersistenceManager SPI provides several useful methods for persistand object or a Collection, delete an existent mapped object in a persistence storage (like a RDBMS, for ex-ample a MySQL or Oracle) and updating (merging) and object

DAO and PersistenceManager API

The PersistenceManager is based in a Core J2EE Patterns called Domain Store, where its core is a Store DAOfor the typical operations CRUD. DAO is a well-know pattern, where tries to hide the complexities of access toa persistence storage and decouples nicely the business layer and the persistence layer.Unfortunately, itprovides a lot of classes in the persistence layer (interfaces, implementations and so on) which increase themanageability of any J2EE application and having same persistence functionality (creation, updating and deleteof entities). However, the presence of JSR-220 EntityManager APIs, has apported a way to reduce these classesand provides more manageable JEE applications.

However, if you need to inject into your class a PersistenceManager and it is not a NexOpen component(Business Service class, Configurable Service or a JobTask), you can do it in the traditional Spring way, inject-ing the PersistenceManager under bean name openfrwk.persistenceManager in a Spring configuration file

......<bean id="myBean" class="org.mypackage.MyBean">

<property name="persistenceManager" ref="openfrwk.persistenceManager"/>......

</bean>.....

or another alternative is just creating a simple locator of PersistenceManager and using in any class which it isnot a ServiceComponent without needs of declaring in any Spring configuration file

....import org.nexopenframework.persistence.PersistenceManager;import org.nexopenframework.spring.BeanLocator;

public abstract class PersistenceManagerLocator {

public static PersistenceManager getPersistenceManager() {return (PersistenceManager) BeanLocator.getBean("openfrwk.persistenceManager");

}

}

Persistence Manager

NexOpen 0.4.0 59

Notice the presence of BeanLocator class, which is able to locate any bean registered in the Business Applica-tionContext (take in mind that Spring offers a hierarchy of ApplicationContexts and Beanlocator is registered inthe business layer, so it has not access to beans regsitered in the web layer such as Spring MVC controllers,Struts actions and so on).

13.2. Query API

The PersistenceManager class it is also factory of Query . This class presents a simplified way to executequeries (such as OQL, HQL, JPQL) and native queries (using SQL). In the following exemple we show, how toexecute a named query (defined in a xml file, package-info class or metadata at class level) and execute a list ofvalues

import org.nexopenframework.persistence.PersistenceManager;import org.nexopenframework.persistence.Query;....

/**The PersistenceManager SPI for persistence storage operations*/@PersistenceManagerContextPersistenceManager pm;

...public List<Issue> findIssuesByCriteria(final String name, final int age1, final int age2) {

//retrieval [Named query]final Query q = pm.createNamedQuery("findByName");q.setParameter("name", name).setParameter("age1", new Integer(age));q.setParameter("age2", new Integer(24));final List values = q.execute();.....

}

You can create native queries using the createNativeQuery method and also createQuery where you put theHQL.

//how to create a native queryfinal Query q_native =

pm.createNativeQuery("SELECT NAME, FIRSTNAME, SECONDNAME FROM PERSON "+"WHERE PERSON.ID LIKE ? AND SECONDNAME IS NOT NULL");

.....//how to create a HQL query objectfinal Query q_hql =

pm.createQuery("from Person as p where p.id like :id and "+"p.secondName is not null");

...

After it has been created, we can easily add the parameters associated to this query and execute the result.Moreover, we can execute Stored Procedures using this object. Take in mind, that we are delagating executionto Hibernate3 and this powerful ORM Framework can easily execute Stored Procedures.

Moreover, we can easily add several features such as query caching facilities, custom hints and pagination sup-port (see javadoc for more detailed information)

Persistence Manager

NexOpen 0.4.0 60

//query cache facilitiesfinal Query q_cache = pm.createNamedQuery("findByComplexFilter");//activation of query caching facilityq_cache.setCacheEnabled(true);//region name where query results is savedq_cache.setRegionName("nexopen");....//query hintsfinal Query q_hint = pm.createNamedQuery("findByCriteria");//fecth supportq_hint.setHint("org.nexopenframework.persistence.hibernate3.fetchSize","10");//Hibernate Hints interface in order to provide Hints supported by Hibernate3//[located at org.nexopenframework.persistence.hibernate3.support.HibernateHints]q_hint.setHint(HibernateHints.HIBERNATE_TIMEOUT,"60");....//query pagination supportfinal Query q_pag = pm.createNamedQuery("findByPagination");q_pag.setFirstResult(10);q_pag.setMaxResults(20);....

13.3. Criteria API

This API is related to build dynamic queries dependending of the values you would like to add. It is a well wayto deal with filters in the presentation layer

...import org.nexopenframework.persistence.Criteria;import org.nexopenframework.persistence.PersistenceManager;import org.nexopenframework.persistence.criterion.CriterionFactory;....

public void doSomething(final String someValue) {final Criteria criteria = this.pm.createCriteria(MyEntity.class);criteria.add(CriterionFactory.like("someValue", someValue));final List values = criteria.execute();....

}

Look at the presence of CriterionFactory a factory of Criterions which fulfills all the specific features of apersistence storage grammar (in other words, typical SQL like, equals, between operations or even maximumand minimal) as you can see in the next example and adding to Criteria object

//create a like criterionfinal Criterion c_like = CriterionFactory.like("someValue", someValue);criteria.add(c_like);//create a non-equals criterionfinal Criterion c_ne = CriterionFactory.ne("someValue2", someValue2);criteria.add(c_ne);//create a between criterionfinal Criterion c_between = CriterionFactory.between("otherValue", lo, hi);criteria.add(c_between);

.......

Persistence Manager

NexOpen 0.4.0 61

Moreover, in criteria you can also add pagination features and also specify hints

...//use of pagination supportfinal Criteria criteria = this.pm.createCriteria(MyEntity.class);criteria.setFirstResult(10).setMaxResults(20);....//use of hints thru Criteria API//Hibernate Hints interface in order to provide Hints supported by Hibernate3//[located at org.nexopenframework.persistence.hibernate3.support.HibernateHints]criteria.setHint(HibernateHints.HIBERNATE_TIMEOUT,"60");....

13.4. Integration with Hibernate3

Hibernate (http://www.hibernate.org/) is one of the most popular ORM frameworks. NexOpen provides an im-plementation of PersistenceManager based in Hibernate3. In this way, w can easily deal with Hibernate3 for-getting the complexities related to deal with the Hibernate3 Session in disconnected way (internally we deleg-ate to the Spring Framework excellent implementation).

Retrieve Hibernate Session from PersistenceManager

Sometimes it is recommended to retrieve the Hibernate Session for dealing with specific features of SessionAPI (evict entities, create scrolled results sets and so on). Fortunately, the implementation of Hibernate3 ofPersistenceManager also implements the SessionHandle interface, so simplely casting to this interface youcan retrieve the current Session for dealing with specific features, just using the getCurrentSession method.

13.5. Integration with Java Persistence API (JPA)

The EntityManager API is the standard way to deal with persistence in the new JEE 5.0 specification, the JPAspecification. NexOpen PersistenceManager provides an easy way to deal with this feature without changingcode. Nevertheless, if you plan to start a new project and you would like to offer an standard way to deal withpersistence, we strongly recommend use directly JPA and enjoy of the excellent integration which offersSpring.

Bridge EntityManager-PersistenceManager

NexOpen provides a bridge if you want to use the JSR-220 EntityManager but you have not configured anyPersistenceProvider. Due the fact that presents a common interface, you can use it in your ServiceCompon-ents. The injected class it is a bridge with the PersistenceManager class configured in your application.

You must notice that this feature is supported since 0.4.x versions and higher.

13.6. Integration with EJB3 POJO Validation

Persistence Manager

NexOpen 0.4.0 62

New in 0.4.x versions and higher it is validation support at EJB3 POJO level using Oval Framework or Hibern-ate Validators. Oval supports JSR-220 annotations and it provides an non-intrusive way to deal with validationsat diference from Hibernate Validator which provides several useful annotations to be added to your EntityModel. Following example uses

....import org.hibernate.validator.Email;import org.hibernate.validator.Length;import org.hibernate.validator.NotNull;....@Entitypublic class Person extends BaseEntityImpl implements Serializable {..../**Person name*/@Length(min=3, max=50)@NotNullprivate String name;/**Person first name*/@Length(min=4, max=100)@NotNullprivate String firstName;/**Person second name*/@Length(max=100)private String secondName;/**person's email*/@Email@NotNullprivate String email;........}

If your are using JPA as your persistence layer, you can declare easily a Entity Listener which performs the val-idations

......import javax.persistence.EntityListeners;......@Entity@EntityListeners(JpaValidatorListener.class)public class Person extends BaseEntityImpl implements Serializable {......

NexOpen Validation support

Behind the scenes Nexopen provides an easy implementation of validation for POJOs. The core class is a GoFFacade called Validator which delegates to a suitable implementation of ValidatorDelegate interface. EJB3POJO validator module provides suitable implementations based in Hibernate Validator or in Oval Framework.

13.7. ServiceComponents and common CRUD operations

NexOpen provides since 0.4.x versions and higher a typed DAO interface for dealing with common CRUD op-erations thru GenericServiceDAO. If your Facades and Application Services has common operations related to

Persistence Manager

NexOpen 0.4.0 63

a given entity, we strongly recommend the use of this DAO and choose the persistence model of your applica-tion, using the generic PersistenceManager or JPA. in the following example, we show an example of such fea-ture for JPA persistence framework

....import org.nexopenframework.persistence.jpa.support.JpaGenericServiceDAO;.....public class UserFacadeImpl extends JpaGenericServiceDAO<User, Long>

implements UserFacade {public UserFacadeImpl() {

//the entity to be managedsuper(User.class);

}....}

Also, in the case of Facades,it has a good practice to extend from GenericServiceDAO, as we show below

....import org.nexopenframework.persistence.support.GenericServiceDAO;....public interface UserFacade extends GenericServiceDAO<User, Long> {.....}

In this way, we can asily deal with common CRUD operations in Facades and Application Services

GenericServiceDAO inheritance in Configurable Business Services

As we have mentioned in the services chapter, Business Configurable Services (hereafter Services) does notsupport classic inheritance support (we can not extend from any class due the fact that in Instrumentation Phaseit is provided a suitable parent class).

13.8. Test support for Persistence Module

As we have mentioned before, a well defined application has several TestCases in order to test the functionalit-ies of your application. However, we realize that soemtimes it is a tedious work to perform a integrated test liketo acces to a database or create a Spring Bean Factory, because we have to perfom a stuff of code. Fortunately,Spring provides a base mock frmaework based in JUNit3 to easily dealing with Spring applications and Nex-Open has extended these classes in order to provide a base start for NexOpen applications based in Hibernate.

A typical JUnit3 test, based in Hibernate3, of a ServiceComponent which has integrated a simple database aHSQLDB, it is as follows

....import org.nexopenframework.persistence.hibernate3.AnnotationLocatorSessionFactoryBean;import org.nexopenframework.persistence.hibernate3.test.AbstractHibernateTransactionalTests;import org.springframework.orm.hibernate3.LocalSessionFactoryBean;

/**

Persistence Manager

NexOpen 0.4.0 64

* <p>example using NexOpen</p>** <p>Base TestCase for MyAppService</p>*/

public class MyAppServiceTest extends AbstractHibernateTransactionalTests {

/** NexOpen ServiceComponent class to test*/protected MyAppService sc;/*** <p>Constructor in order to initialize custom SQL if necessary</p>*/public MyAppServiceTest() {

//put the SQL file location to initialize the data loading//if it is necessary for your test//setSqlFile("myFile.sql");

}/*** <p>Generic test method to check the main functionalities of this* ServiceComponent class. This method invokes other non-public visibility methods* which fulfills the functionalities of this ServiceComponent {@link MyAppService}</p>* TODO Implement properly this method*/public void testTestAppService() {

//start a unit of work, in other words a transactionthis.beginTransaction();//TODO call your functionalities related with this ServiceComponent

//commit unit of workthis.commitTransaction();//your can repeat this operation several times

}/*** <p>Custom initialization</p>** @see org.nexopenframework.test.AbstractTransactionalTests#onSetUpInternal()*/protected final void onSetUpInternal() throws Exception {

this.sc = new MyAppService();//a field of type org.nexopenframework.persistence.PersistenceManager//should exist in your ServiceComponent. Please, use NexOpen wizards if//you have compilation problemsthis.sc.pm = this.getPersistenceManager();//TODO put if necessary other suitable initialization

}/*** <p>Cleaning resources</p>** @see AbstractHibernateTransactionalTests#onTearDownAfterCommit()*/protected final void onTearDownAfterCommit() throws Exception {

//Do not remove the parent invocationsuper.onTearDownAfterCommit();//a field of type org.nexopenframework.persistence.PersistenceManager//should exist in your ServiceComponent. Please, use NexOpen wizards if//you have compilation problems{

this.sc.pm = null;this.sc = null;

}}/*** <p>Returns a custom {@link LocalSessionFactoryBean} for dealing* with auto-discovery of entities</p>** @see AbstractHibernateTransactionalTests#newLocalSessionFactoryBean()*/protected final LocalSessionFactoryBean newLocalSessionFactoryBean() {

//Do not overwrite this code unless it is necessary.//It should be present a nexopen.properties file in the classpath//in order to scan correctly the classes annotated with

Persistence Manager

NexOpen 0.4.0 65

//javax.persistence.Entity (JSR-220)return new AnnotationLocatorSessionFactoryBean();

}/*** <p>Customize initialization of the org.hibernate.SessionFactory</p>* TODO Implement if necessary handleLocalSessionFactoryBean method*/protected final void handleLocalSessionFactoryBean(LocalSessionFactoryBean lsf) {

//put here your custom code}

}

Based in this base definition, we observe that it is not necessary to configure the entities annotated with theJSR-220 annotation in the hibernate configuration files and we can focus in the business features.

Persistence Support for JUnit4 tests classes

NexOpen provides support for JUnit4 test classes for delaing with persistence.

13.9. Configuration of Persistence Module

In the beanRefContext.xml MUST exists an entry in order to ensure the use of the Persistence Module in Nex-Open applications.




<constructor-arg><list>......<value>classpath*:META-INF/spring/openfrwk-module-persistence-jdk15-auto.xml</value><value>classpath*:META-INF/spring/openfrwk-module-persistence-jee50.xml</value>.......</list></constructor-arg>......</bean>

Here, we have selected the auto-discovery EJB 3.0 entities thru Hibernate3 and the possibility of injection ofthe PersistenceManager or EntityManager in your ServiceComponents.

At end of this section, we will indeicate ho to configure use of EJB3 POJO validation support. If you plan touse the validation facilities provided by NexOpen you must be sure to define properly next entrance into bean-RefContext.xml in list defined by bean nexopen whcih appears in the previous caption

Persistence Manager

NexOpen 0.4.0 66

.....

<value>classpath*:META-INF/spring/openfrwk-module-persistence-validator-hibernate.xml</value>.....

You can choose between Oval support and Hibernate Validator component (at the example, we have choosenthis option, nevertheless if you would like to choose Oval framework you must use openfrwk-mod-ule-persistence-validator-oval.xml instead).

Moreover, if you are using Persistence Manager support with Hibernate3, you must also define into your hi-bernate.cfg.xml next entrance

<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE hibernate-configuration PUBLIC

"-//Hibernate/Hibernate Configuration DTD//EN""http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">

<hibernate-configuration><session-factory>.......<event type="pre-update"><listener class="org.nexopenframework.persistence.validation.event.HibernateValidatorListener"/></event><event type="pre-insert"><listener class="org.nexopenframework.persistence.validation.event.HibernateValidatorListener"/></event></session-factory>

</hibernate-configuration>

If your ORM choose has been JPA you do not need to define such entrance, because as we have mentioned be-fore you can choose the EntityListeners annotation for doing the same.

Do not forget to properly define such dependencies into your pom.xml of your business module as follows

<dependency>

<groupId>org.hibernate</groupId><artifactId>hibernate-validator</artifactId><version>3.0.0.ga</version>

</dependency><dependency>

<groupId>net.sf.oval</groupId><artifactId>oval</artifactId><version>1.0</version>

</dependency>

Persistence Manager

NexOpen 0.4.0 67

2Asynchronous Tasks

Asynchronous tasks are a kind of messaging that acts in paralel to the given request.

14.1. Main concepts

The contract in order to use the Asyncrhonous tasks is implementing the interfaceorg.nexopenframework.tasks.JobTask as follows in the given example

import org.nexopenframework.tasks.JobTask;import org.nexopenframework.tasks.JobTaskContext;import org.nexopenframework.tasks.TaskExecutionException;....public class MyJobTask implements JobTask {....

/*** <p>Asynchronous task </p>**@see JobTask#execute(JobTaskContext)*/public void execute(JobTaskContext context) throws TaskExecutionException {

....}

}

The way to invoke an asynchronous task it is as follows, notice that we can also provide a context which ispassed to the given instance.

java.util.Map context = new java.util.HashMap(2);context.put("some.value","Some value");context.put("time.now",new java.util.Date();TaskExecutor.executeTask(com.mypackage.MyJobTask.class, context);

It is important to note that the context MUST be serializable

14.2. J2SE Concurrent integration

14.3. JMS POJO integration

NexOpen 0.4.0 68

As we have observed of the before section, we only specify the JobTask to be executed and a context

14.4. Message-Driven Beans 2.x integration

If we deal with EJBs we should configure properly the DD (the ejb-jar.xml) in order to add the Message DrivenBean from NexOpen

<message-driven>

<ejb-name>exampleTaskExecutor</ejb-name><ejb-class>org.nexopenframework.tasks.jms.MessageDrivenBeanServiceExporter</ejb-class><messaging-type>javax.jms.MessageListener</messaging-type><transaction-type>Container</transaction-type><message-destination-type>javax.jms.Queue</message-destination-type><activation-config><activation-config-property><activation-config-property-name>destinationType</activation-config-property-name><activation-config-property-value>javax.jms.Queue</activation-config-property-value>

</activation-config-property><activation-config-property>

<activation-config-property-name>acknowledgeMode</activation-config-property-name><activation-config-property-value>AUTO_ACKNOWLEDGE</activation-config-property-value>

</activation-config-property></activation-config><env-entry>

<description>Key locator for Spring beanRefContext.xml

</description><env-entry-name>bootstrap/BeanFactoryLocator</env-entry-name><env-entry-type>java.lang.String</env-entry-type><env-entry-value>nexopen</env-entry-value>

</env-entry><resource-ref>

<description>DataSource used by itunes business objects

</description><res-ref-name>jdbc/exampleDS</res-ref-name><res-type>javax.sql.DataSource</res-type><res-auth>Container</res-auth><res-sharing-scope>Shareable</res-sharing-scope>

</resource-ref></message-driven>

Moreover, we should assign the ConnectionFactory and the Queue

<bean id="connectionFactory" class="org.springframework.jndi.JndiObjectFactoryBean">

<property name="jndiName" value="jms/exampleCF"/><property name="lookupOnStartup" value="true"/><property name="resourceRef" value="true"/>

</bean><bean id="queue" class="org.springframework.jndi.JndiObjectFactoryBean">

<property name="jndiName" value="jms/exampleQ"/><property name="lookupOnStartup" value="true"/><property name="resourceRef" value="true"/>

</bean>

Asynchronous Tasks

NexOpen 0.4.0 69

And you must also assign in the DD of Application Servers the correct link between the ENC names and thenames defined in the application server

14.5. Configuration of Tasks Module

In the beanRefContext.xml MUST exists an entry in order to ensure the use of the Tasks Module in NexOpenapplications.




<constructor-arg><list>......<value>classpath*:META-INF/spring/openfrwk-module-tasks-mdb.xml</value>.......</list></constructor-arg>......</bean>

Here, we have selected MDB configuration, so it is necessary to define in the deployment descriptorejb-jar.xml, the nexOpen Message-Driven Bean MessageDrivenBeanServiceExporter.

Asynchronous Tasks

NexOpen 0.4.0 70

Part IV. The WebThis part of the reference documentation covers the NexOpen Framework's support for the presentation tier(and specifically web-based presentation tiers).

NexOpen provides several integrations with some open source projects. Moreover, it also have an integrationwith the JavaServer Faces specification

1MVC support in NexOpen

NexOpen provides integration with several MVC Frameworks but it does not provide an implementation ofsuch pattern. NexOpen team believes that exists excellent OpenSource implementations or even Standars (suchas JSR-168 Portlets or JSF) so it is much better integrate with such framework than create a new implementa-tion.

15.1. Spring MVC support

Spring MVC is the MVC Framework which is used by default in NexOpen related to presentation layer.Moreover, thanks to the architecture of Spring MVC, most of the MVC Frameworks could be easily handled bySpring.

The way that we specify to NexOpen that a class is a Spring MVC Controller is implementing directly or in-diretly from Controller and annotate properly with the UrlMapping orUrlMappings

package org.nexopenframework.web.mvc.spring.annotations;


import java.lang.annotation.Retention;import java.lang.annotation.Target;

@Target({TYPE})@Retention(RUNTIME)public @interface UrlMapping {

/**The mapped url associated to a given Controller*/String value();

}

Here, we can show you an example o use of the above mentioned annotation, we should notice, as we will men-tion before, that with this annotation, we do not need to declare any bean in any Spring XML configuration file

import java.util.HashMap;import java.util.Map;

import javax.servlet.http.HttpServletRequest;import javax.servlet.http.HttpServletResponse;

import org.nexopenframework.core.runtime.annotations.ServiceGatewayRef;import org.nexopenframework.web.mvc.spring.annotations.UrlMapping;import org.springframework.web.servlet.ModelAndView;import org.springframework.web.servlet.mvc.AbstractController;import org.springframework.web.servlet.mvc.Controller;

import com.package.facades.EasyFacade;

NexOpen 0.4.0 72

@UrlMapping("/easy.htm")public class EasyController extends AbstractController implements Controller {

/*** Proxy which hides a call to EasyFacade in a given* container. For instance, an EJB container or a POJO container such as Spring,* or even an EJB3 container could be examples of invoked containers.* Expose always your applications business methods* thru Business Facades patterns.*/@ServiceGatewayRef EasyFacade easyFacade;....

protected ModelAndView handleRequestInternal(HttpServletRequest request,HttpServletResponse response)

throws Exception {.....//return viewreturn new ModelAndView("default",model);

}....

We should mention that folowing the NexOpen nature, we do not need to register in a Spring configuration filesuch Controller. In order to fulfill this feature, you must be sure that the following context parameter element ispresent at least, in your deployment descriptor web.xml

<context-param><param-name>openfrwk.web.definitionRegistries</param-name><param-value>org.nexopenframework.web.mvc.spring.support.ControllerDefinitionRegistry</param-value>

</context-param>

15.2. Struts 1.2.x support

Struts1 is one of the most famous MVC Frameworks n JEE development. Originally, it was a revolution in thedevelopment JEE applications and became a standard. Nowdays, there are several MVC Frameworks and Strutshas loose the importance but we continous found it in JEE applications.

Spring2 offers support for Spring in seevral ways. One of them, and the prefered by NexOpen team, is thru aSpring Controller, which wraps the lifecycle of a given Servlet. In our case this servlet is the well-knownAcionServlet which is the HTTP Listener of such Framework (internally this servlet delegates to RequestPro-

cessor)

The way that we specify in NexOpen that a clas is an Struts Action is thru a J2SE 5.0 annotation such as in thefollowing example

......import javax.servlet.http.HttpServletRequest;import javax.servlet.http.HttpServletResponse;

import org.apache.struts.action.ActionForm;import org.apache.struts.action.ActionForward;import org.apache.struts.action.ActionMapping;import org.nexopenframework.core.runtime.annotations.ServiceGatewayRef;import org.nexopenframework.web.mvc.struts.annotation.Action;

MVC support in NexOpen

NexOpen 0.4.0 73

import org.nexopenframework.web.mvc.struts.annotation.Forward;

import com.mypackage.facades.EasyFacade;

@Action(path="/easy",forwards=@Forward(name ="success",path ="/WEB-INF/jsp/easy.jsp"))public class EasyAction extends org.apache.struts.action.Action {

@ServiceGatewayRef EasyFacade facade;

@Overridepublic ActionForward execute(ActionMapping mapping, ActionForm form,

HttpServletRequest req, HttpServletResponse resp)throws Exception {

......return new ActionForward("success");

}}


In order to ensure that we are using Struts1, we must include such dependency in our pom.xml of the web mod-ule

<dependency>

<groupId>struts</groupId><artifactId>struts</artifactId><version>1.2.9</version>

</dependency>

15.3. Struts 2.0.x support

Struts2 is a fusion of older Struts Apache Project and WebWork2 Framework.

Struts2 is a typical pull-MVC (or MVC2) framework; slightly different from the tradiional MVC in that actiontakes the role o model rather than controller [Roughley2006]. This Framework does not use a traditional Ser-vlet as the HTTP listener. Its architecture is based in a FilterDispatcher which is a JEE Filter for handlingthe HTTP requests

import static com.opensymphony.xwork2.Action.SUCCESS;

import org.apache.struts2.config.Result;import org.nexopenframework.core.runtime.annotations.ServiceGatewayRef;import org.nexopenframework.struts2.annotations.Action;import org.nexopenframework.struts2.dispatcher.NexOpenRequestDispatcherResult;

import com.package.facades.EasyFacade;

@Action@Result(name=SUCCESS, value="easy", type=NexOpenRequestDispatcherResult.class)public class Easy {


NexOpen 0.4.0 74

@ServiceGatewayRef EasyFacade facade;

String hello;

public String execute() {//invoke business method published in your Facade

hello = facade.getHello();return SUCCESS;

}

public String getHello() {return hello;

}

public void setHello(String hello) {this.hello = hello;

}}

It is important to notice that in order to automatically be registered into Struts2 container, your class must satis-fy one of the following rules

1. Have a JSR-175 metadata Action as the previous example

2. Class name ends with Action suffix. EasyAction for example

3. Implements com.opensymphony.xwork2.Action from WebWork2

Finally, you must not forget to register as configuration provider the class NexOpenConfigurationProvider

and be sure to be present in the root of classpath a nexopen.properties file.

Prototype nature of Struts2 Actions

At difference from the older Struts1 action classes, the new actions are created every request and must have in-formation related with teh associated page. In Struts1, every Action was a one isnatnce by classlaoder and ef-forst should be done in order to guarantee a thread-safe solution. Now, situation has changed an every request anew object is created and populated with the page information and programmer has not to be aware of concur-rent nature.


In the deployment descriptor web.xml we must ensure to define the JEE Filter responsable for dealing withstruts actions

<filter>

<filter-name>nexopen-struts2</filter-name><filter-class>org.apache.struts2.dispatcher.FilterDispatcher</filter-class><init-param>

<param-name>configProviders</param-name><param-value>org.nexopenframework.struts2.config.NexOpenConfigurationProvider</param-value>

</init-param></filter><filter-mapping>


NexOpen 0.4.0 75

<filter-name>nexopen-struts2</filter-name><url-pattern>/*</url-pattern>

</filter-mapping>

And be aware to have a struts.xml in the web resources folder which contains some constants. Here, we canalso provide optional interceptors and dealing with custom packages

<?xml version="1.0" encoding="UTF-8" ?><!DOCTYPE struts PUBLIC

"-//Apache Software Foundation//DTD Struts Configuration 2.0//EN""http://struts.apache.org/dtds/struts-2.0.dtd">

<struts>

<constant name="struts.action.extension" value="do"/><constant name="struts.devMode" value="false" />

<constant name="struts.enable.DynamicMethodInvocation" value="false"/><constant name="struts.objectFactory" value="nexopen" />

</struts>

In order to fulfill correctly all the above mentioned, you must include the following lines into your pom.xml(preferly in the web component module if you follow a j2ee maven2 structure)

<dependency><groupId>org.nexopenframework</groupId><artifactId>openfrwk-struts2-jdk15</artifactId><version>0.4.0</version>

</dependency><dependency>

<groupId>org.apache.struts</groupId><artifactId>struts2-core</artifactId><version>2.0.9</version>

</dependency>


NexOpen 0.4.0 76

2Pagination support

16.1. ValueList integration

Pagination is a typical feature that appears often in JEE developments. Such feature has been also documentedas a JEE Core Pattern [Alur2003] called ValueList. Fortunately, ValueList Open Source project has imple-mented this pattern and provides several ways to integrate it. Moreover, it provides integration with SpringFamework for dealing a bean oriented programming style. Nevertheless, in NexOpen we think that things couldbe even more easy and we have tried avoiding several written of spring configuration files. Then, we havedefined package annotations that could be easily to define the paginations of your application

package org.nexopenframework.web.vlh.annotations;

import static java.lang.annotation.ElementType.PACKAGE;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;import java.lang.annotation.Target;

import net.mlw.vlh.ValueListAdapter;

import org.nexopenframework.web.annotations.Property;

@Target({TYPE,PACKAGE})@Retention(RUNTIME)@Inherited@Documentedpublic @interface ValueList {

/**identifier name of the related valuelist*/String name();/**default number per page. Default value <code>20</code>*/int defaultNumberPerPage() default 20;/**default sort column*/String defaultSortColumn() default "";/**default sort direction. Default value <code>asc</code>*/String defaultSortDirection() default "asc";/**the query*/Query query();/**custom properties of the adapter*/Property[] properties() default {};/**type of adapter*/AdapterType adapter() default AdapterType.PERSISTENCE_MANAGER_ADAPTER;/**adapter class. Only used in case {@link AdapterType#FACADE_ADAPTER}*/Class<? extends ValueListAdapter> adapterClass() default ValueListAdapter.class;/**setters for custom behaviour*/Setter[] setters() default {};

}

NexOpen 0.4.0 77

Besides, it exists a holder of valueList called ValueLists for more than one pagination in your application.These annotations must be located into a special class called package-info.java in your web module, as itshows the next example

@ValueList(name = "persons", defaultNumberPerPage = 5,defaultSortColumn = "creationDate",query = @Query(value = "FROM Person as p WHERE 1=1" +

"/~personName: AND p.name LIKE {personName}~/ " +"/~personFirstName: AND p.firstName LIKE {personFirstName}~/ "+"/~personSecondName: AND p.secondName LIKE {personSecondName}~/",

//match mode AnyWhere in the query.//see org.nexopenframework.persistence.criterion.MatchMode.ANYWHEREmatchMode=MatchModeType.ANYWHERE, columns={"personName", "personFirstName",

"personSecondName"}) ,properties = {@Property(name = "removeEmptyStrings", value = "true")})

package org.nexopenframework.samples.simple.info;

import org.nexopenframework.web.annotations.Property;import org.nexopenframework.web.vlh.annotations.MatchModeType;import org.nexopenframework.web.vlh.annotations.ValueList;import org.nexopenframework.web.vlh.annotations.Query;

16.1.1. ValueList Supported Adapters

NexOpen has extended the ValueList AbstractValueListAdapter in order to support PersistenceManagerqueries. Nevertheless, this solution and other adopted by ValueList breaks the traditional organization of layersin a JEE development. It is mainly done beacuase we query results from the presentation layer and no from abusiness layer. This is no dramatic but this solution does not scale at all.


<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="....">

......<bean id="valueListHandler"

class="org.nexopenframework.web.vlh.DefaultValueListHandlerImpl"><description>Declare different value lists</description><property name="config.adapters"><map>

</map></property>

</bean><bean id="exporter"

class="org.nexopenframework.web.vlh.support.ValueListExporter"><description>Exported for delaing with ValueList Adapters</description><property name="valueListAdapterResolver"

ref="valueListAdapterResolver" />

Pagination support

NexOpen 0.4.0 78

</bean><bean id="valueListAdapterResolver"

class="org.nexopenframework.web.vlh.support.AnnotationValueListAdapterResolver"><property name="packageName" value="org.nexopenframework.samples.simple.info" />

</bean>

<bean id="valueListConfig" class="net.mlw.vlh.web.ValueListConfigBean"><description>List style definition</description><property name="styleCount">

<value>2</value></property><property name="stylePrefix">

<value>valueListTableLook</value></property><property name="displayHelper">

<bean class="net.mlw.vlh.web.util.ImagesHomeDisplayHelper"/></property><property name="messageSource"><bean class="org.springframework.context.support.ResourceBundleMessageSource">

<description>Declare properties file</description><property name="basename">

<value>valueListTableLook</value></property>

</bean></property><property name="displayProviders"><map><entry key="html">

<bean id="valueListTableLookHtmlDisplayProvider"class="net.mlw.vlh.web.tag.support.HtmlDisplayProvider"><description>

HTML displaying configurations</description><property name="imageHome">

<value>img/valueList</value></property><property name="preAppendContextPath" value="true"/>

</bean></entry>

</map></property>

</bean>.....

Pagination support

NexOpen 0.4.0 79

3AJAX support

Nowdays, when we design a framework it is unreasoable not support the new features of Web 2.0. NexOpen, inits aim to provide easy solutions for such common tasks, offers an integration with Direct Web Remoting ( ht-tp://getahead.org/dwr ), a popular and powerful open source library for AJAX in Java.

17.1. DWR integrationNexOpen Framework, in its 0.4 version, integrates with DWR 2.0.1, exposing all the desired business layer lo-gic to AJAX requests performed from web pages, but following the same phillosophy that in all other callsdone from the presentation tier to the business layer, using the chain of all possible invokers described in theChapter Service Gateway, from the Part II Business Tier. DWR integration can be found in the web module ofNexOpen 0.4, so this one has to be added in the project's modules in order to offer AJAX features.


The DWR functionality is ready to use if you check the related component checkbox while creating a newproject using the NexOpen IDE (while selecting the desired project facets, under Web Components -> DWRComponent).

In case the NexOpen IDE is not available, some manual configurations should be done:

1. Add dependencies to the required modules.

As said before, the NexOpen web module must be added as dependency to have DWR features available. Alsothe DWR itself must be added as dependency. The pom.xml file of the desired web project must include, a partfrom the NexOpen web module, then the dependency:

<dependency><groupId>org.directwebremoting</groupId><artifactId>dwr</artifactId><version>2.0.1</version>

</dependency>

2. Specify the servlet handling ajax requests.

The NexOpen philosophy is to have all requests served by a unique servlet, and this delegating to the properhandler adapter. Then, the first thing is to have all DWR queries routed to the NexOpen servlet. This can beconfigured in the web.xml file as it follows:

<servlet-mapping><servlet-name>nexopen</servlet-name><url-pattern>/dwr/*</url-pattern>

</servlet-mapping>

NexOpen 0.4.0 80

3. Specify the controller class that will handle every DWR request.

In the nexopen-servlet.xml file, an instance of DWRController has to be declared through its own xml tag, andthen DWR requests should be routed to it, for example, with a Spring's SimpleUrlHandlerMapping.

<dwr:controller id="dwrController" debug="true"/><dwr:creator id="nexOpen"

class="org.nexopenframework.web.dwr.creator.DWRServiceGatewayCreator"/></dwr:init>

</dwr:configuration>

5. Add the custom SpringConfigurator.

Due some problems in the way DWR integrates with SpringFramework, a specific SpringConfigurator has tobe declared, in order to get the business objects created with the NexOpen creator correctly configured.

<bean id="__dwrConfiguration"class="org.nexopenframework.web.dwr.support.SpringConfigurator"><description>In order to inject the params into the creators, we shouldextend it in order to deal properly

AJAX support

NexOpen 0.4.0 81

</description></bean>

With this steps, the web module will be configured to allow web pages make ajax calls to business methods.Let's see how to implement them.

17.2. Simple AJAX calls

To handle simple AJAX calls where web pages ask for information to server without reloading, business logicmust me implemented as is usually done in NexOpen projects, creating business services that expose its meth-ods to the web layer through a facade interface and its implementation.

Once the business is implemented, the desired methods to be used from webpages must registered in the dwrconfiguration section, the place where the NexOpen creator was declared.

<dwr:configuration><dwr:init><dwr:creator id="nexOpen"

class="org.nexopenframework.web.dwr.creator.DWRServiceGatewayCreator"/></dwr:init><dwr:create javascript="AjaxService" type="nexOpen"><dwr:param name="businessService"

value="org.nexopen.samples.facades.TestDWRFacade"/><dwr:param name="invokers" value="EJBRemote" /><dwr:param name="jndiName" value="ejb/serviceGateway" /><dwr:param name="resourceRef" value="true" />

<dwr:include method="getTestInfo"/></dwr:create>

</dwr:configuration>

As seen, all that has to be done is to declare "dwr:create" sections, were the business objects are declared, givena name to be accessed from javascript and specify that they will use NexOpen's custom creator. The invocationparameters should be configured here, specifying the invokers to be used, as a comma separated string of val-ues, between the offered possibilities (pojo,EJBLocal,EJBRemote), as when declaring the invokers for regularservices.

Due the DWR SpringFramework limitations noted before, the SpringConfiguration bean definition has to beupdated with the new business object entry. An entry for every object being exposed must be added in the cre-ators section, referencing the given javascript name, preceded by a "__".

<bean id="__dwrConfiguration"class="org.nexopenframework.web.dwr.support.SpringConfigurator"><description>In order to inject the params into the creators, we shouldextend it in order to deal properly

</description><property name="creators"><map>

<entry><key><value>TestFacade</value></key><ref bean="__AjaxService" />

</entry></map>

</property></bean>

AJAX support

NexOpen 0.4.0 82

The business class is specified using the "dwr:param" with "businessService" as name and from here, just de-clare which methods should be made public.

With this configuration it will be possible to import a TestDWRFacade.js from a web page, which will have aninstanced TestDWRFacade JavaScript object where all the methods defined as included will be accessible. Anoutline of a web page using it:

<html><head><script type="text/javascript" src="dwr/engine.js"></script><script type="text/javascript"

src="/your_web_app/dwr/interface/AjaxService.js"></script><script type="text/javascript" language="JavaScript">

function ajaxTest(){AjaxService.getTestInfo(handlerExample);

}

function handlerExample(recievedData){alert(recievedData);

}</script>

</head><body onload="javascript:ajaxTest();">Ajax call on load!

</body></html>

17.3. Reverse AJAX calls

In the previous point it's been described how to do a typical AJAX call from a web page, but DWR allows to doit in the inverse, generating events from server side and notifying the browser about them. NexOpen extendsthis feature, allowing this reverse calls to be made not only from the web layer in your application, but from thebusiness one, where those events can be generated due complex business methods, scheduling events, work-flow transitions...

For an application to be able to publish those events from the business module in an application, two thingsmust be configured in the nexopen-servlet.xml file under WEB-INF folder. Make sure also that the parameter"activeReverseAjaxEnabled" is set to true in the DWRController.

...<dwr:controller id="dwrController" debug="true">

<dwr:config-param name="activeReverseAjaxEnabled" value="true"/></dwr:controller>



<bean id="ajaxNotifier"class="org.nexopenframework.web.dwr.AjaxNotifier"><description>

Bean used to send AJAX notifications to browser</description><dwr:remote javascript="AjaxNotifier"/><property name="eventExecutorRegistry">

<bean id="eventExecutorRegistry"class="org.nexopenframework.web.dwr.EventExecutorRegistry">

</bean></property>

</bean>

<bean id="__dwrConfiguration"

AJAX support

NexOpen 0.4.0 83

class="org.nexopenframework.web.dwr.support.SpringConfigurator"><description>In order to inject the params into the creators, we shouldextend it in order to deal properly

</description><property name="creators"><map><entry>

<key><value>AjaxNotifier</value></key><ref bean="__AjaxNotifier" />

</entry></map></property>

</bean>...

Here, the AjaxNotifier bean, that will recieve the events generated in the application and also, like in the simpleajax calls, to add the bean in the SpringConfigurator section, with the preceding "__". Remember to program animplementation of org.nexopenframework.web.dwr.AjaxEventExecutor, which is the class that really willknow what to do with the given org.springframework.context.ApplicationEvent subclasses that the applicationfires. AjaxEventExecutor's don't need to be declared in any configuration files, NexOpen framework willautodiscover them.

The usual way to manage this would be defining a hierarchy of org.springframework.context.ApplicationEventclasses, related to the application business and purposes. Every instance of the objects in this hierarchy shouldhandle the information willing to be notified. This object would be then published using theorg.nextret.openfrwk.context.event.EventDispatcher static class, that will send the event to the Spring Applica-tionContext. The event will reach then the executor implemented from the interfaceorg.nexopenframework.web.dwr.AjaxEventExecutor, and call its execute method, recieving as parameters thepublished event and the DWR ServerContext implementation. The later has all methods needed to connect fromthe server to the client browser, so information can be extracted from the former and sent to the client to get thejob done.

...public class NotificationEventExecutor implements AjaxEventExecutor {

public void execute(ApplicationEvent event, ServerContext sCtx){// Get all browser connected sessionsCollection sessions = sCtx.getAllScriptSessions();Util dwrUtil = new Util(sessions);// Build the javascript actionScriptBuffer sb = null;// For instance, our UserDefinedEvent class could have a// getClientCode method that would give us the JavaScript// code to be executed in the client browsersb = new ScriptBuffer(((UserDefinedEvent)event).getClientCode());// So add the new JavaScript to all those connected sessionsdwrUtil.addScript(sb);

}// Describe which kind of events is supporting this executorpublic boolean supports(ApplicationEvent event) {return (UserDefinedEvent.class.isAssignableFrom(event.getClass()));

}}...

Webpages wishing to handle reverse AJAX calls just will need to import he AjaxNotifier javascript to make itpossible, and remeber activating the reverese ajax feature.

<html><head>

AJAX support

NexOpen 0.4.0 84

<script type="text/javascript"src="/your_web_app/dwr/interface/AjaxNotifier.js"></script>

<script type="text/javascript">function init(){

DWREngine.setActiveReverseAjax(true);}</script></head><body onload="javascript:init();"></body>

</html>...

17.4. Extended features

NexOpen Framework provides other features added to those ones offered by default by DWR.

17.4.1. Autocomplete Tag

The framework gives it's own JSTL tag to implement a common AJAX feautre, autocompletion of text fields.To do so, it's as simple as having added the web module with AJAX support to your project and having ex-posed a facade method as described in the previous section. Then it's ready to be used in a jsp pages as it fol-lows:

<nexopenAjax:autocomplete fieldName="exampleID" remoteFunc="testRetrieveFunc"remoteObject="TestDWRFacade"options="minChars:2"><input class="beautifulTextClass" name="exampleTextField" id="exampleID" >

</nexopenAjax:autocomplete>

This example would create a textfield where, after 2 characters have been added to it, the remote functionTestDWRFacade.testRetreiveFunc would be called to suggest autocomplete suggestions.

AJAX support

NexOpen 0.4.0 85

4JavaServer Faces (JSF)

18.1. NexOpen and JavaServer Faces integration

TO BE DOCUMENTED

NexOpen 0.4.0 86

5Acegi Security Integration

Despite the fact that J2EE arhitecture offers a way to deal with authentication/authorization thru JAAS, almostdevelopments offers a module of security out of scope of JAAS.

19.1. Introduction

Related to security in JEE Applications, we have choosen Acegi Security Framework (see ht-tp://www.acegisecurity.org/ for more details).Thanks to its configurable architecture, we can easily plug-inamong several topologies present in common applications (Relational DataBase solutions, LDAP, Siteminder,OpenID and so on). Moreover, it is based in Spring Framework and provides a well-stablished architecture fordealing with security issues.

We have extended some prop

19.2. Relational Database Support

This is the most traditional way to deal with authentication/authorization.

19.2.1. User-Group-Role model

We propouse a typical relation among users, roles and groups

In NexOpen, we have developed a generic implementation in order to deal with a ORM Frameworks (such asHibernate3, where we have developed the mapping files and included into the jar file under META-INF/hibernate)

19.2.2. General Configuration

Here, we will guideline the general configuration in order to integrate with Acegi and NexOpen security. First,we must ensure that in the pom.xml in the module web is present the acegi dependency and nexopen securitycore

<dependency>

<groupId>org.acegisecurity</groupId><artifactId>acegi-security</artifactId><version>1.0.4</version><exclusions>

<exclusion><groupId>org.springframework</groupId><artifactId>spring-remoting</artifactId>

</exclusion><exclusion>

NexOpen 0.4.0 87

<groupId>org.springframework</groupId><artifactId>spring-jdbc</artifactId>


<groupId>org.springframework</groupId><artifactId>spring-support</artifactId>


<groupId>org.springframework</groupId><artifactId>spring-mock</artifactId>


<groupId>commons-logging</groupId><artifactId>commons-logging</artifactId>


<groupId>commons-lang</groupId><artifactId>commons-lang</artifactId>


<groupId>commons-collections</groupId><artifactId>commons-collections</artifactId>


<groupId>ehcache</groupId><artifactId>ehcache</artifactId>


</dependency><dependency>

<groupId>org.nexopenframework</groupId><artifactId>openfrwk-security-core</artifactId><version>${nexopen.version}</version><exclusions>

<exclusion><groupId>org.springframework</groupId><artifactId>spring-support</artifactId>


</dependency><dependency>

<groupId>org.nexopenframework</groupId><artifactId>openfrwk-security-jdk15</artifactId><version>${nexopen.version}</version>

</dependency>

And you must not forget to put the dependency of the security model in your pom.xml of the business module,because we need the definitions of the User-Role-Group interfaces, support classes, integration with other mod-ules and so on.

<dependency><groupId>org.nexopenframework</groupId><artifactId>openfrwk-security-model</artifactId><version>${nexopen.version}</version>

</dependency>

Moreover, you must have present the Acegi Filter into you deployment descriptor web.xml. this filter representsa chain of filters managed inside the Spring IoC which provides several features such authenication, authoriza-tion and otehr features (see Acegi reference guide for more details)

Acegi Security Integration

NexOpen 0.4.0 88

<filter><filter-name>Acegi Filter Chain Proxy</filter-name><filter-class>org.acegisecurity.util.FilterToBeanProxy</filter-class><init-param>

<param-name>targetClass</param-name><param-value>org.acegisecurity.util.FilterChainProxy</param-value>

</init-param></filter><filter-mapping>

<filter-name>Acegi Filter Chain Proxy</filter-name><url-pattern>/*</url-pattern>

</filter-mapping>

We must also add the follwoings beans into the applicationContext.xml located at web module under the WEB-INF folder.

<bean id="web.propertyConfigurer"class="org.nexopenframework.spring.config.PropertyPlaceholderConfigurer"><property name="ignoreResourceNotFound" value="true"/><property name="locations">

<list><value>classpath:acegi.properties</value>

</list></property><property name="properties">

<props><prop key="acegi.secure.channel.urls">

\A.*\Z=REQUIRES_INSECURE_CHANNEL</prop>

<prop key="acegi.secure.urls">/login.jsp=ROLE_ANONYMOUS/**=ROLE_ADMIN,ROLE_USER/secure/**=ROLE_ADMIN

</prop><prop key="acegi.access.denied.url">/accessDenied.jsp</prop><prop key="acegi.authentication.failure.url">/login.jsp?login_error=1</prop><prop key="acegi.default.target.url">/index.jsp</prop><prop key="acegi.filter.process.url">/j_acegi_security_check</prop><prop key="acegi.login.form.url">/login.jsp</prop><prop key="acegi.force.https">false</prop><prop key="acegi.role.prefix">ROLE_</prop>.....

</props></property>

</bean><bean id="openfrwk.roles"

class="org.springframework.beans.factory.config.ListFactoryBean"><description/><property name="sourceList">

<list><value>ROLE_ADMIN</value>

<value>ROLE_USER</value>


NexOpen 0.4.0 89

</list></property>

</bean>

The first bean, a Spring custom property configurer, defines custom properties to be passed to the spring beansdefined in the NexOpen Acegi module files. Here, you can modify, for instance, the secure urls, the role prefix,the url form login,where to redirect if some acces is denied, which url is processed for authentication and so on.The last bean, with name openfrwk.roles, defines a list of your custom roles to be passed also to the NexOpenAcegi configuration files. Notice that the name of the bean it is inmutable and must not be changed, becauseproblems will appear at deployment time.

19.2.3. PersistenceManager support

We provide an integration between Acegi and NexOpen PersistenceManager thru the implementation of thePersistenceProvider, the class PersistenceManagerProvider. In this way, we can easily deal with authentic-ation thru a RDBMS using the NexOpen PersistenceManager interface without need of how to integrate withRDBMS.

In order to configure this module, you must add into your applicationContext.xml

<import resource="classpath:/META-INF/spring/openfrwk-module-security-authn-pm.xml"/>

Finally, we can customize some properties of the PersistenceManager implementation, such as the name(identifier) of the OQL NamedQuery (HQL, for instance), the property name of this query and if we shouldforce the initialization of collections (roles and groups for implementations of NexOpen User-Role-Group) ofthe associate entity.

....<bean id="web.propertyConfigurer"

class="org.nexopenframework.spring.config.PropertyPlaceholderConfigurer"><prop key="openfrwk.acegi.pm.queryName">myCustomLoadUser</prop><prop key="openfrwk.acegi.pm.usernameParameter">name</prop><prop key="openfrwk.acegi.pm.forceInitialization">true</prop>......

We must take into account that the query, in order to load a user MUST only accept a unique parameter, theusername and no more parameters are allowed. Examples of these queries, that could be found in a customJSR-220 user entity or in a package-info.java class, could be

@javax.persistence.NamedQueries({@javax.persistence.NamedQuery(name="myCustomLoadUserFetch",

query="select distinct cu from CustomUser cujoin fetch cu.roles roles where cu.username=:name"),

@javax.persistence.NamedQuery(name="myCustomLoadUser",


NexOpen 0.4.0 90

query="from CustomUser cu where cu.username=:name")})

Notice that one of them, the myCustomLoadUserFetch, forces the load of the roles collection, avoiding initial-ization of collections (therefore, we could put the openfrwk.acegi.pm.forceInitialization to false).

Fetch strategy in custom queries and LazyInitializationException

The fetch way, is prefered in order to avoid runtime exceptions if you do not follow the security model, fromhere we recommend this use in front lazy strategy. Moreover, if we use Hibernate3 as PersistenceManager pro-vider, we will avoid in this way the famous LazyInitializationException at runtime.

If you are using the NexOpen Hibernate implementation of the security model, you must not be worried aboutconfiguration.

19.2.4. JPA EntityManager support

In this release, we also offer an integration with JPA also implementing the PersistenceProvider as the previ-ous section.

In order to configure this module, we assume that you have defined a Spring Bean of type EntityManagerFact-ory (either local thru the FactoryBean implementations provided by Spring or found in the JNDI and con-figured in the Application Server). Moreover, you must also add into your applicationContext.xml the follow-ing import

<import resource="classpath:/META-INF/spring/openfrwk-module-security-authn-jpa.xml"/>

it represents the acegi beans integrated with JPA. As well as the previous section, we can modify some specificproperties related to JPA, as the identifier of the named query, the paramter name used in this query and if weforce or not the initialization of collections.


class="org.nexopenframework.spring.config.PropertyPlaceholderConfigurer">......<prop key="openfrwk.acegi.jpa.queryName">loadCustomUser</prop><prop key="openfrwk.acegi.jpa.usernameParameter">name</prop><prop key="openfrwk.acegi.jpa.forceInitialization">true</prop>......

Refer to previous section, for a detailed discussion about the previous properties.

@RolesCollection and Collections initialization


NexOpen 0.4.0 91

We will mention in a next section, the use of JSR-175 metadata for giving details of user features for modelswhich would not like to follow the NexOpen Security model. One of this metadata is the RolesCollection andidentifies a property as a collection of custom roles. If your custom user class, presents this annotation and youare orcing the initialization of collections, this colelction will be initialized automatically. Other collections willnot be initialized and we recommend the use of fetch strategies in order to avoid runtime exceptions.

19.2.5. Integration with externals Security models

In this integration we realize that several times, almost all applicatiosn provides a secuity model whih differsdramatically of the proposed. You have different ways. One of them is implements the User

User-Role-Group relationship as interfaces

In NexOpen we have offered a generic contrat thru interfaces for dealing with the proposed User-Role-Grouprelationship in order to easily extend to your security domain models. using interfaces easily simplifies the in-tegration with external security models, but offers constraints that sometimes are difficult to solve.

However, if you would not like to implement the above security module, you can also use the annotations forretrieving details of user, useful for Acegi. We have defined the following three annotations, that we can use atfield or method level

1. @Enabled to identify a enabled property holder.

2. @Password to identify a password property holder

3. @RolesCollection to identify a property as holder of roles collection. This annotation is not tagged as thebefore mentioned and accepts two attributes. The type attribute identifies the role class and the mapped-Name the field name of the role class.

We provide the following example for how to use the above annotations in a class

.....import org.nexopenframework.security.annotations.Enabled;import org.nexopenframework.security.annotations.Password;import org.nexopenframework.security.annotations.RolesCollection;.....@Entity@Table(name="MYAPP_USER")@NamedQuery(name="loadCustomUser", query="from User where username=:name")public class User implements Serializable {

private String password;

private boolean enabled;

private Set<Role> roles = new HashSet<Role>();

......

@Enabled@Column(name="USER_ENABLED")public boolean isEnabled() {

return enabled;}


NexOpen 0.4.0 92

@Passwordpublic String getPassword() {

return password;}

@ManyToMany@JoinTable(name="MYAPP_USER_ROLE",

joinColumns={@JoinColumn(name="ID_USER")},inverseJoinColumns={@JoinColumn(name="ID_ROLE")})

@Fetch(SUBSELECT)@RolesCollection(type=Role.class, mappedName="name")public Set<Role> getRoles() {

return roles;}....

In order to ensure, the use of these annotations, we must add the following dependency in the pom.xml of yourbusiness module

<dependency><groupId>org.nexopenframework</groupId><artifactId>openfrwk-security-annotations</artifactId><version>${nexopen.version}</version>

</dependency>

In order to configure this module, you must also add into your applicationContext.xml the following import,which includes the beans which resolves the above annotations.

<import resource="classpath:/META-INF/spring/openfrwk-module-security-userdetails.xml"/>

Finally, if you do not want to use the metadata, you can implement the interface UserDetailsResolverDeleg-

ate for resolving the user details (the annotations dependency is not bnecessary but the before import isneeded) as follows

....import org.nexopenframework.security.acegi.resolver.UserDetailsResolverDelegate;....public class MyCustomResolverDelegate implements UserDetailsResolverDelegate {

public GrantedAuthority[] getAuthorities(final Object userClass) {if (userClass instanceof MyUser) {

Set roles = ((MyUser) userClass).getRoles();GrantedAuthority[] authorities = new GrantedAuthority[roles.size()];int k= 0;final Iterator it_roles = roles.iterator();while (it_roles.hasNext()) {

final MyRole role = (MyRole) it_roles.next();authorities[k++] = new GrantedAuthorityImpl(role.getRoleName());

}return authorities;

}


NexOpen 0.4.0 93

return new GrantedAuthority[0];}

public String getPassword(final Object userClass) {if (userClass instanceof MyUser) {

final MyUser user = (MyUser) userClass;return user.getPassword();

}return null;

}

public boolean isEnabled(final Object userClass) {if (userClass instanceof MyUser) {

final MyUser user = (MyUser) userClass;return user.isEnabled();

}return true;

}

}

Afterwards, you must create spring bean into the above mentioned applicationContext.xml and define a prop-erty called openfrwk.acegi.resolver.delegate specifyng the bean name of this custom implementation


class="org.nexopenframework.spring.config.PropertyPlaceholderConfigurer">.......<prop key="openfrwk.acegi.resolver.delegate">myapp.resolver.delegate</prop>...

</bean>...<bean id="myapp.resolver.delegate" class="om.mypackage.resolver.MyCustomResolverDelegate">...

</bean>

19.3. LDAP Support

TO BE DOCUMENTED

19.4. Siteminder Support

In order to configure this module, you must add into your applicationContext.xml

<import resource="classpath:/META-INF/spring/openfrwk-module-security-auth.siteminder.xml"/>


NexOpen 0.4.0 94

19.5. OpenID Support

TO BE DOCUMENTED

19.6. Different login pages. MultiModule Acegi integration

Sometimes in the same application, we must define several login pages which are the entry point to differentparts of a given application (an example could be a generic application and its adminsitration module). AcegiFramework does not provide a way to deal this problem, but allows an easy extension for dealing with thisproblem.

NexOpen provides support for this feature and you have to follow the next steps for correct integration. First ofall, we must define the following beans related to extensions of Acegi Security Framework in the application-Contex.xml located under the WEB-INF folder in the web module. These extensions considers the existence ofdifferent modules in your application

.....<bean id="multiFilterChainProxy"

class="org.nexopenframework.security.acegi.util.FilterChainProxy"><property name="filterInvocationDefinitionSource">

<value>CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISONPATTERN_TYPE_APACHE_ANT/**=channelProcessingFilter,httpSessionContextIntegrationFilter,logoutFilter,

multiAuthenticationProcessingFilter,basicProcessingFilter,securityContextHolderAwareRequestFilter,rememberMeProcessingFilter,anonymousProcessingFilter,exceptionTranslationFilter,filterInvocationInterceptor

</value></property>

</bean><bean id="multiAuthenticationProcessingFilter"

class="org.nexopenframework.security.acegi.ui.webapp.MultiModuleAuthenticationProcessingFilter" ><description></description><property name="authenticationManager" ref="authenticationManager"/>

<property name="authenticationFailureUrl"><value>${acegi.authentication.failure.url}</value>

</property><property name="defaultTargetUrl">

<value>${acegi.default.target.url}</value></property><property name="filterProcessesUrl">

<value>${acegi.filter.process.url}</value></property><property name="alwaysUseDefaultTargetUrl" value="${acegi.always.use.defaultTargetUrl:false}"/><property name="rememberMeServices" ref="rememberMeServices"/>

</bean><bean id="multiAuthenticationProcessingFilterEntryPoint"

class="org.nexopenframework.security.acegi.ui.webapp.MultiModuleAuthenticationProcessingFilterEntryPoint"><property name="loginFormUrl">

<value>${acegi.login.form.url}</value></property><property name="forceHttps">


NexOpen 0.4.0 95

<value>${acegi.force.https}</value></property><property name="serverSideRedirect" value="${acegi.serverSide.redirect:false}"/>

</bean><bean id="moduleResolver" class="org.nexopenframework.security.acegi.ui.ModuleResolver">

<property name="modules"><list><value>admin</value>

</list></property>

</bean>......

In this example we have consider only one module called admin. Afterwards, we must also define the followingproperty belonging to the property of bean PropertyPlaceholderConfigurer in the above mentioned applica-tionContex.xml

.....<bean

class="org.nexopenframework.spring.config.PropertyPlaceholderConfigurer"id="web.propertyConfigurer"><property name="ignoreResourceNotFound" value="true"/><property name="locations">

<list><value>classpath:acegi.properties</value>

</list></property><property name="properties">

<props>......<prop key="acegi.auth.processor.entryPoint">

multiAuthenticationProcessingFilterEntryPoint</prop>......

</proeprty></bean>......

and you must not forget to declare as ROLE_ANONYMOUS the page where the login is located (also located inthe previous PropertyPlaceholderConfigurer bean)

......<prop key="acegi.secure.urls">

/login.jsp=ROLE_ANONYMOUS/admin/tttlogin.jsp=ROLE_ANONYMOUS

......

In the deployment descriptor, we must also define the param targetBean with the suitable spring bean name,with contains the filter chain with the new authentication filter for multimodule environments


NexOpen 0.4.0 96

......<filter><filter-name>Acegi Filter Chain Proxy</filter-name><filter-class>

org.acegisecurity.util.FilterToBeanProxy</filter-class><init-param><param-name>targetBean</param-name><param-value>multiFilterChainProxy</param-value></init-param>

</filter><filter-mapping>

<filter-name>Acegi Filter Chain Proxy</filter-name><url-pattern>/*</url-pattern>

</filter-mapping>.......

The structure of your project must be as follows concerning the location of your JSPs, look at the presence of afolder at root level with the same name that the modules defined and with two JSP's (index.jsp and login.jsp).Moreover, we must create another folder inside WEB-INF/jsp where we will locate the JSPs related to thismodule. This operation must be repited for each new module you define

webapp|+admin|+index.jsp|+login.jsp

|+css|+img|+js|+WEB-INF

|+jsp|+welcome.jsp....|+admin|+welcome.jsp......

|+web.xml|+applicationContext.xml.....

|+index.jsp|+login.jsp


NexOpen 0.4.0 97

6Web Services

Nowdays, integration features is one of the most common features in the JEE applications. Web Servicesprovides a way to integrate with third party aplications. In this section, we will speak about how NexOpen sup-ports developemnt of Web Services and the libraries supported.

20.1. Introduction

20.2. NexOpen and XFire integration

Use of XFire metadata

XFire provides several annotations for dealing with common features in development. using this annotations,you can enhace the XFire Handler Chain.

20.3. NexOpen and CXF integration

20.4. NexOpen and Axis2 integration

TO BE DOCUMENTED

20.5. Configuration

In case of XFire integration

<bean id="nexopen.web.propertyConfigurer"

class="org.nexopenframework.spring.config.PropertyPlaceholderConfigurer"><property name="ignoreResourceNotFound" value="true" /><property name="properties">

<props><prop key="openfrwk.xfire.alwaysUseFullPath">true</prop>

NexOpen 0.4.0 98

</props></property>

</bean>

Moreover, you also mut provide an XFire Annotations processor for JSR-181 metadata

<bean id="webAnnotations"

class="org.codehaus.xfire.annotations.jsr181.Jsr181WebAnnotations" />

Web Services

NexOpen 0.4.0 99

7Signature Module

21.1. Introduction

21.2. Apache Signature implementation

21.3. JSR-105 implementation

21.4. Configuration

NexOpen 0.4.0 100

8Serialization Module

Serialization of XML data is one of the features common in JEE developments. From Web Services followingSOAP specification to modern XML-protocol REST services thru a transport (such as HTTP or JMS) mar-shalling and unmarshalling has been an important feature for perfomance in your applications. This moduletries to solve in a common API such as

22.1. Introduction

As we have mentioned before, serialization of structured data in XML format is an important feature to be dealwith modern applications which would like to be integrated by third-party applications (the well-known EAI,Enterprise Application Integration).

22.2. Marshaller implementation location in cient side

In order to retrieve the implemented Marshaller, we can use the MarshallerHolder a custom class which keepsan instance of the thread-safe Marshaller (internally, teh first time lookups inside the Spring BeanFcatory)

....import org.nexopenframework.xml.binding.client.MarshallerHolder;....final Marshaller marshaller = MarshallerHolder.getMarshaller();//do marshalling stuff....

This class assumes, that you are doing your marshalling process into the presentation layer. finally, in order toproperly use this class, you must declare into a Spring XML configuration file

<bean id="marshaller.holder"

class="org.nexopenframework.xml.binding.client.MarshallerHolder"><description>Holder of the Marshaller</description>

</bean>

22.3. XStream implementation

XStream is a powerful and easy-to-use API for marshalling the data.

NexOpen 0.4.0 101

Use of XStream J2SE 5.0 annotations

22.3.1. Extension of XStream functionalities

<bean id="aliasMapper"

class="org.nexopenframework.xml.binding.xstream.support.AliasMapper"><description>The alias for custom xml file</description><property name="alias"><map><entry key="key" value="com.mypackage.xstream.mapper.KeyType"/><entry key="true" value="com.mypakage.xstream.mapper.BooleanType"/><entry key="data" value="com.thoughtworks.xstream.mapper.Mapper$Null"/>

</map></property>

</bean><bean id="converterList"

class="org.nexopenframework.xml.binding.xstream.support.ConverterList"><description>A converter list for custom xml file</description><property name="converters">

<list><bean class="com.mypackage.xstream.converters.MyCustomConverter"/><bean class="com.mypackage.xstream.converters.DataConverter"/><bean class="com.thoughtworks.xstream.converters.extended.ISO8601DateConverter"/>

</list></property>

</bean><bean id="annotatedClassList"

class="org.nexopenframework.xml.binding.xstream.support.AnnotatedClassList"><description>A converter list for custom xml file</description><property name="topLevelClasses">

<list><value>com.mypackage.model.PropertyList</value><value>com.mypackage.DateAttribute</value>

</list></property>

</bean>


In the applicationContext.xml

....<import resource="classpath:/META-INF/spring/openfrwk-module-serialization-xstream.xml"/>

Serialization Module

NexOpen 0.4.0 102

22.4. XMLBeans implementation

XMLBeans is a powerful Framework of marshalling/unmarshalling started by Bea WebLogic an donated toApache Foundation.

22.5. XServices

In NexOpen we offer a way to handle with structured data thru HTTP transport, the XServices. Roughly speak-ing an XService, is a command which is associated to a given URI and ofers an easy way to speak with the ser-vice components of your application.

22.6. NexOpen and JAXB2

Related to serialization and standards, Sun proposed JAXB as the standard way to mrshalling structured data.The new version, JAXB2, also offers support for J2SE 5.0 annotations and it is used in the new specification ofJAX-WS 2.0 when we speak about document/literal web services. This specification also belongs to JEE 5.0spec.

Serialization Module

NexOpen 0.4.0 103

Part V. Sample applicationsThis final part of the reference documentation covers the sample applications that come with the NexOpenFramework distribution. In this release we provide the simple application as an example of how to use Nex-Open in your JEE applications.

1Simple application

23.1. Introduction

The NexOpen Framework distribution provides the Simple JEE application, which it is an enterprise applica-tion using Maven2 as the dependency and build manager and it has been tested in J2EE 1.4 complaint Applica-tion Servers such as JBoss 4.0.x and Bea WebLogic 9.2. Presents a simple appeareance, but under scenes showsall the main modules of NexOpen Framework. The main idea it is to provide an startup point for develoeprswhich would like to be involved with NexOpen. We enumerate the main modules present in this application

1. Service Component Architecture. It presents all the service components that NexOpen defines, such as anBusiness Facade, Application Service and (Configurable) Services.

2. Persistence Manager. It shows the main methods that a developer use thru the PersistenceManager

3. Asynchronous Tasks. It exhibits a Message-Driven Bean 2.x fully configured and transaprent for de-velopers

4. Spring MVC integration. We provide several controllers using Spring MVC but annotated in order toavoid tconfiguration of XML files.

5. AJAX support. We use the DWR framework for delaing with AJAX. Moreover, we provide an example ofAJAX reverse, which they are notificactions from the a EJB container to a WEB container.

23.2. Simple and the business and resource layer

23.3. Simple and the presentation layer

23.4. Build and deployment

NexOpen 0.4.0 105

AInstrumentation Phase

A.1. Introduction

NexOpen follows the philosophy to avoid complex developments offering a weaving module which translatesspecific classes into fulfill components of framework. Even more, we can perfectly create new JEE managedcomponents in an easy and transparent way.

A.2. Configuration

Instrumentation module offers a ANT task in order to instrument the bytecode generated by your application. InMaven2, we usually configure in the pom.xml of business module

<tasks><echo>Running NexOpen Framework Instrumentation tools</echo><mkdir dir="${basedir}/target/generated-sources/javassist"/><taskdefclassname="org.nexopenframework.instrument.javassist.tools.JavassistInstrumentorEngineTask"name="instrument"/><instrument criticaltime="600"

destdir="${basedir}/target/generated-sources/javassist"dir="${basedir}/target/classes"verbose="true" writefile="true">

<include name="**/*.class"/><transformerclassname="org.nexopenframework.instrument.javassist.transformers.ServiceCtClassTransformer"/>

<transformerclassname="org.nexopenframework.instrument.javassist.transformers.BusinessCtClassTransformer"/>

<transformerclassname="org.nexopenframework.instrument.javassist.transformers.LoggingCtClassTransformer"/>

<transformerclassname="org.nexopenframework.instrument.javassist.transformers.HACtClassTransformer"/>

</instrument></tasks>....

A.3. Configuration in JEE 5.0

If we want to deploy our application into any JEE 5.0 Application Server and Facades being EJB 3.0 StatelessSession Bean, we must include the following transformers into the previous list

....<instrument criticaltime="600"

NexOpen 0.4.0 106

destdir="${basedir}/target/generated-sources/javassist"dir="${basedir}/target/classes"verbose="true" writefile="true">

<include name="**/*.class"/>.....<transformerclassname="org.nexopenframework.instrument.javassist.transformers.InterceptorCtClassTransformer"/>

<transformerclassname="org.nexopenframework.instrument.javassist.transformers.EJB3CtClassTransformer"/>

</intrument>......

A.4. Frequently Asked Questions

if you have moved from a 0.3.x version to a 0.4.x version or higher, you can find this ugly error

java.lang.NoClassDefFoundError: org/nexopenframework/instrument/annotations/UnInstrumentableat org.nexopenframework.instrument.javassist.AnnotationsUnInstrumentableSupport.isUnInstrumentableat org.nexopenframework.instrument.javassist.CompositeUnInstrumentableSupport.isUnInstrumentableat org.nexopenframework.instrument.javassist.JavassistInstrumentorEngine.instrumentClassat org.nexopenframework.instrument.tools.InstrumentorEngineTask.execute(InstrumentorEngineTask.java:99)at org.apache.tools.ant.UnknownElement.execute(UnknownElement.java:275)at org.apache.tools.ant.Task.perform(Task.java:364)at org.apache.tools.ant.Target.execute(Target.java:341)at org.apache.maven.plugin.antrun.AbstractAntMojo.executeTasks(AbstractAntMojo.java:108)at org.apache.maven.plugin.antrun.AntRunMojo.execute(AntRunMojo.java:83)at org.apache.maven.plugin.DefaultPluginManager.executeMojo(DefaultPluginManager.java:412)at org.apache.maven.lifecycle.DefaultLifecycleExecutor.executeGoals(DefaultLifecycleExecutor.java:534)at org.apache.maven.lifecycle.DefaultLifecycleExecutor.executeGoalWithLifecycle(DefaultLifecycleExecutor.java:475)at org.apache.maven.lifecycle.DefaultLifecycleExecutor.executeGoal(DefaultLifecycleExecutor.java:454)at org.apache.maven.lifecycle.DefaultLifecycleExecutor.executeGoalAndHandleFailures(DefaultLifecycleExecutor.java:306)at org.apache.maven.lifecycle.DefaultLifecycleExecutor.executeTaskSegments(DefaultLifecycleExecutor.java:273)at org.apache.maven.lifecycle.DefaultLifecycleExecutor.execute(DefaultLifecycleExecutor.java:140)at org.apache.maven.DefaultMaven.doExecute(DefaultMaven.java:322)at org.apache.maven.DefaultMaven.execute(DefaultMaven.java:115)at org.apache.maven.cli.MavenCli.main(MavenCli.java:256)at org.maven.ide.eclipse.ext.embedder.Maven2Executor.main(Maven2Executor.java:106)

This is done due the fact of introduction of a new module which deals with annotations for instrumentation pur-poses in the service components classes. This ugly exception it is easily solved putting the corresponding de-pedency with this module into the Maven2 ant plugin in the pom.xml of business module

...<build>

<plugins><plugin>

<groupId>org.apache.maven.plugins</groupId><artifactId>maven-antrun-plugin</artifactId><executions><execution><phase>process-classes</phase><configuration>

<tasks><echo>Running NexOpen Framework Instrumentation tools</echo>

Instrumentation Phase

NexOpen 0.4.0 107

<mkdir dir="${basedir}/target/generated-sources/javassist"/><taskdef name="instrument"

classname="....."/><instrument dir="${basedir}/target/classes"

destdir="${basedir}/target/generated-sources/javassist"verbose="true" writefile="true"criticaltime="600">

<include name="**/*.class"/><transformer classname="org.nexopenframework.instrument.javassist.transformers.ServiceCtClassTransformer"/>......

</instrument><copy todir="${basedir}/target/classes"><fileset dir="${basedir}/target/generated-sources/javassist"/>

</copy></tasks>

</configuration><goals>

<goal>run</goal></goals>

</execution></executions><dependencies><dependency><groupId>org.nexopenframework</groupId><artifactId>openfrwk-instrument-annotations</artifactId><version>${nexopen.version}</version>

</dependency>......

If you put this dependency into the dependencies plugin, it is automatically solved the previous exception

Another ugly exception which could appears it is the following

Caused by: Problem Instrumenting class name com/mypackage/tasks/LoaderTask.classat org.nexopenframework.instrument.tools.InstrumentorEngineTask.execute(InstrumentorEngineTask.java:104)at org.apache.tools.ant.UnknownElement.execute(UnknownElement.java:275)at org.apache.tools.ant.Task.perform(Task.java:364)at org.apache.tools.ant.Target.execute(Target.java:341)at org.apache.maven.plugin.antrun.AbstractAntMojo.executeTasks(AbstractAntMojo.java:108)... 12 more

Caused by: org.nexopenframework.instrument.ClassTransformationException:javassist.NotFoundException: org.nexopenframework.tasks.JobTaskat org.nexopenframework.instrument.javassist.DefaultUnInstrumentableSupport.isUnInstrumentable(DefaultUnInstrumentableSupport.java:51)at org.nexopenframework.instrument.javassist.CompositeUnInstrumentableSupport.isUnInstrumentable(CompositeUnInstrumentableSupport.java:46)at org.nexopenframework.instrument.javassist.JavassistInstrumentorEngine.instrumentClass(JavassistInstrumentorEngine.java:198)at org.nexopenframework.instrument.tools.InstrumentorEngineTask.execute(InstrumentorEngineTask.java:99)... 16 more

Caused by: javassist.NotFoundException: org.nexopenframework.tasks.JobTaskat javassist.ClassPool.get(ClassPool.java:301)at javassist.CtClassType.getInterfaces(CtClassType.java:393)at org.nexopenframework.instrument.javassist.DefaultUnInstrumentableSupport.isUnInstrumentable(DefaultUnInstrumentableSupport.java:40)... 19 more

This exception is related to a dependency not found by the classloader of instrumentation and it is solved in tehsame way as before, putting the dependency into the Maven2 ant plugin

Instrumentation Phase

NexOpen 0.4.0 108

BException Handling

B.1. Introduction

Exception Handling has been one of the most common modules developed in JEE applications. Traditional de-velopments has expend several time trying to handle in a custom way, the exceptions which might occurs inyour application

B.2. Exception Handling in Business Components

In business components (our serice components), we declare a method level, using the annotations Exception-

Handler as follows


import static java.lang.annotation.ElementType.METHOD;import static java.lang.annotation.RetentionPolicy.RUNTIME;


@Target(METHOD) @Retention(RUNTIME)public @interface ExceptionHandler {

/**the exception type*/Class<? extends Throwable> type() default Throwable.class;/**severity related to this excption*/SeverityType severity() default SeverityType.ERROR;/**message to be included in the exception handler framework*/String message() default "";

}

and ExceptionHandlers for declaring a set of exceptions handlers


import static java.lang.annotation.ElementType.METHOD;import static java.lang.annotation.RetentionPolicy.RUNTIME;


@Target(METHOD) @Retention(RUNTIME)public @interface ExceptionHandlers {

ExceptionHandler[] value();}

NexOpen 0.4.0 109

Look at the following exemple, in order how to use the above mentioned metadata

import org.nexopenframework.core.annotations.ExceptionHandler;import static org.nexopenframework.core.annotations.SeverityType.ERROR;import static org.nexopenframework.core.annotations.SeverityType.INFO;.....@ExceptionHandler(type=Throwable.class, severity=ERROR)public void saveDictionaries(final PropertyList propList) {.....}

@ExceptionHandlers({@ExceptionHandler(type=java.io.IOException, severity=ERROR),@ExceptionHandler(type=com.mypackage.MyBusinessException, severity=INFO)})

public java.util.Map doBusiness() throws java.io.IOException, com.mypackage.MyBusinessException {.....}

Fortunately, this the only that we must done as developers. Beyond the scenes, NexOpen catches the exceptionin the AOP interceptor, logs associated to this severity and put the information related to the exception classMBean.

Exception management thru a JMX console

NexOpen provides an MBean which keeps information related to the exceptions arised in the application.

B.3. Exception Handling in WEB

The exception handling, as we have mentioned above, has been one o the most important features in tradiionalJEE developments. The specifications has marked guidelines for vendors for dealing with such behaviours.Nevertheless, developers has needed more advanced features that the specifications declared.

Following Servlet 2.4 specification, we can define in the Deployment Descriptor web.xml the following ele-ments for customization of errors that appears in the application

<error-page>

<error-code>404</error-code><location>/WEB-INF/jsp/404.jsp</location>

</error-page><error-page>

<error-code>500</error-code><location>/WEB-INF/jsp/500.jsp</location>

</error-page>

Not only status code, exceptions are also contempleted and we can declare custom JSPs pages associated tocustom exceptions which achieves the presentation layer.

Exception Handling

NexOpen 0.4.0 110

Due the fact of using Spring Framework, we can also define, in the nexopen-servlet.xml, the following bean inorder to deal with the exceptions which arises the presentation layer

<bean id="exceptionHandlingMapper"

class="org.nexopenframework.web.mvc.spring.handler.NexOpenExceptionResolver"><description>

Handles the mapping between exceptions and defined views toavoid showing server errors

</description><property name="warnLogCategory" value="org.nexopenframework.myapplication"/><property name="exceptionMappings">

<props><prop key="java.lang.Throwable">500</prop>

</props></property>

</bean>

Finally in teh case of Spring MVC controllers, the exception handling and the validation it is done at Controllerclass level

....public final ModelAndView handleException(final HttpServletRequest request,

final HttpServletResponse response,final Throwable thr) throws Exception {

//model to be saved in the request attribute contextfinal Map<String, Object> model = new HashMap<String, Object>(1);final Object command = new FileUploadBean();ServletRequestDataBinder binder = this.createBinder(request, command);{

//bind the values of the requestbinder.bind(request);model.put("upload", command);

}//problem which has caused the problemif (thr instanceof ServletRequestBindingException) {

//validations problemsfinal ServletRequestBindingException srbe = (ServletRequestBindingException) thr;final Throwable valCause = srbe.getRootCause();if (valCause instanceof BindException) {

final BindException be = (BindException) valCause;final Errors errors = be.getBindingResult();final StringBuilder sb = new StringBuilder(BindingResult.MODEL_KEY_PREFIX);

sb.append("upload");model.put(sb.toString(), errors);

}}//forward to the form pagereturn new ModelAndView("myForm", model);

}

Exception Handling

NexOpen 0.4.0 111

Date post:	01-Apr-2018
Category:	Documents
Upload:	vuonganh
View:	221 times
Download:	6 times

NexOpen Framework - Reference...

Documents