> Has anyone else seen framework documentation that they think works better?
An obvious example is Spring and Spring Boot. They went so far that they even created Spring Boot as a framework on top of the legacy Spring framework to hide some complexities. Spring Boot has its own documentation
that overlaps with Spring documentation but focuses only on frequently used APIs:
https://docs.spring.io/spring-boot/docs/current-SNAPSHOT/reference/htmlsingle/
I believe that if we want a complete reference, we should have a separate reference guide for each profile. So we need a separate guide for Web Profile. If we have more profiles in the future, they should have their own
guide each. That means the documentation should be as modular as the platform itself.
Cheers,
Ondrej Mihályi
Senior Payara Service Engineer
Payara Server – Robust. Reliable. Supported.
E:
ondrej.mihalyi@xxxxxxxxxxx | T: +1 415 523 0175 | M: +421 902 079 891
----------------------------------------------------------------------------------------------------------------------
Payara Services Limited, Registered office:
Unit
11, Malvern Hills Science Park,
Geraldine Road,
Malvern,
WR14 3SZ
Registered in England and Wales: 09998946 |
www.payara.fish |
info@xxxxxxxxxxx | @Payara_Fish
From: jakarta.ee-community-bounces@xxxxxxxxxxx <jakarta.ee-community-bounces@xxxxxxxxxxx> on behalf of reza_rahman <reza_rahman@xxxxxxxxx>
Sent: 02 May 2018 14:41:54
To: Jakarta EE community discussions
Subject: Re: [jakarta.ee-community] Why not dropping EARs in Jakarta EE?
This is something I have gone back and forth on over the years. My current thinking is that a comprehensive reference is still needed, but just one that is a bit more modular. In addition, what you need is getting started resources on specific common use
cases.
Has anyone else seen framework documentation that they think works better?
Sent via the Samsung Galaxy S7, an AT&T 4G LTE smartphone
-------- Original message --------
From: Ondrej Mihályi <ondrej.mihalyi@xxxxxxxxxxx>
Date: 5/2/18 2:38 AM (GMT-05:00)
To: Jakarta EE community discussions <jakarta.ee-community@xxxxxxxxxxx>, edivargas@xxxxxxxxx
Subject: Re: [jakarta.ee-community] Why not dropping EARs in Jakarta EE?
We need to clean up the API for sure, to separate preferred and frequently used APIs from other APIs. Some less used APIs make sense to be pruned (made optional) to make life easier for implementers. Other less used
APIs should stay but be made less visible for newcomers.
Especially for newcomers, it's very hard to get started and avoid using older and less preferred technologies. There are many obsolete tutorials and docs that are still widely used. We should definitely update the documentation
to cover the most important APIs first and put those less important parts to advanced tutorials. Otherwise, newcomers are confused.
The current
Java EE 8 tutorial is a perfect example of how not to present things to newcomers. It's a complete reference, with XML and SOAP mentioned prominently in the overview section, all Java EE APIs listed together in the same list without any context,
packaging section talks about EJBs, EJB JARs, etc. Newcomers expect to learn the most important subset first and then add on top of it.
Cheers,
Ondrej Mihályi
Senior Payara Service Engineer
Payara Server – Robust. Reliable. Supported.
E:
ondrej.mihalyi@xxxxxxxxxxx | T: +1 415 523 0175 | M: +421 902 079 891
----------------------------------------------------------------------------------------------------------------------
Payara Services Limited, Registered office:
Unit
11, Malvern Hills Science Park,
Geraldine Road,
Malvern,
WR14 3SZ
Registered in England and Wales: 09998946 |
www.payara.fish |
info@xxxxxxxxxxx | @Payara_Fish
From: jakarta.ee-community-bounces@xxxxxxxxxxx <jakarta.ee-community-bounces@xxxxxxxxxxx> on behalf of Jorge Vargas Garcia - Edivargas <edivargas@xxxxxxxxx>
Sent: 01 May 2018 15:12:02
To: Jakarta EE community discussions
Subject: Re: [jakarta.ee-community] Why not dropping EARs in Jakarta EE?
Aditionally to technical issues about deprecating technologies. Remember most of programmers are there trying to understand and use JakartaEE frameworks and API, they don't have a hapoy path to do it.
We cant' change names and deprecated them every n months. We need (like someone says) stabilized JakartaEE platformn.
BR
We've discussed the EJB issue before so don't really want to beat a dead horse too much again (you'll forgive the pun). I think the consensus was that we need to get it done and it was mostly a question of who was going to do the work.
It has long been my opinion that we should have replaced EJB in Java EE 7 and deprecated it in Java EE 8. It's water under the bridge now, but not doing this has hurt due Java EE adoption in a way I have repeatedly seen first hand. I do hope we can focus
on putting this problem finally behind us quickly in Jakarta EE. The problem with EJB is both technical and marketing oriented.
Sent via the Samsung Galaxy S7, an AT&T 4G LTE smartphone
-------- Original message --------
Date: 5/1/18 7:36 AM (GMT-05:00)
Subject: Re: [jakarta.ee-community] Why not dropping EARs in Jakarta EE?
Hi,
EJB was just an example, as could be JSP. EJB has indeed a lot of unique features like you said (as has SOAP over REST). I don't think there is much interest in developing the EJB spec further, which makes the API a candidate for the "stable spec". Most people
I've talked to would like to see its good features available as CDI extensions. Apparently Oracle didn't have much interest on that lately, but the Concurrency Utilities project is now led by Steve Millidge (Payara) [1] and EJB and JMS will be led by David
Blevins (TomiTribe) [2].
That makes me hope we'll be able to move the required features soon. As shown by Arjan, most is already achievable right now with the existing APIs.
Even then, we might not want to *deprecate* EJBs, but new users should be encouraged to use CDI, where the effort will be centered.
We can replace the "deprecated" or "stable" term with "not-so-cool-right-now". My emphasis is that we need a way to move users forward without forgetting existing investings.
Deprecating a spec might not be the right way to achieve it. In fact, to my knowledge, the JCP didn't deprecate specs, but it was Java EE which decided that *in its context*, a spec was deprecated or proposed optional. Here I see each committee will have
a different role:
- The technical/steering committee decides that some specific technology is not worth putting much effort into, as it is already well stablished and needs no further development.
- Based on that, the technical/steering committee decides that, in the context of Jakarta EE, that spec isn't on the "bleeding edge" right now, tags it at "stable", and removes them from the proposed "Bleeding Edge Profile", that would be there just for
people who want the latest thing.
- The spec committee won't usually update the spec, not because the project is dead, but because the project is already stable and little updates would be needed. The technology is not deprecated, so one can expect some update eventually if there's enough
interest. The spec itself wouldn't be deprecated nor tagged stable. That just exists in the context of Jakarta EE distributions.
SOAP is still *widely* used. We don't see articles on how cool it is, but most of us still have to deal with it in one way or another. People in need for it could just add the implementation dependency, configure the server to provide the module (if the runtime
supports that kind of modularity), or just use the Full Profile as we've been all doing until now.
Nobody complains the Web Profile doesn't contain JAX-WS or remote EJBs, because that profile it's specifically dedicated to web developments. My opinion is that we need a way to separate what most modern developments need, without implying that a specific technology
is dead and should not be used anymore. Until now we only had the deprecation process, but that doesn't fit all cases.
Hope my opinion is clearer now.
@Guillermo, how can you qualify EJB 3 as deprecated if we don't have any standard alternatives for scheduling, concurrency, pooling, security...
@all, I work in industry where all our integration partners use SOAP :-/ and I think I am not alone.
_______________________________________________
jakarta.ee-community mailing list
jakarta.ee-community@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe from this list, visit
https://dev.eclipse.org/mailman/listinfo/jakarta.ee-community
--
Regards,
Guillermo González de Agüero
_______________________________________________
jakarta.ee-community mailing list
jakarta.ee-community@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe from this list, visit
https://dev.eclipse.org/mailman/listinfo/jakarta.ee-community
|