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 application and skip the rest. In the following picture, we try to explain the NexOpen Nature like a jigsaw, where you put the components more suitable for your application.

Figure 1.1. NexOpen as a component framework

Therefore, as you have seen, NexOpen besides to have integration with other Open Sources projects and Frameworks provides several good practices such as profiling, stress-loading and Martin Fowler's Continous Integration.

The main interface which fulfills the concept of component is obviously Component as you have guessed. From this class, we can observe a rich and complex inheritance such as Managed Components, Engines, Service Components and so on.

In JEE applications which uses NexOpen as their framework of development, we can observe the presence of the following components

Here, we can find several modules (WEB, EJB-JAR, RAR, Client or Application Server specific) which could be included in the functionalities of our application.

				
ear
|+META-INF
  |+application.xml
  ....
				 
		

The application.xml is an standard Deployment Descriptor (aka DD) where we define the modules presents in our projet. It also coul be present specific DD related to JEE Application Servers.

The ejbapp is the way that is packaged in a typical NexOpen application. It contains the Sun Deployment Descriptors (ejb-jar.xml) and Spring configuration files

				
ejbapp
|+beanRefContext.xml
|+hibernate.cfg.xml
|+META-INF
  |+spring
    |+nexopen-dataAccessContext.xml
    |+nexopen-modulesConfigurer.xml
  |+ejb-jar.xml

			 
		

The beanRefContext.xml file represents the main file where we configure all the business tier in NexOpen projects. Mainly it defines the Spring configuration files related to access to a persistence storage, definition of messaging and already defined files contained in the NexOpen JAR files. In the ejb-jar.xml file, it contains the definition of the ServiceGatewayBean, and EJB which represents a Gateway [Fowler2002] to the Business layer. An example of beanRefContext is as follows

		  
<beans xmlns="http://www.springframework.org/schema/beans" 
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
	   xmlns:components="http://www.nexopen.org/schema/components" 
	   xsi:schemaLocation="....">
  <bean id="nexopen" 
        class="org.nexopenframework.deployment.context.AnnotationApplicationContext"> 
  <!-- information about project -->  
  <components:module name="test001War" ejbModule="false" ejb3Module="false"
                     description="test001War application, which uses NexOpen Framework"/>  
	......	  
		  
		

Look at the NexOpen implementation of ApplicationContext for dealing with custom or standard JSR-175 metadata (such as the JSR-250 metadata that you can define inside the NexOpen components) and the element components:module which provides information to the runtime Nexopen container (extension of Spring), such as if the projet does or does not support EJB module or even EJB3 mdoule, module name and a short description.

Usually, the business logic is packaged in a Java JAR file, where you can find all the business objects, model objects of your application.

				
business
|+META-INF
  |+spring
    |+production //folder for configuration related to environment production
    |+integration //folder for coniguration related to environment integration
    |+openfrwk-module-beans.xml //optional file
  |+nexopen.properties
			 
		

Moreover, if you need to configure some beans in your application, you can add in Spring configuration files which suffix -beans.xml and explicitely located under META-INF/spring folder.

Here, we can find the static and dynamic content of your application. The dynamic part, it is formed by controllers, 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 Deployment Descriptor we must configure the Spring DispatchServlet and the ServletContext listener needed or bootstrapping the application.

				
<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee ....">
    .....
     <servlet>
        <servlet-name>nexopen</servlet-name>
        <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    ....
    <listener>
        <listener-class>org.nexopenframework.web.context.ContextLoaderListener</listener-class>
    </listener>
    ......
			 
		

NexOpen team recommends highly use of Maven2 as your project modelling tool. Maven2 is a tool for managing the entire build process of a project (including compilation, bytecode instrumentation, running tests and others).

Dependencies that your application has only need to be uniquely specified in the projects pom.xml configuration files using a groupId, artifactId and version. Before the artifact is needed, a local caching repository as well as remote organizational repositories and the standard ibiblio.com repositories are searched. If the artifact is found on a remote repository it is downloaded to local cache and provided to project. As weel as the artifact you requested, any additional transiive dependencies that are needed by teh requested artifact are also downloaded.

				
<repositories>
  ......   
  <repository>
   <id>nexopen-plugin-releases</id>
   <name>NexOpen repository for Maven2</name>
   <url>http://www.nexopen.org/artifactory/repo</url>
  </repository>
</repositories>
.....				
				 
		

