Persistence with JPA - Githubissues

Charlotte-Holt commented 4 years ago

This is a new concept topic that should include an introduction to persistence and JPA. JPA is provided by Jakarta, so this is an instance where developers will need to combine MP and Jakarta APIs. It's worth mentioning in the topic that we use EclipseLink, but users can replace this with Hibernate (https://developer.ibm.com/wasdev/blog/2014/02/12/hibernate-jpa-sample-using-alternative-jpa-provider/). In the topic, don't mention JPA 2.0 (as it's not in OL), only JPA 2.1 and later.

Also, explore whether a section on caching makes sense in the scope of this topic. Look at https://www.ibm.com/support/knowledgecenter/SSAW57_liberty/com.ibm.websphere.wlp.nd.multiplatform.doc/ae/twlp_admin_session_persistence.html and https://www.ibm.com/support/knowledgecenter/SSAW57_liberty/com.ibm.websphere.wlp.nd.multiplatform.doc/ae/twlp_admin_session_persistence_jcache.html for this information in the KC. Regarding these two session persistence topics, Alasdair had the following comments, "Talk about session persistence and why you'd choose one thing over the other. The current focus is Hazelcast but we're going to also be adding in Infinistan (RH Data Grid)." Config example issues already exist for sessionDatabase-1.0 (#1289) and sessionCache-1.0 (#1290).

Resources:

dmuelle commented 4 years ago

Rough draft is now up at https://draft-openlibertyio.mybluemix.net/docs/ref/general/#data-persistence-jpa.html

dmuelle commented 4 years ago

Requesting technical review from @frowe

frowe commented 4 years ago

@Charlotte-Holt In reading your first comment above, I don't think we should put the session persistence content in here, we should find a better place. Session persistence is a service the app server provides to web applications not an API for application dev like JPA. I agree we should discuss EclipseLink vs Hibernate, I was looking at that link to Brent's blog post about doing so (https://developer.ibm.com/wasdev/blog/2014/02/12/hibernate-jpa-sample-using-alternative-jpa-provider/), it appears the links in that post to repo content are all broken? @dmuelle Here's my comments on the draft

Replace occurrences of Java EE with Jakarta EE?
Is navigation working properly on draft docs? I noticed that if I click on either of the feature links in the final section, I can’t use the browser back button to return the JPA topic.
I think we should remove the overview sections, specifically the “Entities and persistence context”, “The EntityManager API”, and “Persistence units and the EntityManagerFactory interface” sections and focus on things that are OL specific like why would I use JPA over JBDC (for which we already have a section, maybe in round 2 of edits we can beef it up a bit), how do I choose whether to use the jpa or jpaContainer feature, and if I use the jpaContainer feature how do I configure it (since that info isn’t in the feature reference). The overview info is easily obtained via a google search, there are many good websites with this info.
The “JPA configuration with Open Liberty” section. The jpa-2.1/2.2 features do not enable the jpaContainer feature, the two are mutually exclusive. Instead of the existing “JPA configuration with Open Liberty“ section, consider something like this in which I try to address the above questions:

JPA for Open Liberty is supported by two mutually exclusive features, one that provides a default JPA implementation and one that allows the user to provide a JPA implementation of their choice. The JPA feature is configured by adding the feature name jpa-2.1 or later to the server configuration. When enabled, it will

expose the JPA specification interfaces
provide container-managed JPA integration
provide a default JPA implementation using the open source EclipseLink package.

Choose this feature if you want to develop applications using EclipseLink, or if you’re just getting started with JPA and don’t have a preference as to which implementation is used. If on the other hand, you have a need to use a JPA implementation other than EclipseLink, for example, Hibernate, use the JPA container feature (feature name jpaContainer-2.1 or later). This feature is similar to the one described above, but doesn’t provide a default JPA implementation and instead allows the configuration of any JPA implementation that meets the JPA specification. In addition to enabling this feature in the server configuration, you’ll need to configure the persistence provider and libraries. As an example, the following config snippet will allow use of the Hibernate JPA implementation instead of the default EclipseLink:

    <featureManager>
        <feature>jpaContainer-2.2</feature>
    </featureManager>

    <jpa defaultPersistenceProvider="org.hibernate.jpa.HibernatePersistenceProvider" />

    <library id="HibernateLib">
        <fileset dir="${shared.resource.dir}/jpa21_hibernate" includes="*.jar"/>
    </library>

dmuelle commented 4 years ago

@frowe - thanks for this feedback. I'll revise the doc accordingly. A couple points to clarify-

if the jpa-2.1 and jpaContainer-2.1 features are mutually exclusive, then we have a bug in our autogen feature doc. On the jpa-2.1 feature page, jpaContainer-2.1 is listed under Features that this feature enables. Then on the jpaContainer-2.1 page, jpa-2.1 is listed under Features that enable this feature . If that's not right, I can open a bug to fix the doc.
for the jpaContainer-2.1 page, we have an issue open to add config examples to that page. I'll pick up that issue and make sure any relevant config gets published at the same time as this doc.
JPA vs JDBC- how I can I fill this section out? Are there typical use cases where one is preferred over the other? Is there a SQL vs NoSQL issue that would influence a developers choice?
as far as removing the overview- I want to check with @lauracowen from a content strategy perspective- most of the docs we are writing for the OL site have a conceptual overview component. If this level of detail isn't useful, I can remove it. But- if I can improve it to make it more useful, thats preferable as having concise and accurate info increases the chance that users will find and use the docs and the product.

Thanks again

frowe commented 4 years ago

@dmuelle Ugg. I totally botched that, your analysis is correct, ignore my comment.

For your 2nd bullet above, the guide for developing microservice persistence may be a good source for sample content.

For your 3rd bullet, for one or more of the following reasons, I might choose JDBC over JPA for applications: 1) don't have a great deal of interaction with a database 2) don't need to support many different database vendors 3) the data model is fairly simple 4) the app developers have SQL experience

