Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/adminfaces/admin-persistence

Provides CRUD utilities for AdminFaces based applications.
https://github.com/adminfaces/admin-persistence

Last synced: 8 months ago
JSON representation

Provides CRUD utilities for AdminFaces based applications.

Awesome Lists containing this project

README 

          
= Admin Persistence

:page-layout: base

:source-language: java

:icons: font

:linkattrs:

:sectanchors:

:sectlink:

:numbered:

:doctype: book

:toc: preamble

:tip-caption: :bulb:

:note-caption: :information_source:

:important-caption: :heavy_exclamation_mark:

:caution-caption: :fire:

:warning-caption: :warning:



image:https://maven-badges.herokuapp.com/maven-central/com.github.adminfaces/admin-persistence/badge.svg["Maven Central",link="http://search.maven.org/#search|ga|1|admin-persistence"]

image:https://travis-ci.org/adminfaces/admin-persistence.svg[Build Status (Travis CI), link=https://travis-ci.org/adminfaces/admin-persistence]

image:https://coveralls.io/repos/github/adminfaces/admin-persistence/badge.svg?branch=master[Coverage, link=https://coveralls.io/r/adminfaces/admin-persistence]

image:https://badges.gitter.im/Join%20Chat.svg[link="https://gitter.im/adminfaces?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"]



CRUD operations like a breeze for https://github.com/adminfaces[AdminFaces applications^] based on https://deltaspike.apache.org/[Apache DeltaSpike^] Data module.



== Prerequisites



This module depends on `JSF`, `CDI` and `JPA` and was tested with respective implementations and versions:



|===



|JSF | CDI | JPA



|Mojarra 2.2| Weld 2.3| Hibernate 5.0



|Mojarra 2.2| Weld 2.2| Hibernate 4.3



|MyFaces 2.1| OpenWebBeans 1.7.4| Eclipselink 2.6



|===



== Usage



Following are the steps you need to follow in order to use `Admin Persistence`:



. *Classpath*

+

First include it in your classpath:

+

----



    com.github.adminfaces

    admin-persistence

    1.0.7



----

+

[IMPORTANT]

======

Admin persistence will bring the following transitive dependencies:



----



    org.primefaces

    primefaces

    7.0



    org.apache.deltaspike.core

    deltaspike-core-impl

    1.8.2



    org.apache.deltaspike.core

    deltaspike-core-api

    1.8.2



    org.apache.deltaspike.modules

    deltaspike-data-module-api

    1.8.2



    org.apache.deltaspike.modules

    deltaspike-data-module-impl

    1.8.2



----    



Of cource you can override them in your pom.xml as needed.

======



. *JPA Metamodel*

+

As Admin Persistence uses https://deltaspike.apache.org/documentation/data.html#_jpa_criteria_api_support[DeltaSpike `typesafe` criteria^] you'll need to generate JPA metamodel. There are various ways to do that, here is a maven plugin example:

+

[source,xml]

----



    com.mysema.maven

    apt-maven-plugin

    1.1.3

    

        

            metamodel

            

                process

            

            

                target/generated-sources/metamodel

                org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor

            

        

    

    

        

            org.hibernate

            hibernate-jpamodelgen

            4.3.8.Final

        

    



----

+

TIP: See https://docs.jboss.org/hibernate/orm/5.0/topical/html/metamodelgen/MetamodelGenerator.html#_usage_within_the_ide[this tutorial^] for configuring it on your IDE.



. *Entity Manager*

+

Admin persistence needs an exposed `entity manager` as CDI Bean, you can do that by using a http://docs.oracle.com/javaee/6/tutorial/doc/gjdid.html[CDI producer^]:

+

[source,java]

----

@ApplicationScoped

public class EntityManagerProducer {



    @PersistenceContext

    EntityManager em;



    @Produces

    public EntityManager produce() {

        return em;

    }

}

----



. *Persistence Entity*

+

Every JPA entity must be typed as a *PersistenceEntity*, it is an interface with only a method, `getId()`:

+

[source,java]

----

import com.github.adminfaces.persistence.model.PersistenceEntity;



@Entity

@Table(name = "car")

public class Car implements PersistenceEntity {



@Override

public Integer getId() {

        return id;

    }



}

----

+

TIP: You can `extend` *BaseEntity* to gain `equals()`,`hashCode()` and `toString()`.



. *Service layer*

+

Now to create a service which will hold your business logic you need to extend *CrudService*:

+

[source,java]

----

@Stateless

public class CarService extends CrudService  {



}

----

+

TIP: Full source code for CarService can be https://github.com/adminfaces/admin-starter-persistence/blob/master/src/main/java/com/github/adminfaces/starter/service/CarService.java#L27[found here^].

+