Maven2 introduces the concept of Archetype. In short, Archetype is a Maven project templating toolkit. An archetype is defined as an original pattern or model from which all other things of the same kind are made . The names fits as we are trying to provide a system that provides a consistent means of generating Maven projects. Archetype will help authors create Maven project templates for users, and provides users with the means to generate parameterized versions of those project templates (see also the following address http://maven.apache.org/guides/introduction/introduction-to-archetypes.html for more details about archetypes).

NexOpen provides several archetypes for easy-building completely configured projects in J2EE 1.4 and we also plan to provide archetypes for JEE 5.0 development. We provide EAR, WAR and reusable Business Components 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
      |+resources //deployment descriptor and configuration files (Spring, Hibernate,...)
  |+pom.xml    
|+web
  |+src
    |+main
    |+test
  |+pom.xml
|+.classpath
|+.project
|+pom.xml
				 
		

This generated project is also a configured Eclipse project and could be easily exported into any Eclipse IDE (it could be great that this Eclipse includes the plugin for Maven2 from http://m2eclipse.codehaus.org/). This structure is necessary to be completely understood by Maven2. Notice that Spring, Hibernate3 and other configuration files are generated by archetype for easy startup.

NexOpen it is a JEE Framework and by its JEE nature could be easily deployed in any Application Server. However, due the fat of great variety of choices, we have centered into the following options, mainly due their popularity among developers

		  
<beans xmlns="http://www.springframework.org/schema/beans" 
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
       xsi:schemaLocation="....">  
  <!-- ========================= RESOURCE DEFINITIONS ========================= -->  
  <!-- The JTA Spring Transaction Manager implementation -->  
  <bean id="transactionManager" class="org.springframework.orm.hibernate3.HibernateTransactionManager"> 
    <description>JTA Spring Transaction Manager implementation</description>  
    <!-- 
 		        avoid retrieve javax.transaction.UserTransaction 
 		        in a EJB CMT environment, otherwise turn on
 		        (for example in a pure web application, only one web module)
 		   -->  
    <!-- IMPORTANT NOTE : this property does not work with spring version 2.0.3 -->  
    <!--property name="userTransactionName"><null/></property-->  
    <property name="sessionFactory" ref="openfrwk.sessionFactory"/>
  </bean>  
  .......	
		 
		

		  
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
		   
		

		  
....
<Context path="/example" docBase="example.war" 
         debug="2" privileged="true" crossContext="false">
    <!-- logging support for example -->
    <Logger className="org.apache.catalina.logger.FileLogger" 
            prefix="localhost_example_log." suffix=".log"    
            timestamp="true"/>
    <!-- definition for Tomcat 5.0.x -->
    <!--Resource name="jdbc/exampleDS" auth="Container"
            type="javax.sql.DataSource"
     		description="Employees Database for Example Applications"/>
     <ResourceParams name="jdbc/exampleDS">
	    <parameter>
	      <name>driverClassName</name>
	      <value>com.mysql.jdbc.Driver</value>
	    </parameter>
	    <parameter>
	      <name>url</name>
	      <value>jdbc:mysql://localhost:3306/eclipse?autoReconnect=true</value>
	    </parameter>
	    <parameter>
	      <name>username</name>
	      <value>user</value>
	    </parameter>
	    <parameter>
	      <name>password</name>
	      <value>pwd</value>
	    </parameter>
    </ResourceParams-->
    <!-- definition for Tomcat 5.5.x and higher -->
    <Resource name="jdbc/exampleDS" auth="Container" type="javax.sql.DataSource"
               maxActive="100" maxIdle="30" maxWait="10000"
               username="user" password="pwd" driverClassName="com.mysql.jdbc.Driver"
               url="jdbc:mysql://localhost:3306/eclipse?autoReconnect=true"/>    
 </Context>		  
		  
		

				
example
|+business
 .....
|+ear
  |+src 
    |+main
      |+resources //specific deployment descriptors of JEE Application Servers    
  |+pom.xml
|+ejb
  |+src
    |+main
      |+resources
        |+META-INF
          |+ejb-jar.xml //Sun ejb Deployment Descriptor
          |+jboss.xml   //JBoss ejb Deployment Descriptor
  |+pom.xml    
|+web
  |+src
    |+main
      |+webapp
        |+WEB-INF
          |+web.xml          //Sun web Deployment Descriptor
          |+jboss-web.xml    //JBoss web Deployment Descriptor
  .... 
|+.classpath
|+.project
|+pom.xml
				 
		

				
<hibernate-configuration>
 <!-- a SessionFactory instance listed as /jndi/name -->
 <session-factory>
  <!-- properties -->
  <property name="hibernate.connection.datasource">java:comp/env/jdbc/exampleDS</property>
  <!-- avoid registering of validation and search listeners due to classloader problems 
       in JBoss 4.2.x.ga [in classpath, we find an older version of hibernate-annotations
       which incudes the validator and search listeners, now belonging to separate projects] -->
  <property name="hibernate.validator.autoregister_listeners">false</property>
  <property name="hibernate.search.autoregister_listeners">false</property>
  <property name="hibernate.validator.apply_to_ddl">false</property>
  <!-- Annotated classes -->				
				
		

				
<!-- this dependency is needed if you want to deploy to JBoss 4.2.0.ga -->
<!-- Hibernate validator -->
<dependency>
	<groupId>org.hibernate</groupId>
	<artifactId>hibernate-validator</artifactId>
	<version>3.0.0.ga</version>
</dependency> 				
				
		

		
example
|+business
 .....
|+ear
  |+src 
    |+main
      |+resources //specific deployment descriptors of JEE Application Servers
        |+META-INF
          |+weblogic-application.xml
  |+pom.xml
|+ejb
  |+src
    |+main
      |+resources
        |+META-INF
          |+ejb-jar.xml            //Sun ejb Deployment Descriptor
          |+weblogic-ejb-jar.xml   //Bea WebLogic ejb Deployment Descriptor
  |+pom.xml    
|+web
  |+src
    |+main
      |+webapp
        |+WEB-INF
          |+web.xml          //Sun web Deployment Descriptor
          |+weblogic.xml     //Bea WebLogic web Deployment Descriptor
  .... 
|+.classpath
|+.project
|+pom.xml
				 
		

		
<?xml version="1.0" encoding="UTF-8"?>

<wls:weblogic-application
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:wls="http://www.bea.com/ns/weblogic/90"
	xsi:schemaLocation="....">
	<wls:application-param>
		<wls:param-name>webapp.encoding.default</wls:param-name>
		<wls:param-value>UTF-8</wls:param-value>
	</wls:application-param>
	<!-- 
	     In WebLogic 9.2 a new feature called Filtering Classloader 
	    (documented in the WebLogic server documentation) has been implemented 
	-->
	<wls:prefer-application-packages>
	  <wls:package-name>javax.jws.*</wls:package-name>
	</wls:prefer-application-packages>
</wls:weblogic-application>		
		
		

We provide a unified way (using the Facade pattern) of to acces to a context or a group of contexts represented by the class import org.nexopenframework.context.framework.Contexts

				
.....
import org.nexopenframework.context.framework.Contexts;
......
//access to all contexts registered
Object obj = Contexts.getAttribute("my.attribute");
//acccess to contexts with scope REQUEST
Object obj_req = Contexts.getAttribute("my.request.attribute", Contexts.REQUEST);
				 
			

Note the presence of a specific method for searching for an attribute in the REQUEST context.

The way to provide a customized Context it is just implementing the interface org.nexopenframework.context.framework.Context

				
.....
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;
	}
}
				
			

You must be sure that in the beanRefContext.xml to be present the following entry into the constructor argument element

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

One important feature of NexOpen is to provide a nice way to deal wih the events of Spring thru BootstrapListener

		
...
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) {
		......
		
	}
	......

}
		
		

One important feature in NexOpen is the possibility to send events easily thanks to EventDispatcher class. In this way, you can easily create any event class type following the java onvention (extending from java.util.EventObject) and fire it. Here, we provide an easy example of use that could be found in any Business 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.

In order to easily configure this module, you must define a file called openfrwk-module-eventsDispatcher.xml in the WEB tier and define a Spring bean as follows (this file also contains other bean for events but we only center in the event dispatcher bean)

		
.....		
<beans xmlns="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="...">
	<description>Objects used to publish events</description>
	<!-- ========================= RESOURCE DEFINITIONS ========================= -->
	<!-- 
	  	Event dispatcher class. After this is initialized by Spring 
	    could be used in a static way forany class of the 
	    simple application 
	-->
	<bean id="publisher" class="org.nexopenframework.context.event.EventDispatcher">
		<description>Event dispatcher for handling notifications</description>
	</bean>
	......	
		
		

Afterwards, yo must import the above Spring configuration file in the nexopen-servlet.xml file

		
 <!-- 
  Spring Event support ::
   1.- sending notifications from any layer of your application 
 -->
 <import resource="openfrwk-module-eventsDispatcher.xml" />		
  		
		

With this, we can easily fire events for any service component and will be catched in the presentation layer.

Pooling is a main characteristic of managed JEE components (such as Servlet Thread Pool, EJBs, javax.sql.DataSource,...). One of the characteristics of Frameworks such as Spring is the possibilty to obtain such features easily thru configuration. In NexOpen, we have choosen to offer such features in a transpaent way or developer and we have though to hide such configuration and offer a set of metadata for easy development.

The way than we can declare that a Business ServiceComponent needs pooling support is thru a JSR-175 annotation

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

}
			 
	

			
<!-- services for j2se 5.0 -->  
<value>classpath*:META-INF/spring/openfrwk-module-services-pool-jdk15.xml</value>			
			
		

All the business logic of an application JEE must be located into this tier. However, several mistakes and misconcepts 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 extensibility.

Business Services are an special kind of components inside NexOpen which fulfills the above descibed features. The main features that are essencial to be included in these components, are transactionality, concurrency control and exception handling. Moreover, in environments or solutions that not included EJB container, we can offer resource pooling support. The J2SE 5.0 annotation of NexOpen which describes this component is given as follows

        
@Target(TYPE) @Retention(RUNTIME)
@Documented
public @interface BusinessService {
	/**
	 * Type of business. Mainly, there are <code>FACADE</code> based in the GoF
	 * Facade pattern and <code>APPLICATION</code> based in the Core J2EE pattern
	 * Application Services.
	 */
	BusinessType type() default BusinessType.FACADE;
	/**
	 * <p>The complete name of the Component interface defining the Business 
	 * Service Component contract.</p> 
	 * 
	 * <p>Only applied for implementation classes of a business service 
	 * of type<code>FACADE</code>. In a <code>APPLICATION</code> has nonsense 
	 * due the fact that has not client view (so, it is not necessary 
	 * to specify a interface).</p>
	 */
	String componentInterface() default "";
}           
			
        

As you have noticed appears a new attribute componentInterface which is special for FACADE business type.

Other important feature of this service components is the possibilty of using the inheritance support of Java as typical Object Oriented language. usually, you can extend a set of Service Components from other class or classes which provides several common methods (such as CRUD operations).

We can adopt the following catalog refering to ServiceComponents : Business Facades, Application Services and Configurable Services.

				
package org.nexopenframework.samples.example.facades;

import org.nexopenframework.business.annotations.BusinessService;
import org.nexopenframework.business.annotations.BusinessType;
/**
 * <p>example using NexOpen Framework</p>
 * 
 * <p>Example of BusinessService</p>
 * 
 * @author <a href="mailto:yourname@yourmail.com">Name Surname</a>
 * @see BusinessService
 * @version 1.0
 * @since 1.0
 */
@BusinessService(type = BusinessType.FACADE)
public class ExampleFacadeImpl implements ExampleFacade {

  ......
}
	      
			

					
package org.nexopenframework.samples.example.services;

import org.nexopenframework.business.annotations.BusinessService;
import org.nexopenframework.business.annotations.BusinessType;
/**
 * <p>example using NexOpen Framework</p>
 * 
 * <p>Example of BusinessService</p>
 * 
 * @author <a href="mailto:yourname@yourmail.com">Name Surname</a>
 * @see BusinessService
 * @version 1.0
 * @since 1.0
 */
@BusinessService(type = BusinessType.APPLICATION)
public class ExampleAppService {

  ......
}
	      
				

Configurable Services (hereafter Services) are an special kind of Business Service Components that can configure some properties of these component thru a JMX console. Notice that these componets, offers the possibility to manage some properties without the need of redeploying an Application Server.

The J2SE 5.0 annotation which describes this component is the following

		  
@Target(TYPE) @Retention(RUNTIME)
@Inherited
@Documented
public @interface Service {
	/**name of the service*/
	String name();
	/**domain*/
	String domain();
	/** A description of the service*/
	String description() default "Service";
	/** If the service has the statistics service enabled*/
	boolean statistics() default false;
	/** If the service is dealing in a distributed environment*/
	boolean distributable() default false;
}		
			
		

Notice that services are prepared to support distributable environemnts, if you specify the attribute distributable as true, automatically any change done in a node of your cluster is broadcasted to all nodes of such cluster. In order to properly done this feature, you must not forget to configure the appropiate module in your beanRefContext.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;
	
	.....
}
		
		

Notice the presence of ServiceConfigProperty as the annotation responsable to indicate which properties could be easily configured or not and if framework should create accessors or mutators (you could not define any getter and setter for this proeprty, framework during the instrumentation phase automatically creates for you the accesors and mutators).

In this example, the property called myProperty could be easily managed in a read-write style by a JMX console, because by default, Instrumentation Phase provides getter and setter methods (in the ServiceConfigProperty annotation exists an operation attribute with default value PropertyOpType.READ_WRITE and then automatically creates such accessors and mutators methods). If you want to modify this default behaviour, you must specify it in this attribute, for instance, if you plan to use only read methods in some properties you have to specify PropertyOpType.READ, and then the Class Transfomer related with Services, in the Instrumentation Phase, will generate only accessors methods (getters) but not mutators (setters).

Finally it is important to note, that inheritance is forbidden in this kind of configurable business components, because in the Intsrumentation Phase is provided a suitable parent to deal with lifecycle methods associated to this component. The parent class could be the specific ServiceSupport or the customized JBoss serice support class

			  
package org.nexopenframework.services.annotations;

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

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

@Target(TYPE) @Retention(RUNTIME)
@Documented
public @interface Depends {
	/**
	 * <p>The services classes array that the annotated class depends</p>
	 * 
	 * @return the services classes whihc the given service depends
	 */
	Class[] value();
}			  
			  
			

			
........			
@Depends({OtherService.class, AService.class})
@Service(name="easy",domain="test.example")
public class SomeService {
........
}			
			
			
			

You have the possibility of addition of custom AOP interceptors in any service component. The way to do is thru an annotation Interceptors. If any annotation is present, in the enhacement phase, will be recovered and searching into Spring IoC container or just created as a single instance (take into account that it is injected any depedency in this phase, if you want to inject something, you must declare such interceptor into a Spring configuration file) and added to the chain of interceptors associated to service components.

	 
package org.nexopenframework.core.interceptors.annotations;

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

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

import org.aopalliance.aop.Advice;

@Target(TYPE) @Retention(RUNTIME)
@Inherited
public @interface Interceptors {
	/**
     * <p>The interceptors to be added to a service component. The class must be an AOP alliance
     * {@link Advice}</p>
     * 
     * @return the interceptors class objects to be added to a given ServiceComponent
     */
	Class<? extends Advice>[] value();
}

	 

Notice the dependency with AOP Alliance, an easy to use implementation of the AOP philosophy. Following we show an example o using this annotation

	 
.....	 
@Interceptors({EasyInterceptor.class, PerformanceMonitorInterceptor.class})
@BusinessService(type=BusinessType.FACADE)
public class ExampleFacade implements ExampleFacadeIf {

	@Component OtherFacadeIf other;
	/* (non-Javadoc)
	 * @see org.nexopenframework.example.business.ExampleFacadeIf#doBusiness()
	 */
	public void doBusiness() {
		System.out.println("ExampleFacade.doBusiness()");
	}
}
	 
	 

In next releases, we probably relax such dependency with AOP Alliance Advice class, in order to inrodce other AOP Frameworks such as AspectJ which is widely supported by Spring2.

Usually, Service Components could depend of other components or resources. The usual way to access to these components is thru injection using the fact that components are managed thru a IoC container (in this case Spring Framework IoC container). NexOpen provides an annotation tha is defined as follows

		
package org.nexopenframework.core.annotations;

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

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

@Target({TYPE,METHOD,FIELD}) @Retention(RUNTIME)
@Documented
@Inherited
public @interface Component {
	/**
	 * 
	 * @return
	 */
	String name() default "";
	/**
	 * <p>The type of the Service Component</p>
	 * @return
	 */
	Class<?> type() default Object.class;
}
		 
		