I might choose JPA over JDBC if my application: 1) interacts with one or more databases fairly regularly 2) needs to support multiple database vendors 3) complex data model 4) the app developers have mostly Java experience

To your last bullet, I think the "What is JPA" section is a good conceptual overview by itself. One of the things Karen is often talking about on our scrums is the mandate to greatly reduce the volume of content in IBM's docs. One way to do that is not try to educate developers on general content that they can consume from anywhere, and to instead focus on IBM's value and differentiation.

lauracowen commented 4 years ago

Regarding overviews, on re-reading the topic, I think @frowe makes a good point I'd be happy with reducing down the amount of generic basic JPA conceptual info and have more info about how it is on Open Liberty as @frowe suggests. Maybe keep the What is JPA? section with its example, which I think is useful, but then provide some good links to learn about the detail instead of the detailed sub-sections? Then (as @frowe suggests), provide more about the choices the developer has to make and why in order to get done what they need to do.

dmuelle commented 4 years ago

Thanks @lauracowen @frowe - draft is updated.

replaced occurrences of Java EE with Jakarta EE
added more info to JPA vs JDBC and JPA and Open Liberty sections
add the config Fred posted above to the JPA Container feature config example doc- see #1462
removed the “Entities and persistence context”, “The EntityManager API”, and “Persistence units and the EntityManagerFactory interface” sections. I could not find a great place to link out to in lieu of these sections- plenty of blogs, stack overflow etc out there but I'm not sure if the doc should link to those. The Oracle docs are fairly old and Jakarta really only offers the spec- not sure it's particularly useful to link to that. The info is easy enough to find though. Incidentally, most of my source material for this was the Liberty doc.

dmuelle commented 4 years ago

https://draft-openlibertyio.mybluemix.net/docs/ref/general/#data-persistence-jpa.html

frowe commented 4 years ago

