3. Core functionnalities

RESThub core has been designed to give your a coherent technology stack and additional functionalities, thus helping you to build your application faster.

You should import the following module in your application to be able to use RESThub in your application :

<dependency>
   <groupId>org.resthub</groupId>
   <artifactId>resthub-core</artifactId>
   <version>1.1</version>
</dependency>

Functionalities available from the core are described below.

3.1. Application context

Since RESThub application context functionalities extend Spring 3 ones, you should carefully read Spring 3 reference manual.

3.1.1. Application context scanning

RESThub default configuration scan all resthubContext.xml and applicationContext.xml files from your classpath. This naming convention and scanning process allows you to build easily a simple plugin-like system, when your functionalities are automatically discovered within the classpath.

You can provide an applicationContext.xml file by module to configure your application.

3.1.2. Beans declaration and injection

You should use J2EE6 annotations to declare and inject your beans.

To declare a bean :

@Named("beanName")
public class SampleClass {

}

To inject a bean :

@Inject
@Named("beanName")
public void setSampleProperty(...) {

}

Best practice : Bean injection on setter is better than on protected or private property because it allows subclasses to override this injection.

3.1.3. Environment specific properties

There is various way to configure your environment specific properties in your application, the one described bellow is the more simple and flexible one we have found.

Maven filtering (search and replace variables) is not recommended because it is done at compile time (not runtime) and makes usually your JAR/WAR specific to an environment. This feature can be useful when defining your target path (${project.build.directory}) in your src/test/applicationContext.xml for testing purpose.

Spring properties placeholders allow you to reference in your application context files some values defined in external properties. This is useful in order to keep your application context generic (located in src/main/resources or src/test/resources), and put all values that depends on the environment (local, dev, staging, production) in external properties. These dynamic properties values are resolved during application startup.

In order to improve testabilty and extensibility of your modules, you should set default values in case no properties are found in the classpath - if properties are found, then default values are obviously overriden. It is acheived by declaring the following lines in your applicationContext.xml :

<context:property-placeholder location="classpath*:mymodule.properties"
                              properties-ref="databaseProperties"
                              ignore-resource-not-found="true"
                              ignore-unresolvable="true" />

<util:properties id="mymoduleProperties" >
   <prop key="param1">param1Value</prop>
   <prop key="param2">param2Value</prop>
</util:properties>

You should now be able to inject dynamic values in your beans :

<bean id="sampleBean" class="org.mycompany.MyBean">
   <property name="property1" value="${param1}"/>
   <property name="property2" value="${param2}"/>
</bean>

You can also inject direcly these values in your Java classes thanks to the @Value annotation :

@Value("${param1}")
protected String property1;

Or :

@Value("${param1}")
protected void setProperty1(String property1) {
   this.property1 = property1;
}

3.1.4. Disable XSD validation

By default, Spring 3 validation XML schema is declared in your application context. This validation could prevent you to use properties placeholder decribed previously, because you will put a value like ${paramStatus} in a boolean attribute that can take only true or false value.

Since there is no way to fix that in vanilla Spring 3, RESThub provides a way to disable application context XSD validations.

In order to disable validation in your unit tests, annotate your test classes with :

@ContextConfiguration(loader = ResthubXmlContextLoader.class)

In order to disable validation in your web application, you should declare in the web.xml file (ResthubXmlWebApplicationContex is located in resthub-web-server dependency) :

<context-param>
   <param-name>contextClass</param-name>
   <param-value>org.resthub.web.context.ResthubXmlWebApplicationContext</param-value>
</context-param>

3.2. Persistence

3.2.1. Default configuration

RESThub comes with a preconfigured Spring/Hibernate stack, with a connection to an H2 embedded databse, pooling and cache. Every configured bean could be customized by redefining the bean in your applicationContext.xml files, or more easily by putting a database.properties in your project resources.

Please find bellow the properties keys and default values of database.properties

dataSource.driverClassName = org.h2.Driver
dataSource.url = jdbc:h2:mem:resthub;DB_CLOSE_DELAY=-1
dataSource.maxActive = 50
dataSource.maxWait = 1000
dataSource.poolPreparedStatements = true
dataSource.username = sa
dataSource.password =

hibernate.show_sql = false
hibernate.dialect = org.hibernate.dialect.H2Dialect
hibernate.format_sql = true
hibernate.hbm2ddl.auto = update
hibernate.cache.use_second_level_cache = true
hibernate.cache.provider_class = net.sf.ehcache.hibernate.SingletonEhCacheProvider
hibernate.id.new_generator_mappings = true

Please notice that the new Hibernate id generator is used, as recommended in Hibernate documentation. It allows much better performance (there’s no need of a SELECT request before an INSERT request).