NOTE: For some examples of CrudService usage https://github.com/adminfaces/admin-persistence/blob/master/src/test/java/com/github/adminfaces/persistence/CrudServiceIt.java#L24[see integration tests here^].



. *Controller*

+

Finally on the controller layer (JSF managed beans) you need to extend *CrudMB* which will enable CRUD support for your JSF pages:

+

[source,java]

----

@Named

@ViewScoped

public class CarListMB extends CrudMB implements Serializable {



    @Inject

    CarService carService;



    @Inject

    @Service

    CrudService crudService; //generic injection



    @Inject

    public void initService() {

       setCrudService(carService); <1>

    }



}

----

<1> Needed by CrudMB otherwise it will throw an exception asking for CrudService initialization.

+

[TIP]

====

You can use *@BeanService* annotation to provide CrudService:



[source,java]

----

@Named

@ViewScoped

@BeanService(CarService.class)//use annotation instead of setter injection

public class CarListMB extends CrudMB implements Serializable {



}



----

====

+

TIP: Full source code for CarListMB can be https://github.com/adminfaces/admin-starter-persistence/blob/master/src/main/java/com/github/adminfaces/starter/bean/CarListMB.java#L24[found here^].



== Pagination



Real pagination involves lots of boilerplate code, in admin-persistence it is a matter of using a Primefaces lazy datatable and bind it to the CrudMB `list` variable:



.xhtml page

[source,html]

----

 

----



TIP: Full source code for this xhtml page can be https://github.com/adminfaces/admin-starter-persistence/blob/master/src/main/webapp/car-list.xhtml[found here^].



== Pagination filtering



For filtering on the lazy datatable you just need to override `configRestrictions` method in the managed bean's service (the service we set in CarListMB) and add your restrictions based on a filter:



.CarService

[source,java]

----

protected Criteria configRestrictions(Filter filter) {



        Criteria criteria = criteria();



        //create restrictions based on parameters map

        if (filter.hasParam("id")) {

            criteria.eq(Car_.id, filter.getIntParam("id"));

        }



        if (filter.hasParam("minPrice") && filter.hasParam("maxPrice")) {

            criteria.between(Car_.price, filter.getDoubleParam("minPrice"), filter.getDoubleParam("maxPrice"));

        } else if (filter.hasParam("minPrice")) {

            criteria.gtOrEq(Car_.price, filter.getDoubleParam("minPrice"));

        } else if (filter.hasParam("maxPrice")) {

            criteria.ltOrEq(Car_.price, filter.getDoubleParam("maxPrice"));

        }



        //create restrictions based on filter entity

        if (has(filter.getEntity())) {

            Car filterEntity = filter.getEntity();

            if (has(filterEntity.getModel())) {

                criteria.likeIgnoreCase(Car_.model, "%"+filterEntity.getModel());

            }



            if (has(filterEntity.getPrice())) {

                criteria.eq(Car_.price, filterEntity.getPrice());

            }



            if (has(filterEntity.getName())) {

                criteria.likeIgnoreCase(Car_.name, "%"+filterEntity.getName());

            }

        }

        return criteria;

    }



----



[NOTE]

====

`filter.params` is a hashmap used to add arbitrary parameters and `filter.entity` is for entity specific ones, see https://github.com/adminfaces/admin-starter-persistence/blob/499a5d738fff90b2d3e9934b2451b90d456575e7/src/main/webapp/car-list.xhtml#L144[search dialog^] which populates those attributes:



[source,html]

----



    





    

        

        

    





    





    





    


        

    


    


        

    






    


        

    


    


        

    




----



====



IMPORTANT: Any datatable update (ajax or not) will trigger the configRestrictions.



NOTE: Besides filtering the `filter` helper class also holds *pagination* and *sort* information.



[WARNING]

====



By default filters are saved on `Session` so when user goes to another page (e.g a detail) and comes back to list the tables keeps it's previous filters.



You can change this behavior by overriding  keepFiltersInSession method on your Bean:



.CarListMB

[source,java]

----

    @Override

    public boolean keepFiltersInSession() {

        return false;

    }

----



====



== Sample application



For an example project using Admin Persistence https://github.com/adminfaces/admin-starter-persistence[see admin-starter-persistence^].



TIP: For a `composite-key` demo https://github.com/adminfaces/admin-starter-persistence/tree/composite-key[see this branch^] of admin-starter.



== Snapshots



Snapshots are published to https://oss.sonatype.org/content/repositories/snapshots/com/github/adminfaces/[maven central^] on each commit, to use it just declare the repository below on your `pom.xml`:



[source,xml]

----



    

        

        snapshots

        libs-snapshot

        https://oss.sonatype.org/content/repositories/snapshots

    



----