Two comments and a question: "familiarity with SQL formatting." should be something like "familiarity with SQL." or "familiarity with SQL programming". In the final paragraph, it's not quite clear, at least to me, that the jpaContainer feature can be used by itself to configure another JPA provider. Perhaps some slight tweak. Did you look into the nav issue I mentioned in 2. above? It's annoying...

dmuelle commented 4 years ago

Agreed- it is annoying! But it's a known issue, specific to the draft site that will hopefully be fixed when they update the framework. This should not happen with docs that are published to the live site.

re jpaCopntainer- I'll make that clear. If I understand correctly- if you are using the jpa feature, you have the option not to use the default because jpaContainer is automatically enabled. But if you know you don't want to use the default anyway, you can install jpaContainer instead of jpa, since the only real difference between them is that jpaContainer doesn't include a default implementation. Is that accurate?

dmuelle commented 4 years ago

Hi @frowe , I've updated the draft per your comments. Hopefully the configuration section is a little more clear about jpaContainer vs jpa

https://draft-openlibertyio.mybluemix.net/docs/ref/general/#data-persistence-jpa.html

If this needs further work just let me know. Thanks!

frowe commented 4 years ago

@dmuelle Sorry, I got sidetracked and didn't respond to your question above.

If I understand correctly- if you are using the jpa feature, you have the option not to use the default because jpaContainer is automatically enabled. (If you enable the jpa-2.x feature, you do not have any option about the jpa provider, you will get the one provided by Liberty (EclipseLink or Hibernate depending on the feature version).) But if you know you don't want to use the default anyway, you can install jpaContainer instead of jpa (not so much 'can' as 'must' use jpaContainer in this case) since the only real difference between them is that jpaContainer doesn't include a default implementation. Is that accurate?

This paragrpah seems to use the expanded acronym a lot making it harder to read, at least for me.

JPA for Open Liberty is supported by the Java Persistence API feature, version 2.1 and later, and the Java Persistence API Container feature, version 2.1 and later. The Java Persistence API feature includes Java Persistence API specification interfaces and container-managed JPA integration. EclipseLink is included as the default JPA provider implementation. If you want to use different a provider implementation, such as Hibernate, enable the Java Persistence API Container feature. The Java Persistence API Container feature provides the same capabilities as the Java Persistence API feature but does not include a default provider implementation.

Could something like this work instead since the acronym is expanded in previous sections on first use? JPA for Open Liberty is supported by the JPA feature, version 2.1 and later, and the JPA Container feature, version 2.1 and later. The JPA feature includes specification interfaces, container-managed integration and EclipseLink as the default JPA provider implementation. If you want to use different a provider implementation, such as Hibernate, enable the JPA Container feature. The JPA Container feature provides the same capabilities as the JPA feature but does not include a default provider implementation.

I'm reviewing the example snippet and comments.

dmuelle commented 4 years ago

Thanks @frowe - I've updated this section per your suggestion. It does improve readability.

frowe commented 4 years ago

@dmuelle Edits look good. I'm still getting to the review/comments about code snippet.

dmuelle commented 4 years ago

Hi @frowe - just circling back to make sure this topic is ready to publish from a technical perspective. If so, can you add the technical reviewed label to this issue? It will not actually publish until we have also completed the feature config topic for JPA Container.

frowe commented 4 years ago

done.

lauracowen commented 4 years ago

Looks good. Thanks. Signing off.

Charlotte-Holt commented 4 years ago

@dmuelle This topic looks great!

Peer review feedback

Do we want to have (JPA) the abbreviation in the title? Not sure, but I think we may've talked about not doing that?

What is JPA?

I think there's a space between JPA and the ? in the heading

JPA and JDBC

You probably know this, but just need a link where it says link pending. Or could comment out that line for the time being if we're waiting on something to be written.

JPA configuration with Open Liberty

Extra the in If you enable the JPA feature, you do not need to enable the the JPA Container feature.

OpenLiberty / docs

Persistence with JPA #1291

Peer review feedback

What is JPA?

JPA and JDBC

JPA configuration with Open Liberty

See also