An example of how to inject components (service components or even resources managed by any JEE application server) is given as follows

			
....
import javax.annotation.Resource;
...
import org.nexopenframework.core.annotations.Component;

@BusinessService(type = BusinessType.FACADE)
public class MyFacade implements MyFacadeIf {
    /**Access to a ApplicationServer component*/
    @Resource javax.transaction.UserTransaction ut;
    /**Access to a Component managed by Spring IoC container*/
    @Component mypackage.service.MyAppService appService;
}			
			
		

As we notice, there two main annotations in order to access to Components. The first one, it is a component managed by an JEE Application Server (a JTA/JTS User Transaction implementation of such Application Server) and the second one is managed by a IoC container, such as Spring Framework. Notice that all of these components, they will be injected during the deployment phase.

One important feature of ServiceComponents is the possibility of caching values in a structure Map type. A typical 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 should make an HTTP invocation in order to ensure it. However, if we can ensure that during an among of time this reponse would not change, it is not necessary to make an HTTP invocation and increasing performance of the application.

The way that we inject a cache, it is as follows using the annotations @org.nexopenframework.cache.annotations.Cache. Look that we are injecting a proxy which deals with a suitable configured provider (such as EhCache or JBossCache) and hides the complexities of Cache API offering a well-known interface to operate. Features such as cache eviction, policies and others they are hidden and could be adminsitered using a JMX console.

			
....
import static org.nexopenframework.cache.annotations.CacheConcurrency.NONSTRICT_READ_WRITE;
....
import java.util.Map;
import org.nexopenframework.cache.annotations.Cache;			
....
public class MyAppService {
    
	/**represents a proxy of a selected cache*/
	@Cache(concurrency=NONSTRICT_READ_WRITE) 
	Map cache;
	.....
}			
			
		

In order o use this feature, we must add into our beanRefContext.xml the following entry

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

Internally, it looks for a suitable implemnetations of org.nexopenframework.cache.providers.CacheProvider. If no one is provided, first tries to load the EhCache provider if it is found in classpath and in negative case provides a naive implementation based in an implementation of java.util.Map. However, you can provide your custom provider just declaring into your business spring files

The Enhacement Phase it is an important phase in the lifecyle of deployment of a NexOpen application, in which all the Service Components, presents in the Spring IoC container, will be enhaced thru the addition of fixed and custom AOP interceptors. The fixed interceptors deals with transactionality support, exception handling and performance monitoring. Therefore, this components will be translated to proxies which can deal in a transparent way with features that could be tought to developers.

It is important to note that in the current release, we only support addition of AOP Alliance interceptors.

Transactionality in ServiceComponents is managed internally by framework thru AOP which intercepts a call and pass the invocation to ServiceComponentEngine. This is an internal component of NexOpen which guarantees to execute the invoked methods in a transactional environment thanks to Spring Transactional module. Internally this engine has an ordered list of Spring TransactionAttributeSource implementations

The name matches, of this last TransactionAttributeSource option, are the following (as it is carried into the services spring configuration files).Therefore, if your method begins with one of this name, you can not declare any specific annotation for dealing with tx behaviour

 ......	  
<bean id="nameMatchAttributeSource"
  class="org.springframework.transaction.interceptor.NameMatchTransactionAttributeSource">
  <description>Name Match attribute source</description>
  <property name="properties">
	<props>
		<prop key="get*">PROPAGATION_SUPPORTS,readOnly</prop>
		<prop key="find*">PROPAGATION_SUPPORTS,readOnly</prop>
		<prop key="exits*">PROPAGATION_SUPPORTS,readOnly</prop>
		<prop key="retrieve*">PROPAGATION_SUPPORTS,readOnly</prop>
		<prop key="query*">PROPAGATION_SUPPORTS,readOnly</prop>
		<prop key="update*">PROPAGATION_REQUIRED</prop>
		<prop key="store*">PROPAGATION_REQUIRED</prop>
		<prop key="handle*">PROPAGATION_REQUIRED</prop>
		<prop key="save*">PROPAGATION_REQUIRED</prop>
		<prop key="insert*">PROPAGATION_REQUIRED</prop>
		<prop key="create*">PROPAGATION_REQUIRED</prop>
		<prop key="persist*">PROPAGATION_REQUIRED</prop>
		<prop key="set*">PROPAGATION_REQUIRED</prop>
		<prop key="add*">PROPAGATION_REQUIRED</prop>
		<prop key="make*">PROPAGATION_REQUIRED</prop>
		<prop key="delete*">PROPAGATION_REQUIRED</prop>
		<prop key="remove*">PROPAGATION_REQUIRED</prop>
		<prop key="erase*">PROPAGATION_REQUIRED</prop>
		<prop key="execute*">PROPAGATION_REQUIRED</prop>
	</props>
  </property>
</bean>
	......
	  

Following caption, shows examples of the before mentioned mechanisms of transactionality

			
/**
 * this method will be executed in a tx environment due the fact of matching
 * with internal rules
 */
 public void createPerson(final Person p) {
    this.pm.persist(p);
 }

/**
 * this method will not be executed in a tx environment
 */
 public void doSomeBusiness(final Person p) {
    this.pm.persist(p);
 }
/**
 * this method will execute in a tx environment using Spring Transactional 
 * annotations support
 */
 @org.springframework.transaction.annotation.Transactional
 public void doBusiness(final Person p) {
    this.pm.persist(p);
 }
 
 /**
  * <p>Client customs the tx using EJB3</p>
  *
  */
  @javax.ejb.TransactionAttribute(javax.ejb.TransactionAttributeType.REQUIRED)
  public void doOperationWithTx() {
  
  }
			
		

Usually, we would like to perform authorization constraints in business components. There two ways o deal with it in NexOpen Framework, one programmatic and teh other one declarative.

