Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Issue 1181 - Minor fixes for Panache documentation #1183

Merged
merged 2 commits into from
Mar 5, 2019
Merged

Issue 1181 - Minor fixes for Panache documentation #1183

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c153cd6
Issue 1181 - Minor fixes for Panache documentation
emmanuelbernard Mar 4, 2019
3761e2b
Update docs/src/main/asciidoc/panache-jpa-guide.adoc
gsmet Mar 5, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 28 additions & 7 deletions docs/src/main/asciidoc/panache-jpa-guide.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Panache focuses on making your entities trivial and fun to write in {project-nam

== First: an example

What we're doing in Panache is allow you to write your Hibernate entities like this:
What we're doing in Panache is allow you to write your Hibernate ORM entities like this:

[source,java]
--
Expand All @@ -31,8 +31,11 @@ public class Person extends PanacheEntity {
}
--

You have noticed how much more compact and readable the code is?
Does this look interesting? Read on!

NOTE: the `list()` method might be surprising at first. It takes fragments of HQL (JP-QL) queries and contextualize the rest. That makes for very concise but yet readable code.

== Setting up and configuring Panache JPA

To get started:
Expand Down Expand Up @@ -117,10 +120,11 @@ public class Person extends PanacheEntity {

And thanks to our field access rewrite, when your users read `person.name` they will actually call your `getName()` accessor,
and similarly for field writes and the setter.
This allows for proper encapsulation at runtime as all fields calls will be replaced by the corresponding getter/setter calls.

== Most useful operations

Once you have written your entity, here are the most common operations you would be able to do:
Once you have written your entity, here are the most common operations you will be able to do:

[source,java]
--
Expand Down Expand Up @@ -164,7 +168,15 @@ Person.delete("status", Status.Alive);
Person.deleteAll();
--

Naturally, all `list` methods have equivalent `stream` versions.
All `list` methods have equivalent `stream` versions.

[source,java]
--
List<String> namesButEmmanuels = Person.streamAll()
.map(p -> p.name.toLowerCase() )
.filter( n -> ! "emmanuel".equals(n) )
.collect(Collectors.toList());
--

== Paging

Expand Down Expand Up @@ -193,6 +205,12 @@ int numberOfPages = livingPersons.pageCount();

// get the total number of entities returned by this query without paging
int count = livingPersons.count();

// and you can chain methods of course
return Person.find("status", Status.Alive)
.page(Page.ofSize(25))
.nextPage()
.stream()
--

The `PanacheQuery` type has many other methods to deal with paging and returning streams.
Expand All @@ -211,6 +229,9 @@ But these methods also accept an optional `Sort` parameter, which allows your to
[source,java]
--
List<Person> persons = Person.list(Sort.by("name").and("birth"));

// and with more restrictions
List<Person> persons = Person.list("status", Sort.by("name").and("birth"), Status.Alive);
--

The `Sort` class has plenty of methods for adding columns and specifying sort direction.
Expand Down Expand Up @@ -270,7 +291,7 @@ Or by name using a `Map`:
Map<String, Object> params = new HashMap<>();
params.put("name", "stef");
params.put("status", Status.Alive);
Person.find("name = :name and status = :status", "stef", Status.Alive);
Person.find("name = :name and status = :status", params);
--

Or using the convenience class `Parameters` to either build a `Map` or just use as-is:
Expand Down Expand Up @@ -337,7 +358,7 @@ go back to specifying your ID and using getters and setters if that's your thing

== Custom IDs

IDs are often a touchy subject, and not everyone's up for letting them handled by the framework, but once again we
IDs are often a touchy subject, and not everyone's up for letting them handled by the framework, once again we
have you covered.

You can specify your own ID strategy by extending `PanacheEntityBase` instead of `PanacheEntity`. Then
Expand Down Expand Up @@ -375,7 +396,7 @@ public class PersonRepository implements PanacheRepositoryBase<Person,Integer> {

== How and why we simplify Hibernate mapping

When it comes to writing hibernate entities, there are a number of annoying things that users have grown used to
When it comes to writing Hibernate ORM entities, there are a number of annoying things that users have grown used to
reluctantly deal with, such as:

- Duplicating ID logic: most entities need an ID, most people don't care how it's set, because it's not really
Expand Down Expand Up @@ -408,4 +429,4 @@ your entity `Person` by typing `Person.` and getting completion for all the oper
`Person.find("name = ?1 and status = ?2", "stef", Status.Alive)` or even better
`Person.find("name", "stef")`.

That's all there is to it: with Panache, Hibernate has never looked so trim.
That's all there is to it: with Panache, Hibernate has never looked so trim and neat.