KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #typescript #claude-code #codex #dsh #dsh-plugin #ai-agent #ai-agents #deepseek-harness #agent-skills #macos #cli

gorm-tools

★ 25 Open GitHub ↗

repository, data services, mango query tools plugin for grails gorm

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![CircleCI](https://img.shields.io/circleci/project/github/yakworks/gorm-tools/master.svg?longCache=true&style=for-the-badge&logo=circleci)](https://circleci.com/gh/yakworks/gorm-tools)
[![9ci](https://img.shields.io/badge/BUILT%20BY-9ci%20Inc-blue.svg?longCache=true&style=for-the-badge)](http://9ci.com)
<img src="https://forthebadge.com/images/badges/built-with-love.svg" height="28">
<img src="https://forthebadge.com/images/badges/gluten-free.svg" height="28">
<img src="https://forthebadge.com/images/badges/made-with-groovy.svg" height="28">

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

## 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](https://yakworks.github.io/gorm-rest-api/){.new-tab}.

Gorm-Tools is the next iteration on the [DAO plugin](https://grails.org/plugin/dao) 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
<small>[jump to reference](docs/repository/ref.md)</small>

A repository is a [Domain Driven Design](docs/usefulLinks.md#references) 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]

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

``` js
{
  "name": "Bill%",
  "type": "New",
  "age": {"$gt": 65}
}
```
would get converted to the equivalent criteria

```javascript
criteria.list {
    ilike "name", "Bill%"
    eq "type", "New"
    gt "age", 65
}
```
[repository docs]: docs/repository/ref.md
[Spring's Repository pattern]:https://docs.spring.io/spring-data/data-commons/docs/current/reference/html/
[Data Services]:http://gorm.grails.org/6.1.x/hibernate/manual/#dataServices
[Restdb.io]:https://restdb.io/docs/querying-with-the-api
[Mongo's]:https://docs.mongodb.com/manual/reference/operator/query/
[Mango selector-syntax]:http://docs.couchdb.org/en/latest/api/database/find.html#selector-syntax
[json-sql]:https://github.com/2do2go/json-sql/

## 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](docs/developer.md) for info on our release process

**Using latests SNAPSHOT**

Configure 9ci repo in build.gradle

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

See [version.properties](version.properties) for snapshot version

```groovy
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](docs/release-notes.md)

| Guide | API | 
|------|--------|
|[Released Docs](https://yakworks.github.io/gorm-tools/) | [Released Api](https://yakworks.github.io/gorm-tools/api)
|[snapshot](https://yakworks.github.io/gorm-tools/snapshot) | [snapshot](https://yakworks.github.io/gorm-tools/snapshot/api)

gorm-tools

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README