The programmatic way, is to obtain n instance of Actor and perform teh operations such as obatine the current User, or if a given role is allowed

		
.....
import org.nexopenframework.security.context.Actor;
.....
public void doBusinessMethod (final Map<String, Serializable> filter) {
    final Actor actor = Actor.getInstance();
 	//retrieve the current User
 	final User user = actor.getCurrentUser();
 	....
 	//of perform programatic authz
 	if (actor.isUserInRole("ROLE_ADMIN") {
 	  ........
 	}
 	......
}		
		
		
		

The declarative way, is to use JEE 5.0 RolesAllowed annotation. This annotation should be declared at method level and in the specific case of Facades, it must be declared at the interface level, as follows in the given example

		
...
import javax.annotation.security.RolesAllowed;
...
@RolesAllowed("ROLE_ADMIN")
void createPerson(final Person person);
....
	
		
		

In order to use such module you must be sure that the Spring configuration file for services it si included in your beanRefContext.xml

			
<!-- services for j2se 5.0 -->  
<value>classpath*:META-INF/spring/openfrwk-module-services-jdk15.xml</value> 			
			
		

Moreover, you must include such dependency in your pom.xml

<dependency> 
  <groupId>org.nexopenframework</groupId>  
  <artifactId>openfrwk-services-jdk15</artifactId>  
  <version>${nexopen.version}</version>  
  <exclusions> 
    <exclusion> 
      <artifactId>commonj-twm</artifactId>  
      <groupId>com.bea.wlplatform</groupId> 
    </exclusion>  
    <exclusion> 
      <artifactId>junit</artifactId>  
      <groupId>junit</groupId> 
    </exclusion>  
    <exclusion> 
      <artifactId>commons-logging</artifactId>  
      <groupId>commons-logging</groupId> 
    </exclusion> 
  </exclusions> 
</dependency> 		
		

We should exclude such dependencies in order not to be included in the artifact (ear, war, ...)

Invokers are a chain of implementations of ServiceGatewayInvoker which are able to communicate to a given container. In this sense, for a developer point of view always see the same code from a client class, but the way of how to 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 is defined as follows

				
package org.nexopenframework.core.runtime.annotations;
.....
@Target({TYPE,METHOD,FIELD}) @Retention(RUNTIME)
@Inherited
@Documented
public @interface ServiceGatewayRef {
  /**the business service to be proxied*/
  Class businessService() default Object.class;
  /**JNDI name of the Service Gateway component*/
  String jndiName() default "";
  /**if must include the prefix java:comp/env to previous JNDI name*/
  boolean resourceRef() default true;
  /**if we use the local or remote call*/
  /**This attribute has been deprecated*/
  @Deprecated
  boolean localEJB() default false;
  /**additional interceptors [now support for AOP Alliance]*/
  Class<? extends Advice>[] interceptors() default {};
}
				
		

Elements such as jndiName and resourceRef are necessary when we deal with communication to EJB 3.0 Stateless Session Beans. Finally, element interceptors is suitable when you would like to enhace the chain of AOP advices to be applied to invocation of Business Facade (very useful, if you want to perform authorization mechanisms, for isntance)

				
....
<beans xmlns="http://www.springframework.org/schema/beans"
	   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	   xmlns:jee="http://www.springframework.org/schema/jee"
	   xsi:schemaLocation="....">
  ....
 <!-- ========================= RESOURCE DEFINITIONS ========================= -->
	
 <bean id="servGatewayProcessor"
	class="org.nexopenframework.deployment.processor.ServiceGatewayProcessor">
	<description>
		Processor which deals with service gateway references in controllers
	</description>
	<!-- Invokers -->
	<property name="invokers">
       <list>
          <value>org.nexopenframework.core.runtime.invokers.EJBLocalInvoker</value>
          <value>org.nexopenframework.core.runtime.invokers.EJBRemoteInvoker</value>
       </list>
    </property>
</bean>
....
				 
		

		  
 <!-- EJB Gateway (Gateway pattern [See Fowler2002, 466])-->
<dependency>
	<groupId>org.nexopenframework</groupId>
	<artifactId>openfrwk-ejbgateway</artifactId>
	<version>${nexopen.version}</version>
	<exclusions>
		<exclusion>
			<groupId>commons-logging</groupId>
			<artifactId>commons-logging</artifactId>
		</exclusion>
	</exclusions>
</dependency>
		 
		 

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>
  */
  @Auditable
  public void doMoreBusiness() {
    ......
  }
}				
				
		

As you can observe, you do not need to perform

		
....
@Auditable
public class MyFacadeImpl implements MyFacade {
  ...
}
		
		

in this case, all the methods are auditable

NexOpen provides a way to deal with Oracle FGA support

However, several times you need a particular auditing that it is not contempleted by our implementations or extend 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

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

	   
...
<!-- services for j2se 5.0 -->  
<value>classpath*:META-INF/spring/openfrwk-module-audit-jdk15.xml</value>
<!-- synchronous audit Orale FGA -->
<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

Independently of the scheduler provider that we are using, the way to declare that a method must be scheduled is 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 annotation provides support for common periodic schedulings as well cron expressions (you must be sure that your provider supports such feature)

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

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

			
....
<beans xmlns="http://www.springframework.org/schema/beans" 
	   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
	   xmlns:components="http://www.nextret.org/schema/components" 
	   xsi:schemaLocation=".....">  
	   
  <bean id="nexopen"
        class="org.nexopenframework.deployment.context.AnnotationApplicationContext">
   <constructor-arg> 
    <list>
     ......
     <!-- Scheduler modules using Quartz -->  
    <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 configuration file instead.

			
 <!-- Scheduler modules using CommonJ -->  
<value>classpath*:META-INF/spring/openfrwk-module-scheduler-commonj.xml</value>   			
			
		

More specifically, workflow is the operational aspect of a work procedure: how tasks are structured, who performs them, what their relative order is, how they are synchronized, how information flows to support the tasks and 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 representing wait states, decision, tasks, etc... NexOpen Workflow module offers you a simply way to enhace your Business Services to interact with the business process management engine.

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

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 Associated Entities is made throught saving Primary Key at Process Context. We use NexOpen Context Module in order to perfom this Integration. The Current Process Context is loaded using Hiberante Listeners. When a business service method load an Entity the Workflow module is responsible to load the process Instances binded to this Entity

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

Figure 10.1.  NexOpen Workflow Integration with jBPM 3.1.x

Figure 10.2. NexOpen Workflow

Figure 10.3. NexOpen Workflow Context

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

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

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

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

The next step is update the beanRefContext.xml File. In that file MUST exists an entry in order to ensure the use 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=".....">  	   
  <bean id="nexopen"
        class="org.nexopenframework.deployment.context.AnnotationApplicationContext">
   <constructor-arg> 
    <list>
     ......
     <!-- WorkFlow Module -->  
    <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 reference one of these files

			
.......
<!-- WorkFlow Module Annotation Support -->  
<value>classpath*:META-INF/spring/openfrwk-module-workflow-jbpm-jdk15.xml</value>
<!-- WorkFlow Module Annotation Support + Hibernate Integration -->  
<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

				
     .......
<!-- # jbpm mapping files # -->		
<!-- hql queries and type defs -->
<mapping resource="org/jbpm/db/hibernate.queries.hbm.xml" />

<!-- graph.def mapping files -->
<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"/>

<!-- graph.node mapping files -->
<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"/>
<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"/>

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

<!-- taskmgmt.def mapping files -->
<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"/>

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

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

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

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

<!-- graph.exe mapping files -->
<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"/>

<!-- module.exe mapping files -->
<mapping resource="org/jbpm/module/exe/ModuleInstance.hbm.xml"/>
    
<!-- context.exe mapping files -->
<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"/>

<!-- msg.db mapping files -->
<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"/>

<!-- taskmgmt.exe mapping files -->
<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"/>

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

<!-- logging mapping files -->
<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"/>
<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"/>

<!-- # end jbpm mapping files # -->
   .......
      
			

Now the Workflow module it's ready to work

