

Overview

Version: 6.1.12-v.2

      ________                                           _.-````'-,_
     /  _____/  ___________  _____                   ,-'`           `'-.,_
    /   \  ___ /  _ \_  __ \/     \          /)     (\       9ci's       '``-.
    \    \_\  (  <_> )  | \/  Y Y  \        ( ( .,-') )    Yak Works         ```
     \______  /\____/|__|  |__|_|  /         \ '   (_/                         !!
            \/                   \/           |       /)           '           !!!
  ___________           .__                   ^\    ~'            '     !    !!!!
  \__    ___/___   ____ |  |   ______           !      _/! , !   !  ! !  !   !!!
    |    | /  _ \ /  _ \|  |  /  ___/            \Y,   |!!!  !  ! !!  !! !!!!!!!
    |    |(  <_> |  <_> )  |__\___ \               `!!! !!!! !!  )!!!!!!!!!!!!!
    |____| \____/ \____/|____/____  >               !!  ! ! \( \(  !!!|/!  |/!
                                  \/               /_(      /_(/_(    /_(  /_(   
         Version: 7.3.77

JAVA 11 required for 7.3.28+ to prep for spring 6.

6.1.x is for grails 3.3.x and gorm 6.1.x

7.0.8-vX is for grails 4.x and gorm 7.0.8

7.3.20+ is for grails 5.x and gorm 7.3+ , see notes

repositories {
  //jcenter shutdown, use mavenCentral
  mavenCentral()
}
...
implementation "org.yakworks:gorm-tools:7.3.23"
etc...

Libs

• org.yakworks:gorm-tools - main plugin for the base gorm-tools extensions
• org.yakworks:boot-security - implementations of the domains for security, audit stamp traits and events.
• org.yakworks:gorm-rest - foundation and ASTs for automated rest api from gorm domains
• org.yakworks:gorm-openapi - gorm swagger and json schema foundation.
• org.yakworks:gorm-etl - Extract, Transform, Load for creating Excel and CSV

Security

• org.yakworks:security-core - Dependency free, Simple facade interfaces and impls for User/Subject and Roles/Permissions
• org.yakworks:boot-security - Spring Security with setup for basic, saml2, oauth. Depends only on spring boot and security
• org.yakworks:boot-security-gorm - gorm entities and support for Users/Roles

Rally

• org.yakworks:rally-domain - A sort of TCK. Opinionated CRM like models that serve as foundation for our business apps. Also used for examples and testing.
• examples/rcm-api - Integration tests and another TCK app. front rally-domain with rest api and tests out gorm-rest lib.
• Testing Helper Libs
• org.yakworks:gorm-test-support - Testing framework for gorm domains
• org.yakworks:gorm-test-domain - common domain model used for tests. KitchenSink is commonly used in tests

Test and Example Projects

• examples/testify - Integration tests for gorm-tools and the others. rally-domain has its own integration tests
• examples/resitfy - Playground for simple rest app
• examples/benchmarks - currenty non-functional but proves out performance benchmarks for high transaction and async/parralel processins
• boot-security-shiro - FUTURE USE for using shiro or shiro like permissions with spring-security

Groovy 3, Grails 5 and Gorm 7.3

Versioning will track the gorm.version for example gorm-tools 7.3.20, 7.3.21, etc will be compiled against gorm.version 7.3.2, 7.3.31 -> gorm.version 7.3.3 etc...

Purpose

Gorm-tools allows your Grails/Gorm project to start with a design of best practices that they can customize along the way. This brings an opinionated SpringBoot based starting point to a Grails/Gorm project but without being locked in. Developers are free to easily customize, replace and disable these patterns when their opinions differ.

Overview

This is a library of tools to help standardize and simplify the service and Restful controller layer business logic for domains and is the basis for the Gorm Rest API plugin.

Gorm-Tools is the next iteration on the DAO plugin and has been in use for about 10 years processing millions of transactions per day.

There are 3 primary patterns this library enables as detailed below for Repositories, Mango ( A mongo/graphql like query way to get gorm entity data with a Map) and Batch or Bulk inserting and updating with data binding

Domain Repository Services

jump to reference

A repository is a Domain Driven Design pattern. Used a a place logic to validate, bind, persist and query data that resides either in a database or NoSql (via GORM usually of course). The design pattern here is a bit similiar to Spring's Repository pattern and Grails GORM's new Data Services pattern.

Goals

• Standardization: a clean common pattern across our apps for domain service layer logic that reduces boiler plate in both services as well as controllers.
• Transactional Saves: every save() or persist() is wrapped in a transaction if one doesn't already exist. This is critical when there are cascading saves and updates.
• RuntimeException Rollback by default: saves or persist() always occur with failOnError:true so a RuntimeException is thrown for both DataAccessExceptions as well a validation exceptions. This is critical for deeply nested domain logic dealing with saving multiple domains chains.
• Events & Validation: the Repository allows a central place to do events such as beforeSave, beforeValidate, etc so as not to pollute the domain class. This pattern makes it easier to keeps the special logic in a transaction as well. Allows validation outside of constraints to persistence without needing to modify the domain source.
• Events with Flushing: As mentioned in the Gorm docs, "Do not attempt to flush the session within an event (such as with obj.save(flush:true)). Since events are fired during flushing this will cause a StackOverflowError.". Putting the event business logic in the Repository keeps it all in a normal transaction and a flush is perfectly fine.
• Easy Override/Replace Plugin's Domain Logic: Since the Repository is a service this also easily allows default logic in a provided plugin to be overriden in an application. For example, I may have a CustomerRepo in a plugin that deals with deault common logic to validate address. I can then implement a CustomerRepo in an application and it will override the spring bean just as it does for a service.

Fast Data Binder & Batch Insert/Update

We process millions of transactions per day and needed more performant binding performance.

Goals

• FAST Data Binding Service: databinding from maps (and thus JSON) has to be fast. We sacrfice a small amount of functionality for a big performance gain Maps and json are a first class citizen in the data service layer instead of the controller layer. Eliminates boiler plate in getting data from the database to Gorm to JSON Map then back again.
• Asynchronous batch processing PERFORMANCE: GORM insert and updates can be chunked and processed in parrallel using GPARS or RxJava making it easy to processes millions of records from JSON, CSV or Excel

JSON Query and Filtering (Mango Query)

The primary motive here is to create an easy dynamic map based way to query any Gorm Datastore (SQL or NoSQL). Using a simple map that can come from json, yaml, groovy config etc... A huge motivating factor being able is to be able to have a powerful and flexible way to query using json from a REST based client without having to use GraphQL (the only other clean alternative) The Repositories and RestApiController come with a query(criteriaMap, closure) method. It allows you to get a paginated list of entities restricted by the properties in the criteriaMap.

• A lot of inspiration was drawn from Restdb.io
• the query language is similar to Mongo's
• and CouchDB's new Mango selector-syntax .
• Also inspired by json-sql

Whilst selectors have many similarities with MongoDB query documents, these arise more from a similarity of purpose and do not necessarily extend to commonality of function or result.

Example for example, sending a JSON search param that looks like this

{
  "name": "Bill%",
  "type": "New",
  "age": {"$gt": 65}
}

would get converted to the equivalent criteria

criteria.list {
    ilike "name", "Bill%"
    eq "type", "New"
    gt "age", 65
}

Developer Notes

Make

while gradle is the build tool behind spring/grails, make is used for consitency to run gradle and use docker and setting up env for testing

run make to see help

run make check for full tests

or run ./gradlew check

Running docs locally

run make help for latest targets

make docmark.start

Publishing Plugin Releases

See Developer Docs for info on our release process

Using latests SNAPSHOT

Configure 9ci repo in build.gradle

repositories {
  maven { url "http://repo.9ci.com/oss-snapshots" }
 }

See version.properties for snapshot version

dependencies {
 compile('org.grails.plugins:gorm-tools:x.y.z-SNAPSHOT') { changing = true } 
}

Docs Links

DOCS ARE REALLY OUT OF DATE AND BEING UPDATED FOR BREAKING CHANGES after 6.1.12-v.X ALSO MERGING IN DOCS FOR THE REST-API AND AUDITSTAMP THAT WAS MERGED INTO HERE More breaking changes in 7.0.8-v6. is required on domain entity now or it needs to implement @GormRepoEntity

RELEASE NOTES

Guide	API
Released Docs	Released Api
snapshot	snapshot