blob: 90472b2f3f55c0db325d282ac5b682b156b0ee19 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 1.5.6.1">
<title>EE4J Projects - Technical Direction</title>
<style>
</style>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.6.3/css/font-awesome.min.css">
</head>
<body class="article toc2 toc-left">
<div id="header">
<h1>EE4J Projects - Technical Direction</h1>
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel1">
<li><a href="#introduction">Introduction</a></li>
<li><a href="#technical-direction-guiding-principles">Technical Direction - Guiding Principles</a>
<ul class="sectlevel2">
<li><a href="#open-for-innovation">Open for Innovation</a></li>
<li><a href="#split-stand-alone-jakarta-ee-tck-into-individual-projects">Split stand-alone Jakarta EE TCK into individual projects</a></li>
<li><a href="#embrace-jpms">Embrace JPMS</a></li>
<li><a href="#standardise-on-the-maven-build-system">Standardise on the Maven build system</a></li>
<li><a href="#deprecate-old-technologies-and-provide-optional-modules">Deprecate old technologies and provide optional modules</a></li>
<li><a href="#prefer-soft-dependencies">Prefer soft dependencies</a></li>
<li><a href="#integration-with-cdi-and-config">Integration with CDI and Config</a></li>
<li><a href="#release-cadence">Release Cadence</a></li>
<li><a href="#focus-on-testing">Focus on testing</a></li>
<li><a href="#standard-formatting-of-specification-and-documentation">Standard formatting of Specification and Documentation</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>Date: 2018-06-08</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="introduction"><a class="anchor" href="#introduction"></a><a class="link" href="#introduction">Introduction</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>Jakarta EE<sup class="footnote">[<a id="_footnoteref_1" class="footnote" href="#_footnote_1" title="View footnote.">1</a>]</sup> is the future of cloud-native Java.
Jakarta EE’s mission is to provide frequent releases, lower barriers to participation,
and to put the community back into what was formerly the Java EE platform.</p>
</div>
<div class="paragraph">
<p>Eclipse EE4J<sup class="footnote">[<a id="_footnoteref_2" class="footnote" href="#_footnote_2" title="View footnote.">2</a>]</sup> PMC has released this following technical direction document which all EE4J projects should consider when
driving innovations in Jakarta EE.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="technical-direction-guiding-principles"><a class="anchor" href="#technical-direction-guiding-principles"></a><a class="link" href="#technical-direction-guiding-principles">Technical Direction - Guiding Principles</a></h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="open-for-innovation"><a class="anchor" href="#open-for-innovation"></a><a class="link" href="#open-for-innovation">Open for Innovation</a></h3>
<div class="paragraph">
<p>As Jakarta EE evolves we expect innovation from a range of open source communities to be quickly adopted into new versions
of the platform to help developers create portable cloud-native applications.
We also expect that the rapid innovation occurring in other areas of cloud native development (e.g. Kubernetes, Istio, etc.)
as well as in other development languages, will be reflected within Jakarta EE evolution.</p>
</div>
<div class="paragraph">
<p>We encourage projects which are implementing Jakarta EE-related APIs to join the EE4J top-level project.
We would like to encourage Jakarta EE-related innovation, regardless if it’s in Eclipse, Apache, or somewhere else.
And, when these innovations have solidified and matured, we would like to see these projects become more integrated with Jakarta EE
and become part of the platform.</p>
</div>
</div>
<div class="sect2">
<h3 id="split-stand-alone-jakarta-ee-tck-into-individual-projects"><a class="anchor" href="#split-stand-alone-jakarta-ee-tck-into-individual-projects"></a><a class="link" href="#split-stand-alone-jakarta-ee-tck-into-individual-projects">Split stand-alone Jakarta EE TCK into individual projects</a></h3>
<div class="paragraph">
<p>Each API project should have a corresponding TCK test repository project.
This technical direction is near the top of the list because this effort is not trivial!
All projects have to use the same standard mechanism for TCK.
We don’t want to face a situation where different projects use different frameworks and it is a challenge to run TCK tests
for each of them. It will require some PMC guidance and community input about how new TCK tests are organized,
what testing frameworks are used, etc.</p>
</div>
</div>
<div class="sect2">
<h3 id="embrace-jpms"><a class="anchor" href="#embrace-jpms"></a><a class="link" href="#embrace-jpms">Embrace JPMS</a></h3>
<div class="paragraph">
<p>Despite the fact that the first release of Jakarta EE will be JDK8 based, projects should start preparation for the module system, i.e.
JDK9+ support. First step would be adding automatic-module-name in MANIFEST.MF.
Then if it is possible to provide a correct module-info.java.
If not, it can wait for the next project release. The global definition and usage of modules needs to be defined at the Platform level (PMC),
again with community input, and then adhered to by the various EE4J component projects.</p>
</div>
</div>
<div class="sect2">
<h3 id="standardise-on-the-maven-build-system"><a class="anchor" href="#standardise-on-the-maven-build-system"></a><a class="link" href="#standardise-on-the-maven-build-system">Standardise on the Maven build system</a></h3>
<div class="paragraph">
<p>Apache Maven is a de facto standard build system for Java projects.
There are currently some older EE4J projects that use Ant which should be mavenized.
Also, projects should use default Maven directory structures and build processes.
The project builds should produce standard Maven artifacts (sources.jar, binaries.jar, javadoc.jar) and be as simple to execute as
running mvn clean install without providing complicated properties.
Projects should use recommended versions of Maven and plugins as defined in EE4J parent pom.</p>
</div>
</div>
<div class="sect2">
<h3 id="deprecate-old-technologies-and-provide-optional-modules"><a class="anchor" href="#deprecate-old-technologies-and-provide-optional-modules"></a><a class="link" href="#deprecate-old-technologies-and-provide-optional-modules">Deprecate old technologies and provide optional modules</a></h3>
<div class="paragraph">
<p>Requiring all components to preserve backwards compatibility increases the maintenance burden in both size and complexity.
We should extract old and rarely used technologies to optional modules and leave it up to users if they want to use them.
Backwards compatibility has always been a strength for Java EE for many adopters, but at the same time a weakness for others,
particularly as it often appears to throttle the pace of innovation.
We need a way to ensure that those who require backwards compatibility (often for years) can rely upon it,
whilst others can move forward with quicker releases without requiring compatibility with previous versions of Jakarta EE.</p>
</div>
</div>
<div class="sect2">
<h3 id="prefer-soft-dependencies"><a class="anchor" href="#prefer-soft-dependencies"></a><a class="link" href="#prefer-soft-dependencies">Prefer soft dependencies</a></h3>
<div class="paragraph">
<p>Think carefully before adding hard dependencies.
Components depending on half of the world are heavy and not suitable for microservices development.
Use a modular approach that allows users to include only functionality that&#8217;s needed in their application,
while maintaining platform consistency.</p>
</div>
</div>
<div class="sect2">
<h3 id="integration-with-cdi-and-config"><a class="anchor" href="#integration-with-cdi-and-config"></a><a class="link" href="#integration-with-cdi-and-config">Integration with CDI and Config</a></h3>
<div class="paragraph">
<p>Dependency injection and configuration should be included in all projects.
It will provide consistency between all Jakarta EE components if they are configured the same way.</p>
</div>
</div>
<div class="sect2">
<h3 id="release-cadence"><a class="anchor" href="#release-cadence"></a><a class="link" href="#release-cadence">Release Cadence</a></h3>
<div class="paragraph">
<p>We are recommending one year cadence for the Jakarta EE platform.
For components the recommendation is 3+1 yearly cadence,
where one major release is synchronized with the Platform release and 3 quarterly minor releases.</p>
</div>
<div class="paragraph">
<p>E.g. Something like (please do <strong>NOT</strong> take this example as an actual roadmap)</p>
</div>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 20%;">
<col style="width: 20%;">
<col style="width: 20%;">
<col style="width: 20%;">
<col style="width: 20%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">2019 Q1</th>
<th class="tableblock halign-left valign-top">2019 Q2</th>
<th class="tableblock halign-left valign-top">2019 Q3</th>
<th class="tableblock halign-left valign-top">2019 Q4</th>
<th class="tableblock halign-left valign-top">2020 Q1</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Jakarta EE 8.0</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">&#8230;&#8203;</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">&#8230;&#8203;</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">&#8230;&#8203;</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Jakarta EE 9.0</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">CompX 3.0</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">CompX 3.1</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">CompX 3.2</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">CompX 4.0</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">CompX 4.1</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">&#8230;&#8203;</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">&#8230;&#8203;</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">&#8230;&#8203;</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">&#8230;&#8203;</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">&#8230;&#8203;</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect2">
<h3 id="focus-on-testing"><a class="anchor" href="#focus-on-testing"></a><a class="link" href="#focus-on-testing">Focus on testing</a></h3>
<div class="paragraph">
<p>The PMC regards tests to be a very important part of every project.
Specifications and APIs should be designed the way that applications using them can be easily tested.</p>
</div>
</div>
<div class="sect2">
<h3 id="standard-formatting-of-specification-and-documentation"><a class="anchor" href="#standard-formatting-of-specification-and-documentation"></a><a class="link" href="#standard-formatting-of-specification-and-documentation">Standard formatting of Specification and Documentation</a></h3>
<div class="paragraph">
<p>Documentation and specs should be created using standard format and tooling.
The Maven tooling (see above) should render this as part of the build and resulting documentation in pdf / html format.
These artifacts should be part of the release.</p>
</div>
</div>
</div>
</div>
</div>
<div id="footnotes">
<hr>
<div class="footnote" id="_footnote_1">
<a href="#_footnoteref_1">1</a>. Jakarta EE is the brand for the platform and specifications developed at the Eclipse Foundation as Eclipse Enterprise For Java (EE4J).
</div>
<div class="footnote" id="_footnote_2">
<a href="#_footnoteref_2">2</a>. See Footnote 1.
</div>
</div>
</body>
</html>