Due to business reasons it could be interesting to you to enhance some of your entities by binding an specific Workflow to them. This workflow must be in charge of perform some cross operations that allow to your Analist to detach workflow business logic from your entity logic. By this way we could add a Process Event Dispatcher Bean to dispatch the events defined in the Workflow Process Definition, a Process Decision Manager Bean 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 Application Service

			 
<!-- process definition -->
<bean id="example-process-definition"
	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=“”)
			
		

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

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

	
...
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() {
      ..........
   }
}	
		
	

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

NexOpen uses JAX-WS 2.0 in order to integrate with Web Services. Following the nice practices developed by Spring Team, we use AOP and we leave to develoeprs to define properly the interface which provides the gateway to invoke the methods exposed by the foreign Web Service which would like to integrate. Next, we show how 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 {
	  @WebMethod
	  public 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 {

      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 to be 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 NexOpen provides an Standard MBean in order to manage this integration.

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

	
.....
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 {
 .......
}	
	
	

NexOpen provides support for using JUnit3 as test Framework support. using NexOpen facilities we can easily test 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 location
      this.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 service
       final 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
		....
    }  
}
	
	

In case of XFire integration, we must ensure to

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

Persistence Manager is based in the Object Relational Mapping (ORM) philosophy. It is important to note that NexOpen Framework does not provide a implementation of a new ORM, NexOpen only try to integrate several know ORM OpenSource, like Hibernate3 or any JPA Open Source provider, trying to simplify the knowlodgement of these implementations. Besides having a several CRUD operations like persist, delete, update and simple finders, it is also a Query factory and Criteria Factory. The main point it is to consider this interface as a part of the integration or resource layer. DAO's will be needed,as we have mentioned before, if we have query strings that compromises and couples the business layer. Just persisting, deleting or easy retrieval including query 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 important to note that all the POJO classes which represents the entities in a persistence storage should be annotated 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 a Service Component use this API for ORM operations

				
import org.nexopenframework.persistence.PersistenceManager;

....

	      
/**The PersistenceManager SPI for persistence storage operations*/
@PersistenceManagerContext
PersistenceManager 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) {
	this.pm = pm;
}


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

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

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, injecting 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 is not 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");  
    }

}
		

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

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

/**The PersistenceManager SPI for persistence storage operations*/
@PersistenceManagerContext
PersistenceManager 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();
	.....
}     
	      
		

This API is related to build dynamic queries dependending of the values you would like to add. It is a well way to 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 a persistence storage grammar (in other words, typical SQL like, equals, between operations or even maximum and minimal) as you can see in the next example and adding to Criteria object

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

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

		    
    ...
    //use of pagination support
    final 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");
    ....
    
		

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

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

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

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

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

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

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