3.2.2. Extend JPA properties

RESThub provides some core jpa properties to configure entityManagerFactory in resthubContext.xml (real values are provided thanks to placholders - cf. database.properties configuration) :

<util:map id="resthubCoreJpaProperties">
             <entry key="hibernate.dialect" value="${hibernate.dialect}" />
             <entry key="hibernate.format_sql" value="${hibernate.format_sql}" />
             <entry key="hibernate.hbm2ddl.auto" value="${hibernate.hbm2ddl.auto}" />
             <entry key="hibernate.cache.use_second_level_cache" value="${hibernate.cache.use_second_level_cache}" />
             <entry key="hibernate.cache.provider_class" value="${hibernate.cache.provider_class}" />
             <!-- New ID generator is now recommanded to true for all projects. It provides
                     betters performances and better generation behaviour than default one. More
                     details on http://docs.jboss.org/hibernate/core/3.6/reference/en-US/html/mapping.html#mapping-declaration-id-enhanced -->
             <entry key="hibernate.id.new_generator_mappings" value="${hibernate.id.new_generator_mappings}" />
     </util:map>

In order to allow to add extended and additional JPA or Hibernate configuration properties in your own project using RESThub, we provide a dedicated extension point thanks to spring maps and its merge capacity.

Indeed, resthub entityManagerFacory includes an larger map of properties with an external bean reference :

  <bean id="entityManagerFactory"
          class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">

...

<property name="jpaProperties" ref="jpaProperties" />
  </bean>

  <bean id="jpaProperties" parent="resthubCoreJpaProperties">
          <property name="sourceMap">
                  <map merge="true"/>
          </property>
  </bean>

By default the map contains only core resthub jpa properties but if you need to add JPA or Hibernate properties, you only have to override the jpaProperties bean with your own configuration. Provided properties will be added to resthub core properties.

Just add in you applicationContext :

<bean id="jpaProperties" parent="resthubCoreJpaProperties">
        <property name="sourceMap">
                <map merge="true">
                        <entry key="my.key"
                                value="my.value" />
                </map>
        </property>
</bean>

3.2.3. Entity scan

RESThub allows to scan entities in different modules using the same PersitenceUnit, which is not possible with default Spring/Hibernate.

By default, the ScanningPersistenceUnitManager searches entities with the pattern “org.resthub.**.model”. To indicates different packages, you’ll have to override the bean definition in your own Spring configuration file.

<resthub:include-entities base-package="net.myProject.**.model" />

Now, entities within the net/myProject/**/model packages will be scanned.

Beware ! You have to be careful with the loading order of your spring configuration files. Reference the RESTHub file first (and don’t forget the * behind “classpath”), and then your files.

3.2.4. Interface only DAO

Hades is a really powerful Generic DAO framework, included by default in RESThub, which allows to write your DAO with only an interface (no implmentation needed).

Hades’ ability to generate DAO from interfaces is not activated by default in RESThub application, but could be with the following line in your applicationContext.xml.

<hades:dao-config base-package="org.mycompany.myproject.dao" />

3.3. Generic CRUD classes

RESThub provides some generic classes in order to quickly implement CRUD functionalities :

Provides some generic classes and interfaces for default DAO, service or controller.

• Dao : GenericDao default CRUD operation

  • interface GenericDao: generic DAO interface
  • class GenericJpaDao: generic DAO JPA implementation

• Generic CRUD services : RESThub provides a reusable service classes that implements by default CRUD operations.

  • interface GenericService: generic service interface
  • class GenericServiceImpl: generic service default implementation

For example, to define a CRUD interface for Booking class :

public interface BookingService extends GenericService<Booking, Long> {

}

3.4. Monitoring

RESThub provides some helpers to monitor your application. The monitoring service is based on JAMon (http://jamonapi.sourceforge.net/).

To monitor all methods of a Bean, add annotaion @Monitored upon the service’s implementation.

@Monitored
@Named("beanName")
public class SampleClass {

}

Note: You can exclude some methods by annotated this methods by @NotMonitored.

To activate this annotation add this bean post processor declaration into the application context:

<bean class="org.resthub.core.monitoring.MonitoringBeanPostProcessor" />

As soon this processor declared, all methods of the bean are logged in DEBUG output and compute to JAMon metrics.

JAMon metrics are accessible via the MonitorFactory.

for (Iterator<?> it = MonitorFactory.getFactory().iterator(); it.hasNext();) {
   System.out.println(it.next().toString());
}

See more way to view metrics at JAMon site.

Another cool feature is that you can monitor SQL orders. To do that edit database.properties and change the JDBC Driver by JAMon one: