Big Panache API refactor

[FroMage]

Big Panache API refactor.

Project

• Dropped independent-projects/panache (since it cannot function without Quarkus)
• Moved extensions/panache/runtime|deployment into extensions/panache/panache-jpa (subfolder for all panache modules)
• Moved panache API code inside shamrock-panache-jpa
• Added extensions/panache/common/runtime (shamrock-panache-jpa-runtime depends on it)
• Moved non-JPA API code into shamrock-panache-common-runtime (because shamrock-panache-rx-runtime will use those classes)

Names

• Model is now called PanacheEntity (that's your entity base class with an ID)
  • original rationale was Model is clear for MVC, but @gsmet made a case that existing Hibernate users would look for Entity
  • cannot use Entity because @Entity is using it, so prefixing with Panache
• EntityBase is now called PanacheEntityBase (that's the entity base class if you specify your own ID)
• DaoBase is now called PanacheRepositoryBase and is parameterised with an extra ID type parameter
  • rationale is that cool kids now use Repository and not Dao
  • rationale for extra ID type parameter is to limit the findById argument (was Object)
• PanacheRepository is what people should extend for their repository
  • It specifies an ID of type Long
• JpaOperations is gone in impl package
• Query is now called PanacheQuery
  • rationale is that Query is super overused
• New class Panache with general operations
• New classes Parameters, Sort, Page in common
  • Turns out these names are also super overused

Per class changes

• PanacheEntity
  • now has a Long ID instead of Integer
  • we debated having a version field, but thought it was not very used
• PanacheEntityBase
  • save() is now called persist since it does not do persistOrUpdate anymore
  • find/count/delete now take either Object... for indexed params, or Map<String,Object or Parameters for named params
    • Parameters is a trivial Map builder with less ceremony than the JDK provides
  • find/count/delete now take an optional Sort for specifying sort columns and orders
    • rationale is that Spring users like that
  • new shortcut methods list/stream that call list/stream on find (for small tables with no paging)
  • list(query)/listAll(), find(query)/findAll(), stream(query)/streamAll() and delete(query)/deleteAll() but count(query)/count() to mark expensive/dangerous operations with All but count is harmfull and countAll seems weird
  • new methods persist(Iterable/Stream/Object[] to persist more than one entity
• PanacheRepositoryBase has the same changes
  • findById(Id) insteadof findById(Object) (because we can here, and we cannot for EntityBase)
• PanacheQuery
  • Added count() method which executes an HQL count for the query, which counts the number of results with no paging (it's cached)
  • Added nextPage(), previousPage(), firstPage(), lastPage(), hasNextPage(), hasPreviousPage(), Page page() and pageCount() that sometimes make use of the count() method when required
  • Renamed getFirstResult() to firstResult()
  • Renamed getSingleResult() to singleResult()
• Page
  • renamed of(size) to ofSize(size)
  • added Page index(newIndex) to change the page index
• Parameters
  • Usage is Parameters.with("foo", bar).and("gee", baz).map()
  • Could add Parameters.of(K, V), Parameters.of(K, V, K, V) like JDK 9 but really it's not more readable
  • Within an Entity I think we should add Parameters parameter(key, value) instance method that delegates to the Parameters.with just to get auto-scope
• Sort
  • static Sort.by(String column) to sort by one column ASC
  • static Sort.by(column, direction) to sort by one column
  • static Sort.by(column...) to sort by more than one column ASC (alias for Sort.ascending(column...))
  • static Sort.descending(column...) to sort by more than one column DESC
  • descending()/ascending()/direction(Direction) to change a sort direction (for all columns)
  • and(column) to add a column ASC
  • and(column, direction) to add a column
  • toOrderBy() not entirely sure it's useful to make it public, but it does what it says

[FroMage]

Summary updated

[FroMage]

@gsmet it passed CI :)

[gsmet]

Let's merge before the big renaming and discuss that more in depth next week.

[FroMage]

Thanks!

[emmanuelbernard]

Is there examples of usages (code example_, vs this list? That would help me.

[emmanuelbernard]

• new methods persist(Iterable/Stream/Object[] to persist more than one entity

Was it worth having? vs a foreach and passing EntityBase::persist or whatever the kool functional kids are doing?

[emmanuelbernard]

I can use .findAll() and pagination, right?

[FroMage]

Is there examples of usages, vs this list?

https://github.com/jbossas/protean-shamrock/blob/master/integration-tests/panache/src/main/java/io/quarkus/example/panache/TestEndpoint.java

Was it worth having? vs a foreach and passing EntityBase::persist

Some other frameworks have it, @gsmet said it would be useful. I figured it didn't harm, but it doesn't do more than what you suggested.

I can use .findAll() and pagination, right?

Yes, pagination is on the resulting PanacheQuery.

[FroMage]

@emmanuelbernard #1054 has the guide.