NexOpen provides since 0.4.x versions and higher a typed DAO interface for dealing with common CRUD operations thru GenericServiceDAO. If your Facades and Application Services has common operations related to a given entity, we strongly recommend the use of this DAO and choose the persistence model of your application, using the generic PersistenceManager or JPA. in the following example, we show an example of such feature 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 managed
        super(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

As we have mentioned before, a well defined application has several TestCases in order to test the functionalities of your application. However, we realize that soemtimes it is a tedious work to perform a integrated test like to 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 NexOpen 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 a HSQLDB, it is as follows

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

/**
 * <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 transaction 
        this.beginTransaction();
        //TODO call your functionalities related with this ServiceComponent
        
        //commit unit of work
        this.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 problems
        this.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 invocation
        super.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
        //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 the JSR-220 annotation in the hibernate configuration files and we can focus in the business features.

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

			
....
<beans xmlns="http://www.springframework.org/schema/beans" 
	   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
	   xmlns:components="http://www.nextret.org/schema/components" 
	   xsi:schemaLocation=".....">  
	   
  <bean id="nexopen"
        class="org.nexopenframework.deployment.context.AnnotationApplicationContext">
   <constructor-arg> 
    <list>
     ......
     <!-- persistence manager for j2se 5.0 allowing auto-discovery of JSR-220 entities-->  
     <value>classpath*:META-INF/spring/openfrwk-module-persistence-jdk15-auto.xml</value>
     <!-- allow the injection of PersistenceManager or EntityManager -->
     <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 of the 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 to use the validation facilities provided by NexOpen you must be sure to define properly next entrance into beanRefContext.xml in list defined by bean nexopen whcih appears in the previous caption

			
.....
 <!-- hibernate validation support -->
<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 choosen this option, nevertheless if you would like to choose Oval framework you must use openfrwk-module-persistence-validator-oval.xml instead).

Moreover, if you are using Persistence Manager support with Hibernate3, you must also define into your hibernate.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>
 <!-- a SessionFactory instance listed as /jndi/name -->
 <session-factory>
  .......
  <!-- validation events -->
  <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 before 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

			
<!-- Put it if you have choosen Hibernate Validator alternative -->
 <dependency>
    <groupId>org.hibernate</groupId>
    <artifactId>hibernate-validator</artifactId>
    <version>3.0.0.ga</version>
</dependency>
<!-- Put it if you have choosen Oval Validator Framework alternative -->
 <dependency>
    <groupId>net.sf.oval</groupId>
    <artifactId>oval</artifactId>
    <version>1.0</version>
</dependency>
			
		

The contract in order to use the Asyncrhonous tasks is implementing the interface org.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 is passed 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

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

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

			
<!-- MDB for executing tasks in itunes application-->
<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

			
<!-- ========================= JMS DEFINITIONS  ========================= -->		
<!-- uncomment if you want to work with asynchronous tasks module -->
<!-- JMS ConnectionFactory -->
<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>
<!-- JMS Queue -->
<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>			
			 
		

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

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

			
....
<beans xmlns="http://www.springframework.org/schema/beans" 
	   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
	   xmlns:components="http://www.nextret.org/schema/components" 
	   xsi:schemaLocation=".....">  
	   
  <bean id="nexopen"
        class="org.nexopenframework.deployment.context.AnnotationApplicationContext">
   <constructor-arg> 
    <list>
     ......
     <!-- Tasks modules using MDB -->  
    <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 descriptor ejb-jar.xml, the nexOpen Message-Driven Bean MessageDrivenBeanServiceExporter.

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 by Spring.

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

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

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

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

@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 view
		   return new ModelAndView("default",model); 
	  }
	  ....	 				    				
			
		

We should mention that folowing the NexOpen nature, we do not need to register in a Spring configuration file such Controller. In order to fulfill this feature, you must be sure that the following context parameter element is present 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>
		  
		

Struts1 is one of the most famous MVC Frameworks n JEE development. Originally, it was a revolution in the development JEE applications and became a standard. Nowdays, there are several MVC Frameworks and Struts has 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 a Spring Controller, which wraps the lifecycle of a given Servlet. In our case this servlet is the well-known AcionServlet which is the HTTP Listener of such Framework (internally this servlet delegates to RequestProcessor)

The way that we specify in NexOpen that a clas is an Struts Action is thru a J2SE 5.0 annotation such as in the following 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;
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;
	
	@Override
	public ActionForward execute(ActionMapping mapping, ActionForm form, 
                                 HttpServletRequest req, HttpServletResponse resp) 
 								 throws Exception {
		......
		return new ActionForward("success");
	}
}						    				
			
		

				
<!-- Struts1 dependency -->				
<dependency>
   <groupId>struts</groupId>
   <artifactId>struts</artifactId>
   <version>1.2.9</version>
</dependency>			    				
				
			

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 action takes the role o model rather than controller [Roughley2006]. This Framework does not use a traditional Servlet as the HTTP listener. Its architecture is based in a FilterDispatcher which is a JEE Filter for handling the 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 {

	@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 satisfy one of the following rules

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.

				
<!-- Struts2 Filter -->
<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>
   <filter-name>nexopen-struts2</filter-name>
   <url-pattern>/*</url-pattern>
</filter-mapping>
				
			

				<?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>
	<!-- Here you can extend functionalities for your application -->
	
	<!-- constants -->
	<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" />
    <!-- Add packages here -->
    
</struts>
				
			

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

Pagination is a typical feature that appears often in JEE developments. Such feature has been also documented as a JEE Core Pattern [Alur2003] called ValueList. Fortunately, ValueList Open Source project has implemented this pattern and provides several ways to integrate it. Moreover, it provides integration with Spring Famework for dealing a bean oriented programming style. Nevertheless, in NexOpen we think that things could be even more easy and we have tried avoiding several written of spring configuration files. Then, we have defined 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
@Documented
public @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 {};
}    
      
      

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 it shows 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.ANYWHERE
        matchMode=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;      
      
      

      
<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="....">
......
<!-- ========================= VALUE LIST ========================= -->
<!-- uncomment all these beans if you plan to use ValueList in your application -->
<!-- convenient class in order to allow custom registering -->
<bean id="valueListHandler"
	class="org.nexopenframework.web.vlh.DefaultValueListHandlerImpl">
	<description>Declare different value lists</description>
	<property name="config.adapters">
	  <map>
	  <!-- put here your custom adapters-->

	  </map>
	</property>
</bean>
<!-- register of custom valuelist's -->
<bean id="exporter"
	class="org.nexopenframework.web.vlh.support.ValueListExporter">
	<description>Exported for delaing with ValueList Adapters</description>
	<property name="valueListAdapterResolver"
		ref="valueListAdapterResolver" />
</bean>
<!-- resolver related with annotations provided by NexOpen -->
<bean id="valueListAdapterResolver"
	class="org.nexopenframework.web.vlh.support.AnnotationValueListAdapterResolver">
	<!-- 
        please put in a package-info.java class file located at package com.myproject.info
        all the annotations related with ValueList notifications 
    -->
	<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>
			<!-- append or not the context path to images location -->
			<property name="preAppendContextPath" value="true"/>
		</bean>
	   </entry>
	 </map>
	</property>
</bean>
.....
      
      

To handle simple AJAX calls where web pages ask for information to server without reloading, business logic must me implemented as is usually done in NexOpen projects, creating business services that expose its methods 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 dwr configuration section, the place where the NexOpen creator was declared.

  <dwr:configuration>
    <dwr:init>
      <!-- Register NexOpen's custom creator -->
      <dwr:creator id="nexOpen" 
        class="org.nexopenframework.web.dwr.creator.DWRServiceGatewayCreator"/>
    </dwr:init>
    <!-- Remotely exposed business objects -->
    <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, given a name to be accessed from javascript and specify that they will use NexOpen's custom creator. The invocation parameters should be configured here, specifying the invokers to be used, as a comma separated string of values, between the offered possibilities (pojo,EJBLocal,EJBRemote), as when declaring the invokers for regular services.

Due the DWR SpringFramework limitations noted before, the SpringConfiguration bean definition has to be updated with the new business object entry. An entry for every object being exposed must be added in the creators 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 should
      extend it in order to deal properly
    </description>
    <property name="creators">
      <map>
        <entry>
          <key><value>TestFacade</value></key>
          <ref bean="__AjaxService" />
        </entry>				
      </map>
    </property>    
  </bean>

The business class is specified using the "dwr:param" with "businessService" as name and from here, just declare 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 an instanced TestDWRFacade JavaScript object where all the methods defined as included will be accessible. An outline 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>

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

For an application to be able to publish those events from the business module in an application, two things must 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.

... 
  <!-- Define the controller for DWR requests -->
  <dwr:controller id="dwrController" debug="true">
  	<dwr:config-param name="activeReverseAjaxEnabled" value="true"/>
  </dwr:controller>

<!-- ========================= AJAX NOTIFICATION ========================= -->
<!-- uncomment if you plan to use AJAX NexOpen support in your application -->
   <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"
    class="org.nexopenframework.web.dwr.support.SpringConfigurator">
    <description>
      In order to inject the params into the creators, we should
      extend 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 simple ajax calls, to add the bean in the SpringConfigurator section, with the preceding "__". Remember to program an implementation of org.nexopenframework.web.dwr.AjaxEventExecutor, which is the class that really will know what to do with the given org.springframework.context.ApplicationEvent subclasses that the application fires. AjaxEventExecutor's don't need to be declared in any configuration files, NexOpen framework will autodiscover them.

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

... 
public class NotificationEventExecutor implements AjaxEventExecutor { 
  public void execute(ApplicationEvent event, ServerContext sCtx){ 
    // Get all browser connected sessions 
    Collection sessions = sCtx.getAllScriptSessions(); 
    Util dwrUtil = new Util(sessions); 
    // Build the javascript action
    ScriptBuffer 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 browser 
    sb = new ScriptBuffer(((UserDefinedEvent)event).getClientCode());
    // So add the new JavaScript to all those connected sessions 
    dwrUtil.addScript(sb); 
  } 
  // Describe which kind of events is supporting this executor 
  public 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 it possible, and remeber activating the reverese ajax feature.

<html> 
  <head>
  <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> 
...

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

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

TO BE DOCUMENTED

Related to security in JEE Applications, we have choosen Acegi Security Framework (see http://www.acegisecurity.org/ for more details).Thanks to its configurable architecture, we can easily plug-in among 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 for dealing with security issues.

We have extended some prop

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

             
<!-- Acegi Security Framework for Spring -->
<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>
            <groupId>org.springframework</groupId>
            <artifactId>spring-jdbc</artifactId>
        </exclusion>
        <exclusion>
            <groupId>org.springframework</groupId>
            <artifactId>spring-support</artifactId>
        </exclusion>
        <exclusion>
            <groupId>org.springframework</groupId>
            <artifactId>spring-mock</artifactId>
        </exclusion>
        <exclusion>
            <groupId>commons-logging</groupId>
            <artifactId>commons-logging</artifactId>
        </exclusion>
        <exclusion>
            <groupId>commons-lang</groupId>
            <artifactId>commons-lang</artifactId>
        </exclusion>
        <exclusion>
            <groupId>commons-collections</groupId>
            <artifactId>commons-collections</artifactId>
        </exclusion>
        <exclusion>
            <groupId>ehcache</groupId>
            <artifactId>ehcache</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<!-- NexOpen dependencies -->
<dependency>
    <groupId>org.nexopenframework</groupId>
    <artifactId>openfrwk-security-core</artifactId>
    <version>${nexopen.version}</version>
    <exclusions>
        <exclusion>
            <groupId>org.springframework</groupId>
            <artifactId>spring-support</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>org.nexopenframework</groupId>
    <artifactId>openfrwk-security-jdk15</artifactId>
    <version>${nexopen.version}</version>
</dependency>
        	 
            

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

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

             
<bean id="web.propertyConfigurer"
      class="org.nexopenframework.spring.config.PropertyPlaceholderConfigurer">
      <property name="ignoreResourceNotFound" value="true"/>
      <property name="locations">
          <list>
             <!-- classpath properties file for overwritten this default properties -->
             <value>classpath:acegi.properties</value>
          </list>
      </property>
      <!-- Acegi configuration -->
      <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
                 <!-- 
                    Configure here the roles of your application 
                    and the allowed url patterns like the following example
                    /**=ROLE_USER,ROLE_ADMIN
                    /admin/*=ROLE_ADMIN
                  -->
                  /**=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>
              <!-- role prefix configurable -->
              <prop key="acegi.role.prefix">ROLE_</prop>
              .....
          </props>
      </property>
  </bean>
  <!-- Acegi role list -->
  <bean id="openfrwk.roles"
        class="org.springframework.beans.factory.config.ListFactoryBean">
     <description/>
     <property name="sourceList">
          <list>
            <!-- the specific roles of your application -->
            <value>ROLE_ADMIN</value>
		    <value>ROLE_USER</value>
          </list>
     </property>
  </bean>
              
            

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

             
....
<bean id="web.propertyConfigurer"
      class="org.nexopenframework.spring.config.PropertyPlaceholderConfigurer">
<!-- PersistenceManager support -->
<!-- the identifier of the named query -->
<prop key="openfrwk.acegi.pm.queryName">myCustomLoadUser</prop>
<!-- the named parameter of the above query -->
<prop key="openfrwk.acegi.pm.usernameParameter">name</prop>
<prop key="openfrwk.acegi.pm.forceInitialization">true</prop>
......
             
            

             
@javax.persistence.NamedQueries({
	@javax.persistence.NamedQuery(name="myCustomLoadUserFetch", 
	            query="select distinct cu from CustomUser cu 
	                   join fetch cu.roles roles where cu.username=:name"),
	@javax.persistence.NamedQuery(name="myCustomLoadUser", 
	            query="from CustomUser cu where cu.username=:name")
})
             
            

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

             
....
<bean id="web.propertyConfigurer"
      class="org.nexopenframework.spring.config.PropertyPlaceholderConfigurer">
......
<!-- jpa support -->
<prop key="openfrwk.acegi.jpa.queryName">loadCustomUser</prop>
<prop key="openfrwk.acegi.jpa.usernameParameter">name</prop>
<prop key="openfrwk.acegi.jpa.forceInitialization">true</prop>
......
             
            

             
.....
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;
	}

	@Password
	public 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;
	}
	....
             
            

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

             
<!-- Acegi Security Framework -->
<!-- User details resolution -->
<import resource="classpath:/META-INF/spring/openfrwk-module-security-userdetails.xml"/>
              
            

             
....
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;
    }
	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;
  }
	
}
             
            

             
....
<bean id="web.propertyConfigurer"
      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>  
             
            

TO BE DOCUMENTED

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

             
<!-- Acegi Security Framework -->
<!-- User details resolution -->
<import resource="classpath:/META-INF/spring/openfrwk-module-security-auth.siteminder.xml"/>
              
            

TO BE DOCUMENTED

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

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

		   
.....            
<!-- MultiModules support -->
<!--  if you wish to use channel security, add "channelProcessingFilter," in front
	   of "httpSessionContextIntegrationFilter" in the list below -->
<bean id="multiFilterChainProxy"
	class="org.nexopenframework.security.acegi.util.FilterChainProxy">
  <property name="filterInvocationDefinitionSource">
	<value>
	  CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
	  PATTERN_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>
	<!-- 
	     If true, will always redirect to the value of getDefaultTargetUrl 
	     upon successful authentication, irrespective of the page 
	     that caused the authentication request (defaults to false) 
	-->
	<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">
		<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 following property belonging to the property of bean PropertyPlaceholderConfigurer in the above mentioned applicationContex.xml

             
 .....            
<bean
  class="org.nexopenframework.spring.config.PropertyPlaceholderConfigurer" 
  id="web.propertyConfigurer">
  <property name="ignoreResourceNotFound" value="true"/>
  <property name="locations">
     <list>
       <!-- classpath properties file for overwritten this default properties -->
       <value>classpath:acegi.properties</value>
     </list>
  </property>
  <!-- Acegi configuration -->
 <property name="properties">
     <props>
         ......
         <!-- multimodule support -->
         <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 in the 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

          
......
<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 a folder 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 this module. 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  
           
      

TO BE DOCUMENTED

In case of XFire integration

			
<!-- ========================= RESOURCE DEFINITIONS ========================= -->
<bean id="nexopen.web.propertyConfigurer"
	  class="org.nexopenframework.spring.config.PropertyPlaceholderConfigurer">
  <property name="ignoreResourceNotFound" value="true" />
  <!-- XFire configuration -->
  <property name="properties">
	<props>
     <!-- 
       configuration value for webservices using XFire. 
       This indicates that must keep the servlet path to
       perform a lookup into the registered webservices with xfire
      -->
      <prop key="openfrwk.xfire.alwaysUseFullPath">true</prop>
	</props>
  </property>
</bean>			
			
		

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

			
<!-- ========================= WEB SERVICES DEFINITIONS ========================= -->
<!-- XFire web services annotations -->
<!-- IMPORTANT NOTE: For web services with auto-discovery strategy, this the correct place to be defined, 
	 at difference from older versions of framework where was defined in the 'nexopen-servlet.xml' file.
-->
<!-- uncomment if you plan to use webservices support in your application -->
<bean id="webAnnotations"
	class="org.codehaus.xfire.annotations.jsr181.Jsr181WebAnnotations" />			
			
		

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

In order to retrieve the implemented Marshaller, we can use the MarshallerHolder a custom class which keeps an 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 to properly use this class, you must declare into a Spring XML configuration file

    
 <!-- MarshallerHolder -->
<bean id="marshaller.holder" 
      class="org.nexopenframework.xml.binding.client.MarshallerHolder">
   <description>Holder of the Marshaller</description>
</bean>    
     
    

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

        
 <!-- ========================= XSTREAM SUPPORT ========================================= -->
 <!-- XStream beans support -->
 <!-- aliases -->
 <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"/>
       <!-- data element is ignored -->
       <entry key="data" value="com.thoughtworks.xstream.mapper.Mapper$Null"/>
      </map>
    </property>
 </bean>
 <!-- converters -->
 <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>
 <!-- list of classes with JSR-175 metadata -->
 <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>        
        
        

        
....
<!-- use XStream support in your application -->
<import resource="classpath:/META-INF/spring/openfrwk-module-serialization-xstream.xml"/> 
     
       

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

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

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 of JAX-WS 2.0 when we speak about document/literal web services. This specification also belongs to JEE 5.0 spec.

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