Jump to: navigation, search

Difference between revisions of "EclipseLink/Development/Documentation/2.4"

m (fixed where truncated)
Line 1: Line 1:
<div class="WordSection1">
+
<div class=WordSection1>
= Documentation Plan for EclipseLink 2.4  =
+
  
== Change Record  ==
+
<p class=MsoTitle>Documentation Plan for EclipseLink 2.4</p>
  
{| cellspacing="0" cellpadding="0" border="1" style="border-collapse:collapse;border:none" class="MsoNormalTable"
+
<h1>Change Record</h1>
|-
+
| width="213" valign="top" style="width:159.6pt;border:solid windowtext 1.0pt; padding:0in 5.4pt 0in 5.4pt" |
+
'''<span>Date</span>'''
+
  
| width="213" valign="top" style="width:159.6pt;border:solid windowtext 1.0pt; border-left:none;padding:0in 5.4pt 0in 5.4pt" |
+
<table class=MsoNormalTable border=1 cellspacing=0 cellpadding=0
'''<span>Author</span>'''  
+
style='border-collapse:collapse;border:none'>
 +
<tr>
 +
  <td width=213 valign=top style='width:159.6pt;border:solid windowtext 1.0pt;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><strong><span style='font-family:"Calibri","sans-serif"'>Date
 +
  </span></strong></p>
 +
  </td>
 +
  <td width=213 valign=top style='width:159.6pt;border:solid windowtext 1.0pt;
 +
  border-left:none;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><strong><span style='font-family:"Calibri","sans-serif"'>Author</span></strong></p>
 +
  </td>
 +
  <td width=213 valign=top style='width:159.6pt;border:solid windowtext 1.0pt;
 +
  border-left:none;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><strong><span style='font-family:"Calibri","sans-serif"'>Change
 +
  Record</span></strong></p>
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td width=213 valign=top style='width:159.6pt;border:solid windowtext 1.0pt;
 +
  border-top:none;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>7/28/11</p>
 +
  </td>
 +
  <td width=213 valign=top style='width:159.6pt;border-top:none;border-left:
 +
  none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Ben Gelernter</p>
 +
  </td>
 +
  <td width=213 valign=top style='width:159.6pt;border-top:none;border-left:
 +
  none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>First draft</p>
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td width=213 valign=top style='width:159.6pt;border:solid windowtext 1.0pt;
 +
  border-top:none;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>8/11/11</p>
 +
  </td>
 +
  <td width=213 valign=top style='width:159.6pt;border-top:none;border-left:
 +
  none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Ben Gelernter</p>
 +
  </td>
 +
  <td width=213 valign=top style='width:159.6pt;border-top:none;border-left:
 +
  none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Incorporated changes from doc manager  review.</p>
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td width=213 valign=top style='width:159.6pt;border:solid windowtext 1.0pt;
 +
  border-top:none;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>8/17/11</p>
 +
  </td>
 +
  <td width=213 valign=top style='width:159.6pt;border-top:none;border-left:
 +
  none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Ben Gelernter</p>
 +
  </td>
 +
  <td width=213 valign=top style='width:159.6pt;border-top:none;border-left:
 +
  none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Incorporated changes from doc team review</p>
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td width=213 valign=top style='width:159.6pt;border:solid windowtext 1.0pt;
 +
  border-top:none;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>9/15/11</p>
 +
  </td>
 +
  <td width=213 valign=top style='width:159.6pt;border-top:none;border-left:
 +
  none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Ben Gelernter</p>
 +
  </td>
 +
  <td width=213 valign=top style='width:159.6pt;border-top:none;border-left:
 +
  none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Incorporated changes from Dev/QA/PM  review</p>
 +
  </td>
 +
</tr>
 +
</table>
  
| width="213" valign="top" style="width:159.6pt;border:solid windowtext 1.0pt; border-left:none;padding:0in 5.4pt 0in 5.4pt" |
+
<p class=MsoNormal>&nbsp;</p>
'''<span>Change</span>'''
+
  
|-
+
<p class=MsoNormal>This documentation plan describes how the documentation team
| width="213" valign="top" style="width:159.6pt;border:solid windowtext 1.0pt; border-top:none;padding:0in 5.4pt 0in 5.4pt" |
+
will provide EclipseLink documentation for the EclipseLink; (EL) 2.4 release.</p>
7/28/11
+
  
| width="213" valign="top" style="width:159.6pt;border-top:none;border-left: none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt; padding:0in 5.4pt 0in 5.4pt" |
+
<h1>Schedule</h1>
Ben Gelernter
+
  
| width="213" valign="top" style="width:159.6pt;border-top:none;border-left: none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt; padding:0in 5.4pt 0in 5.4pt" |
+
<table class=MsoNormalTable border=1 cellspacing=0 cellpadding=0
First draft
+
style='border-collapse:collapse;border:none'>
 +
<tr>
 +
  <td width=319 valign=top style='width:239.4pt;border:solid windowtext 1.0pt;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><b>Milestone</b></p>
 +
  </td>
 +
  <td width=319 valign=top style='width:239.4pt;border:solid windowtext 1.0pt;
 +
  border-left:none;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><b>Date</b></p>
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td width=319 valign=top style='width:239.4pt;border:solid windowtext 1.0pt;
 +
  border-top:none;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Doc plan first draft</p>
 +
  </td>
 +
  <td width=319 valign=top style='width:239.4pt;border-top:none;border-left:
 +
  none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>8/10/11</p>
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td width=319 valign=top style='width:239.4pt;border:solid windowtext 1.0pt;
 +
  border-top:none;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Doc plan posted</p>
 +
  </td>
 +
  <td width=319 valign=top style='width:239.4pt;border-top:none;border-left:
 +
  none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>8/17/11 </p>
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td width=319 valign=top style='width:239.4pt;border:solid windowtext 1.0pt;
 +
  border-top:none;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Doc plan comments due</p>
 +
  </td>
 +
  <td width=319 valign=top style='width:239.4pt;border-top:none;border-left:
 +
  none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>8/24/11</p>
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td width=319 valign=top style='width:239.4pt;border:solid windowtext 1.0pt;
 +
  border-top:none;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Final doc plan </p>
 +
  </td>
 +
  <td width=319 valign=top style='width:239.4pt;border-top:none;border-left:
 +
  none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>8/29/11</p>
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td width=319 valign=top style='width:239.4pt;border:solid windowtext 1.0pt;
 +
  border-top:none;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>EclipseLink release 2.4</p>
 +
  </td>
 +
  <td width=319 valign=top style='width:239.4pt;border-top:none;border-left:
 +
  none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><span class=ornotepadcommenttext>2.4.1 Juno: 2012-06-27 </span><br>
 +
  <span class=ornotepadcommenttext>2.4.0: 2012-03-28</span></p>
 +
  <p class=MsoNormal><span class=ornotepadcommenttext>(See: <a
 +
  href="http://www.eclipse.org/projects/project_summary.php?projectid=rt.eclipselink"
 +
  target="_blank">http://www.eclipse.org/projects/project_summary.php?projectid=rt.eclipselink</a>
 +
  for any changes to these dates.)</span></p>
 +
  </td>
 +
</tr>
 +
</table>
  
|-
+
<p class=MsoNormal>&nbsp;</p>
| width="213" valign="top" style="width:159.6pt;border:solid windowtext 1.0pt; border-top:none;padding:0in 5.4pt 0in 5.4pt" |
+
8/11/11
+
  
| width="213" valign="top" style="width:159.6pt;border-top:none;border-left: none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt; padding:0in 5.4pt 0in 5.4pt" |
+
<h1>Audience</h1>
Ben Gelernter
+
  
| width="213" valign="top" style="width:159.6pt;border-top:none;border-left: none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt; padding:0in 5.4pt 0in 5.4pt" |
+
<table class=MsoNormalTable border=1 cellspacing=0 cellpadding=0
Incorporated changes from doc manager review.  
+
style='border-collapse:collapse;border:none'>
 +
<tr>
 +
  <td width=187 valign=top style='width:1.95in;border:solid windowtext 1.0pt;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><b>User</b></p>
 +
  </td>
 +
  <td width=451 valign=top style='width:4.7in;border:solid windowtext 1.0pt;
 +
  border-left:none;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><b>Description</b></p>
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td width=187 valign=top style='width:1.95in;border:solid windowtext 1.0pt;
 +
  border-top:none;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Application Developers</p>
 +
  </td>
 +
  <td width=451 valign=top style='width:4.7in;border-top:none;border-left:none;
 +
  border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Developers who want to develop applications using any of
 +
  the following technologies for persistence services:</p>
 +
  <uy.php?projectid=rt.eclipselink"
 +
  target="_blank">http://www.eclipse.org/projects/project_summary.php?projectid=rt.eclipselink</a>
 +
  for any changes to these dates.)</span></p>
 +
  </td>
 +
</tr>
 +
</table>
  
|-
+
<p class=MsoNormal>&nbsp;</p>
| width="213" valign="top" style="width:159.6pt;border:solid windowtext 1.0pt; border-top:none;padding:0in 5.4pt 0in 5.4pt" |
+
8/17/11
+
  
| width="213" valign="top" style="width:159.6pt;border-top:none;border-left: none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt; padding:0in 5.4pt 0in 5.4pt" |
+
<h1>Audience</h1>
Ben Gelernter
+
  
| width="213" valign="top" style="width:159.6pt;border-top:none;border-left: none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt; padding:0in 5.4pt 0in 5.4pt" |
+
<table class=MsoNormalTable border=1 cellspacing=0 cellpadding=0
Incorporated changes from doc team review
+
style='border-collapse:collapse;border:none'>
 +
<tr>
 +
  <td width=187 valign=top style='width:1.95in;border:solid windowtext 1.0pt;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><b>User</b></p>
 +
  </td>
 +
  <td width=451 valign=top style='width:4.7in;border:solid windowtext 1.0pt;
 +
  border-left:none;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><b>Description</b></p>
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td width=187 valign=top style='width:1.95in;border:solid windowtext 1.0pt;
 +
  border-top:none;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Application Developers</p>
 +
  </td>
 +
  <td width=451 valign=top style='width:4.7in;border-top:none;border-left:none;
 +
  border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Developers who want to develop applications using any of
 +
  the following technologies for persistence services:</p>
 +
  <ul style='margin-top:0in' type=disc>
 +
  <li class=MsoNormal>Java Persistence Architecture (JPA) 2.x plus the
 +
      EclipseLink JPA extensions</li>
 +
  <li class=MsoNormal>Java Architecture for XML Binding 2.x (JAXB) plus the
 +
      EclipseLink MOXy extensions.</li>
 +
  <li class=MsoNormal>Java API for XML Web Services 2.x (JAX-WS) plus EclipseLink
 +
      Database Web Services (DBWS) features. </li>
 +
  </ul>
 +
  <p class=MsoNormal>Developers should be familiar with the concepts and
 +
  programming practices of the version of Java SE and Java EE supported by
 +
  their deployment platform.</p>
 +
  <p class=MsoNormal><b>Assumed knowledge:</b></p>
 +
  <ul style='margin-top:0in' type=disc>
 +
  <li class=MsoNormal>Developers using EclipseLink JPA should be familiar with
 +
      the concepts and programming practices of JPA 2.x.</li>
 +
  <li class=MsoNormal>Developers using EclipseLink MOXy should be familiar
 +
      with the concepts and programming practices of JAXB 2.x.</li>
 +
  <li class=MsoNormal>Developers using EclipseLink DBWS should be familiar
 +
      with the concepts and programming practices of JAX-WS 2.x.</li>
 +
  </ul>
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td width=187 valign=top style='width:1.95in;border:solid windowtext 1.0pt;
 +
  border-top:none;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Administrator/Deployer</p>
 +
  </td>
 +
  <td width=451 valign=top style='width:4.7in;border-top:none;border-left:none;
 +
  border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Users who want to deploy and manage applications using the
 +
  EclipseLink persistence technologies.<b><i> </i></b></p>
 +
  <p class=MsoNormal><b>Assumed knowledge:</b></p>
 +
  <p class=MsoNormal>These users should be familiar with basic operations of
 +
  the chosen application server.</p>
 +
  </td>
 +
</tr>
 +
</table>
  
|}
+
<p class=MsoNormal>&nbsp;</p>
  
&nbsp;
+
<h1>Planned Documentation Deliverables</h1>
  
This documentation plan describes how the documentation team will provide EclipseLink documentation for the EclipseLink; (EL) 2.4 release.
+
<p class=MsoNormal>The Documentation team will document EclipseLink-specific
 +
features for:</p>
  
== Schedule ==
+
<ul style='margin-top:0in' type=disc>
 +
  <li class=MsoNormal>JPA </li>
 +
<li class=MsoNormal>MOXy</li>
 +
<li class=MsoNormal>DBWS</li>
 +
</ul>
  
{| cellspacing="0" cellpadding="0" border="1" style="border-collapse:collapse;border:none" class="MsoNormalTable"
+
<p class=MsoNormal><b>Note:</b> JPA is the most commonly used and the biggest,
|-
+
therefore more resources will be devoted to JPA than the other services. </p>
| width="319" valign="top" style="width:239.4pt;border:solid windowtext 1.0pt; padding:0in 5.4pt 0in 5.4pt" |
+
'''Milestone'''
+
  
| width="319" valign="top" style="width:239.4pt;border:solid windowtext 1.0pt; border-left:none;padding:0in 5.4pt 0in 5.4pt" |
+
<p class=MsoNormal>The Documentation team will not document EIS, SDO, <span
'''Date'''
+
class=ornotepadcommenttext>or any other &quot;native&quot; TopLink
 +
functionality (i.e., non-JPA such as ORM, OX, etc.)</span>..</p>
  
|-
+
<h2>Documentation Design</h2>
| width="319" valign="top" style="width:239.4pt;border:solid windowtext 1.0pt; border-top:none;padding:0in 5.4pt 0in 5.4pt" |
+
Doc plan first draft
+
  
| width="319" valign="top" style="width:239.4pt;border-top:none;border-left: none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt; padding:0in 5.4pt 0in 5.4pt" |
+
<p class=MsoNormal>The wiki topics will be handled as follows:</p>
8/10/11
+
  
|-
+
<ul style='margin-top:0in' type=disc>
| width="319" valign="top" style="width:239.4pt;border:solid windowtext 1.0pt; border-top:none;padding:0in 5.4pt 0in 5.4pt" |
+
<li class=MsoNormal>All EclipseLink documentation will be maintained under the
Doc plan posted
+
    <i>Documentation Center</i> on the EclipseLink wiki at <a
 +
    href="http://wiki.eclipse.org/EclipseLink/UserGuide">http://wiki.eclipse.org/EclipseLink/UserGuide</a>.
 +
    </li>
 +
<li class=MsoNormal>Versioning will be handled as follows:</li>
 +
<ul style='margin-top:0in' type=circle>
 +
  <li class=MsoNormal>A note &quot;New in EL 2.<i>n</i>&quot; will be placed
 +
      next to new topics in the TOCs, where <i>n</i> refers to the release when
 +
      the feature was introduced. This is currently handled using template <span
 +
      style='font-family:"Courier New"'>{{EclipseLink/NewIn2<i>n</i>}}</span>.</li>
 +
  <li class=MsoNormal>A note  &quot; New in version 2.<i>n</i>.&quot; will be
 +
      added at the beginning of a topic documenting a new feature.  This is
 +
      currently handled using <span style='font-family:"Courier New"'>{{EclipseLink_NewIn|version=2.n}}.</span></li>
 +
  <li class=MsoNormal>If a new feature is handled in an existing topic and the
 +
      topic changes more than 50%, the note &quot; New in version 2.<i>n</i>.&quot;
 +
      will be placed at the beginning of the topic or at the beginning of the appropriate
 +
      section. </li>
 +
  <li class=MsoNormal>Header and footers on the wiki page will contain no
 +
      references to release numbers. </li>
 +
  <li class=MsoNormal>If a feature is deprecated, a note will placed next to
 +
      the documentation for the feature.</li>
 +
</ul>
 +
<li class=MsoNormal>Each topic will document one &quot;feature.&quot; The term
 +
    &quot;feature&quot; here is somewhat loose. In some cases, it is a single
 +
    annotation. In some cases, the topic will document how to use multiple
 +
    annotations together for a specific purpose, e.g., single-table
 +
    multi=tenancy.</li>
 +
<li class=MsoNormal>These topics are more-or-less &quot;reference&quot;
 +
    topics. That is, they document the primary APIs and XML used to implement
 +
    the feature. There can be limited discussion about how to use the code to
 +
    achieve the purpose of the feature, but we will not attempt to put the
 +
    feature in a larger context or to fully document all related features<span
 +
    style='color:red'>. </span></li>
 +
<li class=MsoNormal>The JPA topics will primarily focus on using annotations,
 +
    when they are available. For example, a topic may begin with something
 +
    like, &quot;Use the @Xyz annotation to…&quot; and most or all examples and
 +
    code snippets will show annotations. When the feature can also be coded
 +
    using XML, the topic can discuss the XML (including a reference to the
 +
    schema), but the documentation for XML will not be as extensive as the
 +
    documentation for the annotation.</li>
 +
<li class=MsoNormal>Every topic will cross-reference:</li>
 +
<ul style='margin-top:0in' type=circle>
 +
  <li class=MsoNormal> Any associated example provided by Development and
 +
      located in the Samples section of the wiki.</li>
 +
  <li class=MsoNormal>Any associated Javadoc. When an annotation is available,
 +
      the reference will be to the annotation(s), not the &quot;native
 +
      API.&quot;</li>
 +
</ul>
 +
<li class=MsoNormal>The Documentation team will not document features that are
 +
    not EclipseLink-specific. In particular, features that are documented in
 +
    the specification for the underlying technology. For example features
 +
    documented in the <i>JSR-000317 JavaTM Persistence 2.0</i> specification
 +
    will not be documented.  However, anyone with permission to edit the wiki
 +
    may add topics to the wiki. As time permits, the Documentation team may
 +
    provide advice on the organization of topics. Any non-Documentation person
 +
    adding topics is responsible for adding and maintaining the following:</li>
 +
<ul style='margin-top:0in' type=circle>
 +
  <li class=MsoNormal>Previous and Next browse sequence links at the bottom of
 +
      the page </li>
 +
  <li class=MsoNormal>Links from the Table of Contents</li>
 +
  <li class=MsoNormal>Links from the parent, or container, topic, if there is
 +
      one. For example, the JPA documentation includes a &quot;Weaving
 +
      Topic&quot; which introduces several weaving-related topics under it. </li>
 +
</ul>
 +
</ul>
  
| width="319" valign="top" style="width:239.4pt;border-top:none;border-left: none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt; padding:0in 5.4pt 0in 5.4pt" |
+
<p class=MsoNormal style='margin-left:1.0in'>Note: A container topic should not
8/17/11
+
contain only a list of links. Every topic must include at least an overview
 +
sentence. For example:  &quot;The EclipseLink cache is an in-memory repository
 +
that stores recently read or written objects based on class and primary key
 +
values. Caching is discussed in the following topics:&quot;</p>
  
|-
+
<ul style='margin-top:0in' type=disc>
| width="319" valign="top" style="width:239.4pt;border:solid windowtext 1.0pt; border-top:none;padding:0in 5.4pt 0in 5.4pt" |
+
<li class=MsoNormal>Individual topics will not include cross references to the
Doc plan comments due
+
    standard specifications (JPA, JAXB). There will be one overview topic (or
 +
    an overview topic for each service) that will contain the link to the
 +
    appropriate specification.</li>
 +
<li class=MsoNormal>If design documents (specs) are not available or do not
 +
    contain enough source material (including examples), writers will file
 +
    bugs against Development via BugZilla.</li>
 +
</ul>
  
| width="319" valign="top" style="width:239.4pt;border-top:none;border-left: none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt; padding:0in 5.4pt 0in 5.4pt" |
+
<h2>Tasks/Deliverables</h2>
8/24/11
+
  
|-
+
<p class=MsoNormal>The following tasks are not specifically associated with the
| width="319" valign="top" style="width:239.4pt;border:solid windowtext 1.0pt; border-top:none;padding:0in 5.4pt 0in 5.4pt" |
+
EclipseLink 2.4 release but will be handled by the Documentation team during
Final doc plan
+
this period:</p>
  
| width="319" valign="top" style="width:239.4pt;border-top:none;border-left: none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt; padding:0in 5.4pt 0in 5.4pt" |
+
<h3>General</h3>
8/29/11
+
  
|-
+
<table class=MsoNormalTable border=1 cellspacing=0 cellpadding=0
| width="319" valign="top" style="width:239.4pt;border:solid windowtext 1.0pt; border-top:none;padding:0in 5.4pt 0in 5.4pt" |
+
style='border-collapse:collapse;border:none'>
EclipseLink release 2.4
+
<tr>
 +
  <td width=406 valign=top style='width:304.4pt;border:solid windowtext 1.0pt;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><b><i>Task/Deliverable</i></b></p>
 +
  </td>
 +
  <td width=233 valign=top style='width:174.4pt;border:solid windowtext 1.0pt;
 +
  border-left:none;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><b><i>Writer</i></b></p>
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td width=406 valign=top style='width:304.4pt;border:solid windowtext 1.0pt;
 +
  border-top:none;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Identify topics in the JPA TOC that are documented in the
 +
  JPA specification to clarify which existing items are the responsibility of
 +
  Documentation and which are the responsibility of Development.</p>
 +
  </td>
 +
  <td width=233 valign=top style='width:174.4pt;border-top:none;border-left:
 +
  none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Ben Gelernter, Rick Sapir</p>
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td width=406 valign=top style='width:304.4pt;border:solid windowtext 1.0pt;
 +
  border-top:none;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Review JPA topics to make sure all 2.2 and 2.3 features
 +
  are documented and reviewed. Update as needed.</p>
 +
  <p class=MsoNormal>&nbsp;</p>
 +
  </td>
 +
  <td width=233 valign=top style='width:174.4pt;border-top:none;border-left:
 +
  none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Ben Gelernter</p>
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td width=406 valign=top style='width:304.4pt;border:solid windowtext 1.0pt;
 +
  border-top:none;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Create an Introduction/Overview section:</p>
 +
  <ul style='margin-top:0in' type=disc>
 +
  <li class=MsoNormal>If introductory information exists elsewhere (e.g., the
 +
      JPA intro section), move it to this section</li>
 +
  <li class=MsoNormal>Write any introductory information that is missing,
 +
      including cross-references to the specifications (JPA, JAXB)</li>
 +
  </ul>
 +
  </td>
 +
  <td width=233 valign=top style='width:174.4pt;border-top:none;border-left:
 +
  none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Ben Gelernter, Rick Sapir</p>
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td width=406 valign=top style='width:304.4pt;border:solid windowtext 1.0pt;
 +
  border-top:none;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Review existing topics for consistency, e.g.:</p>
 +
  <ul style='margin-top:0in' type=disc>
 +
  <li class=MsoNormal>Navigation links</li>
 +
  <li class=MsoNormal>Lists of links in topics (TOCs for sections)</li>
 +
  <li class=MsoNormal>Headers/footers</li>
 +
  <li class=MsoNormal>Tables, examples</li>
 +
  <li class=MsoNormal>Key API links (qualified by path?) </li>
 +
  </ul>
 +
  </td>
 +
  <td width=233 valign=top style='width:174.4pt;border-top:none;border-left:
 +
  none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Ben Gelernter</p>
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td width=406 valign=top style='width:304.4pt;border:solid windowtext 1.0pt;
 +
  border-top:none;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Create documentation style guide specific to EclipseLink. </p>
 +
  <p class=MsoNormal>The main source for documentation style is the Eclipse
 +
  documentation standards. However, as EclipseLink-specific style issues that not
 +
  covered by the Eclipse standards arise, the writers will post them on this
 +
  wiki page. We will spend minimal time developing standards.</p>
 +
  <p class=MsoNormal>Eclipse Doc Style Guide (for Eclipse Help): <a
 +
  href="http://wiki.eclipse.org/Eclipse_Doc_Style_Guide">http://wiki.eclipse.org/Eclipse_Doc_Style_Guide</a></p>
 +
  <p class=MsoNormal>Writers may also find these pages useful: <a
 +
  href="http://wiki.eclipse.org/DocumentationGuidelines">http://wiki.eclipse.org/DocumentationGuidelines</a>
 +
  and <a href="http://wiki.eclipse.org/DocumentationGuidelines/StyleGuidelines">http://wiki.eclipse.org/DocumentationGuidelines/StyleGuidelines</a></p>
 +
  </td>
 +
  <td width=233 valign=top style='width:174.4pt;border-top:none;border-left:
 +
  none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal> Tom Pfaeffle (create the page)</p>
 +
  <p class=MsoNormal>Entire team may contribute.</p>
 +
  <p class=MsoNormal><b><i>&nbsp;</i></b></p>
 +
  </td>
 +
</tr>
 +
</table>
  
| width="319" valign="top" style="width:239.4pt;border-top:none;border-left: none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt; padding:0in 5.4pt 0in 5.4pt" |
+
<p class=MsoNormal>&nbsp;</p>
<s>10/26/11</s> – probably postponed until "into the new year," per Doug C.
+
  
|}
+
<p class=MsoNormal>The following tables show the features that will be documented
 +
for EL 2.4.</p>
  
&nbsp;
+
<h3>JPA Features</h3>
  
== Audience ==
+
<table class=MsoNormalTable border=1 cellspacing=0 cellpadding=0
 +
  style='border-collapse:collapse;border:none'>
 +
<tr>
 +
  <td valign=top style='border:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><b>Feature          </b></p>
 +
  </td>
 +
  <td valign=top style='border:solid windowtext 1.0pt;border-left:none;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><b>Design documents, examples, any other source material</b></p>
 +
  </td>
 +
  <td valign=top style='border:solid windowtext 1.0pt;border-left:none;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><b>Subject Matter Expert</b></p>
 +
  </td>
 +
  <td valign=top style='border:solid windowtext 1.0pt;border-left:none;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><b>Writer</b></p>
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td valign=top style='border:solid windowtext 1.0pt;border-top:none;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><b>Enhanced Schema Provisioning: </b>Schema upgrade to
 +
  handle application version upgrades. Upon request the Schmea will be extended
 +
  to add additional tables, columns, indexes.</p>
 +
  </td>
 +
  <td valign=top style='border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt;
 +
  border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Not yet available?</p>
 +
  </td>
 +
  <td valign=top style='border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt;
 +
  border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><span class=ornotepadcommenttext>Peter Krogh and/or
 +
  designee from his team</span></p>
 +
  </td>
 +
  <td valign=top style='border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt;
 +
  border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>&nbsp;</p>
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td valign=top style='border:solid windowtext 1.0pt;border-top:none;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><b>MetadataSource support for PU Properties: </b>During
 +
  the bootstrap of a JPA persistence unit the Metadatasource will provide
 +
  additional PU properties that can come from an external source to customize
 +
  the PU properties used in the EntityManagerFactory creation.</p>
 +
  </td>
 +
  <td valign=top style='border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt;
 +
  border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Not yet available?</p>
 +
  </td>
 +
  <td valign=top style='border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt;
 +
  border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>&quot;</p>
 +
  </td>
 +
  <td valign=top style='border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt;
 +
  border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>&nbsp;</p>
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td valign=top style='border:solid windowtext 1.0pt;border-top:none;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><b>JPA 2.1</b>: Provide early access to some of the JPA
 +
  2.1 defined features. This will depend on the progress the expert group
 +
  makes.</p>
 +
  </td>
 +
  <td valign=top style='border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt;
 +
  border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Not yet available?</p>
 +
  </td>
 +
  <td valign=top style='border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt;
 +
  border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>&quot;</p>
 +
  </td>
 +
  <td valign=top style='border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt;
 +
  border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>&nbsp;</p>
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td valign=top style='border:solid windowtext 1.0pt;border-top:none;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><b>Gemini JPA</b>: With the Gemini JPA 1.0 release
 +
  scheduled to come out this summer the current solution available (which we
 +
  have deprecated) need to be fully transitioned to leverage the Gemini
 +
  solutions. This will involve updates or migration of examples but may also
 +
  involve a coordinated Gemini release if feature work is included</p>
 +
  <p class=MsoNormal>From the Gemini JPA wiki (http://www.eclipse.org/gemini/jpa/):
 +
  &quot;The Gemini JPA project is about modular implementations of Java
 +
  Persistence API technology. This project currently provides the integration
 +
  with the EclipseLink JPA provider to support the OSGi JPA specification
 +
  approach that clients can use to get JPA support in an OSGi framework.&quot;</p>
 +
  </td>
 +
  <td valign=top style='border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt;
 +
  border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Not yet available?</p>
 +
  </td>
 +
  <td valign=top style='border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt;
 +
  border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>&quot;</p>
 +
  </td>
 +
  <td valign=top style='border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt;
 +
  border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>&nbsp;</p>
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td valign=top style='border:solid windowtext 1.0pt;border-top:none;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><b>Database Change Event Cache Invalidation: </b>This
 +
  project will provide an infrastructure for supporting database change events
 +
  to invalidate the changed objects in the EclipseLink shared cache.</p>
 +
  </td>
 +
  <td valign=top style='border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt;
 +
  border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><a
 +
  href="http://wiki.eclipse.org/EclipseLink/DesignDocs/356812"
 +
  title="EclipseLink/DesignDocs/356812">Database Change Event Cache
 +
  Invalidation</a></p>
 +
  </td>
 +
  <td valign=top style='border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt;
 +
  border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>&quot;</p>
 +
  </td>
 +
  <td valign=top style='border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt;
 +
  border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>&nbsp;</p>
 +
  </td>
 +
</tr>
 +
</table>
  
{| cellspacing="0" cellpadding="0" border="1" style="border-collapse:collapse;border:none" class="MsoNormalTable"
+
<h3>MOXy Features</h3>
|-
+
| width="187" valign="top" style="width:1.95in;border:solid windowtext 1.0pt; padding:0in 5.4pt 0in 5.4pt" |
+
'''User'''
+
  
| width="451" valign="top" style="width:4.7in;border:solid windowtext 1.0pt; border-left:none;padding:0in 5.4pt 0in 5.4pt" |
+
<table class=MsoNormalTable border=1 cellspacing=0 cellpadding=0
'''Description'''  
+
style='border-collapse:collapse;border:none'>
 +
<tr>
 +
  <td width=164 valign=top style='width:123.3pt;border:solid windowtext 1.0pt;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><b>Feature         </b></p>
 +
  </td>
 +
  <td width=283 valign=top style='width:212.2pt;border:solid windowtext 1.0pt;
 +
  border-left:none;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><b>Design documents, examples, any other source material</b></p>
 +
  </td>
 +
  <td width=124 valign=top style='width:92.85pt;border:solid windowtext 1.0pt;
 +
  border-left:none;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><b>Subject Matter Expert</b></p>
 +
  </td>
 +
  <td width=67 valign=top style='width:50.45pt;border:solid windowtext 1.0pt;
 +
  border-left:none;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><b>Writer</b></p>
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td width=164 valign=top style='width:123.3pt;border:solid windowtext 1.0pt;
 +
  border-top:none;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><b>Object-JSON</b> Mapping support</p>
 +
  </td>
 +
  <td width=283 valign=top style='width:212.2pt;border-top:none;border-left:
 +
  none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><span class=ornotepadcommenttext><a
 +
  href="http://wiki.eclipse.org/EclipseLink/DesignDocs/350483">Object-to-JSON
 +
  Binding Layer</a> </span></p>
 +
  </td>
 +
  <td width=124 valign=top style='width:92.85pt;border-top:none;border-left:
 +
  none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Blaise Doughan, David Twelves</p>
 +
  </td>
 +
  <td width=67 valign=top style='width:50.45pt;border-top:none;border-left:
 +
  none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Rick Sapir</p>
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td width=164 valign=top style='width:123.3pt;border:solid windowtext 1.0pt;
 +
  border-top:none;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><span class=ornotepadcommenttext>Set of features to match <b>extensions
 +
  provided by JAXB RI</b></span></p>
 +
  </td>
 +
  <td width=283 valign=top style='width:212.2pt;border-top:none;border-left:
 +
  none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><span class=ornotepadcommenttext>&quot;We are currently
 +
  developing and tracking this list through Bugzilla enhancements.&quot; [David
 +
  Twelves]</span></p>
 +
  </td>
 +
  <td width=124 valign=top style='width:92.85pt;border-top:none;border-left:
 +
  none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><span class=ornotepadcommenttext>David Twelves</span></p>
 +
  </td>
 +
  <td width=67 valign=top style='width:50.45pt;border-top:none;border-left:
 +
  none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>&nbsp;</p>
 +
  </td>
 +
</tr>
 +
</table>
  
|-
+
<h3>DBWS Features</h3>
| width="187" valign="top" style="width:1.95in;border:solid windowtext 1.0pt; border-top:none;padding:0in 5.4pt 0in 5.4pt" |
+
Application Developers
+
  
| width="451" valign="top" style="width:4.7in;border-top:none;border-left:none; border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt; padding:0in 5.4pt 0in 5.4pt" |
+
<table class=MsoNormalTable border=1 cellspacing=0 cellpadding=0
Developers who want to develop applications using any of the following technologies for persistence services:  
+
style='border-collapse:collapse;border:none'>
 +
<tr>
 +
  <td valign=top style='border:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><b>Feature</b></p>
 +
  </td>
 +
  <td valign=top style='border:solid windowtext 1.0pt;border-left:none;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><b>Design documents, examples, any other source material</b></p>
 +
  </td>
 +
  <td valign=top style='border:solid windowtext 1.0pt;border-left:none;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><b>Subject Matter Expert</b></p>
 +
  </td>
 +
  <td valign=top style='border:solid windowtext 1.0pt;border-left:none;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><b>Writer</b></p>
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td valign=top style='border:solid windowtext 1.0pt;border-top:none;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><b>Parse DDL to extract database metadata</b>: Change the
 +
  way type metadata is accessed by DBWSBuilder, providing support for the
 +
  following enhancement requests:</p>
 +
  <ul style='margin-top:0in' type=disc>
 +
  <li class=MsoNormal><span class=ornotepadcommenttext>DBWSProvider does not
 +
      handle weakly-typed REF CURSORs (bug 325124)</span></li>
 +
  <li class=MsoNormal><span class=ornotepadcommenttext> DBWSProvider does not
 +
      handle strongly-typed REF CURSORs (bug 339721)</span></li>
 +
  <li class=MsoNormal><span class=ornotepadcommenttext>DBWSProvider does not
 +
      handle optional arguments for Stored Procedures (bug 234385)</span></li>
 +
  <li class=MsoNormal><span class=ornotepadcommenttext>DBWS does not handle
 +
      %ROWTYPE mix of PL/SQL types and JDBC Advanced types bug 329435</span></li>
 +
  </ul>
 +
  </td>
 +
  <td valign=top style='border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt;
 +
  border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><a
 +
  href="http://wiki.eclipse.org/EclipseLink/Development/DBWS/ParseDDLforMetadata">Parsing
 +
  DDL for Metadata Design Spec</a> </p>
 +
  </td>
 +
  <td valign=top style='border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt;
 +
  border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Mike Norman, David Twelves</p>
 +
  </td>
 +
  <td valign=top style='border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt;
 +
  border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Rick Sapir</p>
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td valign=top style='border:solid windowtext 1.0pt;border-top:none;
 +
  padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal><b>RESTful JPA</b>: Provide a JAX-RS solution for easily
 +
  making a JPA persistence unit available through REST calls.</p>
 +
  <p class=MsoNormal>(<a
 +
  href="http://wiki.eclipse.org/EclipseLink/Development/2.4.0">EclipseLink
 +
  2.4.0 Development Plans</a> page says &quot;BWS Generation of JAX-RS Web
 +
  Services.&quot;</p>
 +
  </td>
 +
  <td valign=top style='border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt;
 +
  border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Not yet available.</p>
 +
  <p class=MsoNormal>&quot;Planned for later in 2.4 dev cycle.&quot; [David
 +
  Twelves]</p>
 +
  </td>
 +
  <td valign=top style='border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt;
 +
  border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>David Twelves</p>
 +
  </td>
 +
  <td valign=top style='border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt;
 +
  border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt'>
 +
  <p class=MsoNormal>Rick Sapir</p>
 +
  </td>
 +
</tr>
 +
</table>
  
*Java Persistence Architecture (JPA) 2.x plus the EclipseLink JPA extensions
+
<p class=MsoNormal>&nbsp;</p>
*Java Architecture for XML Binding 2.x (JAXB) plus the EclipseLink MOXy extensions.
+
*Java API for XML Web Services 2.x (JAX-WS) plus EclipseLink Database Web Services (DBWS) features.
+
  
Developers should be familiar with the concepts and programming practices of:
+
<h3>Printable Versions</h3>
  
*Java SE
+
<p class=MsoNormal>We plan to provide a printable version of the EclipseLink
*Java EE
+
wiki topics. When a new version of EclipseLink is released (and all
 +
documentation issues are wrapped up), we will  generate a PDF version (and, if
 +
possible an HTML version)<b><i> </i></b>of the wiki topics and post that as the
 +
official documentation for a certain release. Updates may continue to be made
 +
on the wiki, but the PDF/HTML will not be regenerated until the next release.</p>
  
'''''//REVIEWERS: Should this specify a Java version? which?//'''''
+
<p class=MsoNormal>Details about how to accomplish this are not yet resolved.</p>
  
'''Assumed knowledge:'''
+
<h1>Scheduling and Reviews</h1>
  
*Developers using EclipseLink JPA should be familiar with the concepts and programming practices of JPA 2.x.
+
<p class=MsoNormal>Schedules must include time for:</p>
*Developers using EclipseLink MOXy should be familiar with the concepts and programming practices of JAXB 2.x.
+
*Developers using EclipseLink DBWS should be familiar with the concepts and programming practices of JAX-WS 2.x.
+
  
|-
+
<ul style='margin-top:0in' type=disc>
| width="187" valign="top" style="width:1.95in;border:solid windowtext 1.0pt; border-top:none;padding:0in 5.4pt 0in 5.4pt" |
+
<li class=MsoNormal>Documentation reviews by Dev/QA. Reviews will be conducted
Administrator/Deployer
+
    on the wiki.</li>
 +
<li class=MsoNormal>A final production review of the wiki including, but not limited
 +
    to:</li>
 +
</ul>
  
| width="451" valign="top" style="width:4.7in;border-top:none;border-left:none; border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt; padding:0in 5.4pt 0in 5.4pt" |
+
<ul style='margin-top:0in' type=disc>
<br> '''Assumed knowledge:'''
+
<ul style='margin-top:0in' type=circle>
 +
  <li class=MsoNormal>Links to samples</li>
 +
  <li class=MsoNormal>Links to Javadoc</li>
 +
  <li class=MsoNormal>Cross-references</li>
 +
  <li class=MsoNormal>Style consistency</li>
 +
</ul>
 +
</ul>
  
These users should be familiar with basic operations of the chosen Java EE compliant application server.  
+
<p class=MsoNormal style='text-indent:.5in'>All writers will contribute to the
 +
production review.</p>
  
'''''//REVIEWERS: Is this correct simply to say "Java EE compliant app server"? Should it be something like "Java'''''<b>''<span style="font-size:14.0pt;line-height:115%">5</span> EE compliant app server—some features are available only with Java 6 (or 7?) EE, and therefore users of those features should be familiar with those features in Java 6/7."? It may not even be important to specify. Please advise//''</b>  
+
<h1>Bugs</h1>
  
|}
+
<p class=MsoNormal>All writers must have BugZilla accounts and review and
 +
handle documentation bugs against their EclipseLink topics.</p>
  
&nbsp;
+
<p class=MsoNormal>If a writer is responsible for a feature that has no
 +
corresponding design documentation or if the design documentation does not
 +
contain enough information (missing details, code snippets, release, etc.), the
 +
writer should file a BugZilla bug against Development. (Use your judgment:
 +
often a phone call or e-mail can clear up a problem.)</p>
  
== Planned Documentation Deliverables  ==
+
<h1>Assignments</h1>
  
The Documentation team will document EclipseLink-specific features for:
+
<table class=MsoNormalTable border=1 cellspacing=0 cellpadding=0
 
+
style='border-collapse:collapse;border:none'>
*JPA (this is the highest priority)
+
<tr>
*MOXy
+
  <td width=319 valign=top style='width:239.4pt;border:solid windowtext 1.0pt;
*DBWS
+
  padding:0in 5.4pt 0in 5.4pt'>
 
+
  <p class=MsoNormal>Joe Garcia</p>
The Documentation team will not document EIS, SDO, <span class="ornotepadcommenttext">or any other "native" TopLink
+
  </td>
functionality (i.e., non-JPA such as ORM, OX, etc.)</span>..
+
  <td width=319 valign=top style='width:239.4pt;border:solid windowtext 1.0pt;
 
+
  border-left:none;padding:0in 5.4pt 0in 5.4pt'>
=== Documentation Design  ===
+
  <p class=MsoNormal>Manager </p>
 
+
  </td>
The wiki topics will be handled as follows:
+
  </tr>
 
+
  <tr>
*All EclipseLink documentation will be maintained under the ''Documentation Center'' on the EclipseLink wiki at &lt;a href="http://wiki.eclipse.org/EclipseLink/UserGuide"&gt;http://wiki.eclipse.org/EclipseLink/UserGuide&lt;/a&gt;.
+
  <td width=319 valign=top style='width:239.4pt;border:solid windowtext 1.0pt;
*Versioning will be handled as follows:
+
  border-top:none;padding:0in 5.4pt 0in 5.4pt'>
*A note "New in EL 2.''n''" will be placed next to new topics in the TOCs, where ''n'' refers to the release when the feature was introduced. This is currently handled using template <span>{{EclipseLink/NewIn2<i>n</i>}}</span>.
+
  <p class=MsoNormal>Donna Micozzi</p>
*A note " New in version 2.''n''." will be added at the beginning of a topic documenting a new feature. This is currently handled using <span>{{EclipseLink_NewIn|version=2.n}}.</span>
+
  </td>
*If a new feature is handled in an existing topic and the topic changes more than 50%, the note " New in version 2.''n''." will be placed at the beginning of the topic or at the beginning of the appropriate section.
+
  <td width=319 valign=top style='width:239.4pt;border-top:none;border-left:
*Header and footers on the wiki page will contain no references to release numbers.
+
  none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
*If a feature is deprecated, a note will placed next to the documentation for the feature.
+
  padding:0in 5.4pt 0in 5.4pt'>
*Each topic will document one "feature." The term "feature" here is somewhat loose. In some cases, it is a single annotation. In some cases, the topic will document how to use multiple annotations together for a specific purpose, e.g., single-table multi=tenancy.
+
  <p class=MsoNormal>Manager </p>
*These topics are more-or-less "reference" topics. That is, they document the primary APIs and XML used to implement the feature. There can be limited discussion about how to use the code to achieve the purpose of the feature, but we will not attempt to put the feature in a larger context or to fully document all related features<span style="color:red">. </span>
+
  <p class=MsoNormal>&nbsp;</p>
*The JPA topics will primarily focus on using annotations, when they are available. For example, a topic may begin with something like, "Use the @Xyz annotation to…" and most or all examples and code snippets will show annotations. When the feature can also be coded using XML, the topic can discuss the XML (including a reference to the schema), but the documentation for XML will not be as extensive as the documentation for the annotation.
+
  </td>
*Every topic will cross-reference:
+
  </tr>
*Any associated example provided by Development and located in the Samples section of the wiki.
+
  <tr>
*Any associated Javadoc. When an annotation is available, the reference will be to the annotation(s), not the "native API."
+
  <td width=319 valign=top style='width:239.4pt;border:solid windowtext 1.0pt;
*The Documentation team will not document features that are not EclipseLink-specific. In particular, features that are documented in the specification for the underlying technology. For example features documented in the ''JSR-000317 JavaTM Persistence 2.0'' specification will not be documented. However, anyone with permission to edit the wiki may add topics to the wiki. As time permits, the Documentation team may provide advice on the organization of topics. Any non-Documentation person adding topics is responsible for adding and maintaining the following:
+
  border-top:none;padding:0in 5.4pt 0in 5.4pt'>
*Previous and Next browse sequence links at the bottom of the page
+
  <p class=MsoNormal>Ben Gelernter</p>
*Links from the Table of Contents
+
  </td>
*Links from the parent, or container, topic, if there is one. For example, the JPA documentation includes a "Weaving Topic" which introduces several weaving-related topics under it.
+
  <td width=319 valign=top style='width:239.4pt;border-top:none;border-left:
 
+
  none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
Note: A container topic should not contain only a list of links. Every topic must include at least an overview sentence. For example: "The EclipseLink cache is an in-memory repository that stores recently read or written objects based on class and primary key values. Caching is discussed in the following topics:"
+
  padding:0in 5.4pt 0in 5.4pt'>
 
+
  <p class=MsoNormal>Lead, JPA topics</p>
*Individual topics will not include cross references to the standard specifications (JPA, JAXB). There will be one overview topic (or an overview topic for each service) that will contain the link to the appropriate specification.
+
  </td>
*If design documents (specs) are not available or do not contain enough source material (including examples), writers will file bugs against Development via BugZilla.
+
</tr>
 
+
<tr>
=== Tasks/Deliverables  ===
+
  <td width=319 valign=top style='width:239.4pt;border:solid windowtext 1.0pt;
 
+
  border-top:none;padding:0in 5.4pt 0in 5.4pt'>
The following tasks are not specifically associated with the EclipseLink 2.4 release but will be handled by the Documentation team during this period:
+
  <p class=MsoNormal>Ed Spear</p>
 
+
  </td>
==== General  ====
+
  <td width=319 valign=top style='width:239.4pt;border-top:none;border-left:
 
+
  none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
{| cellspacing="0" cellpadding="0" border="1" style="border-collapse:collapse;border:none" class="MsoNormalTable"
+
  padding:0in 5.4pt 0in 5.4pt'>
|-
+
  <p class=MsoNormal>JPA topics (TBD)</p>
| width="406" valign="top" style="width:304.4pt;border:solid windowtext 1.0pt; padding:0in 5.4pt 0in 5.4pt" |
+
  </td>
'''''Task/Deliverable'''''  
+
</tr>
 
+
<tr>
| width="233" valign="top" style="width:174.4pt;border:solid windowtext 1.0pt; border-left:none;padding:0in 5.4pt 0in 5.4pt" |
+
  <td width=319 valign=top style='width:239.4pt;border:solid windowtext 1.0pt;
'''''Writer'''''
+
  border-top:none;padding:0in 5.4pt 0in 5.4pt'>
 
+
  <p class=MsoNormal>Rick Sapir</p>
|-
+
  </td>
| width="406" valign="top" style="width:304.4pt;border:solid windowtext 1.0pt; border-top:none;padding:0in 5.4pt 0in 5.4pt" |
+
  <td width=319 valign=top style='width:239.4pt;border-top:none;border-left:
Identify topics in the JPA TOC that are documented in the JPA specification to clarify which existing items are the responsibility of Documentation and which are the responsibility of Development.
+
  none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
 
+
  padding:0in 5.4pt 0in 5.4pt'>
| width="233" valign="top" style="width:174.4pt;border-top:none;border-left: none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt; padding:0in 5.4pt 0in 5.4pt" |
+
  <p class=MsoNormal>MOXy</p>
Ben Gelernter, Rick Sapir
+
  <p class=MsoNormal>DBWS</p>
 
+
  </t
|-
+
| width="406" valign="top" style="width:304.4pt;border:solid windowtext 1.0pt; border-top:none;padding:0in 5.4pt 0in 5.4pt" |
+
Review JPA topics to make sure all 2.2 and 2.3 features are documented and reviewed. Update as needed.
+
 
+
&nbsp;
+
 
+
| width="233" valign="top" style="width:174.4pt;border-top:none;border-left: none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt; padding:0in 5.4pt 0in 5.4pt" |
+
Ben Gelernter
+
 
+
|-
+
| width="406" valign="top" style="width:304.4pt;border:solid windowtext 1.0pt; border-top:none;padding:0in 5.4pt 0in 5.4pt" |
+
Create an Introduction/Overview section:
+
 
+
*If introductory information exists elsewhere (e.g., the JPA intro section), move it to this section
+
*Write any introductory information that is missing, including cross-references to the specifications (JPA, JAXB)
+
 
+
| width="233" valign="top" style="width:174.4pt;border-top:none;border-left: none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt; padding:0in 5.4pt 0in 5.4pt" |
+
Ben Gelernter, Rick Sapir
+
 
+
|-
+
| width="406" valign="top" style="width:304.4pt;border:solid windowtext 1.0pt; border-top:none;padding:0in 5.4pt 0in 5.4pt" |
+
Review existing topics for consistency, e.g.:
+
 
+
*Navigation links
+
*Lists of links in topics (TOCs for sections)
+
*Headers/footers
+
*Tables, examples
+
*Key API links (qualified by path?)
+
 
+
| width="233" valign="top" style="width:174.4pt;border-top:none;border-left: none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt; padding:0in 5.4pt 0in 5.4pt" |
+
Ben Gelernter
+
 
+
|-
+
| width="406" valign="top" style="width:304.4pt;border:solid windowtext 1.0pt; border-top:none;padding:0in 5.4pt 0in 5.4pt" |
+
Create documentation style guide specific to EclipseLink.
+
 
+
The main source for documentation style is the Eclipse documentation standards. However, as EclipseLink-specific style issues that not covered by the Eclipse standards arise, the writers will post them on this wiki page. We will spend minimal time developing standards.
+
 
+
Eclipse Doc Style Guide (for Eclipse Help): &lt;a href="http://wiki.eclipse.org/Eclipse_Doc_Style_Guide"&gt;http://wiki.eclipse.org/Eclipse_Doc_Style_Guide&lt;/a&gt;
+
 
+
Writers may also find these pages useful: &lt;a href="http://wiki.eclipse.org/DocumentationGuidelines"&gt;http://wiki.eclipse.org/DocumentationGuidelines&lt;/a&gt; and &lt;a href="http://wiki.eclipse.org/DocumentationGuidelines/StyleGuidelines"&gt;http://wiki.eclipse.org/DocumentationGuidelines/StyleGuidelines&lt;/a&gt;
+
 
+
| width="233" valign="top" style="width:174.4pt;border-top:none;border-left: none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt; padding:0in 5.4pt 0in 5.4pt" |
+
Tom Pfaeffle (create the page)
+
 
+
Entire team may contribute.
+
 
+
'''''&nbsp;'''''
+
 
+
|}
+
 
+
&nbsp;
+
 
+
The following tables show the features that will be documented for EL 2.4.
+
 
+
==== JPA Features ====
+
 
+
{| cellspacing="0" cellpadding="0" border="1" style="border-collapse:collapse;border:none" class="MsoNormalTable"
+
|-
+
| valign="top" style="border:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt" |
+
'''Feature'''
+
 
+
| valign="top" style="border:solid windowtext 1.0pt;border-left:none; padding:0in 5.4pt 0in 5.4pt" |
+
'''Design documents, examples, any other source material'''
+
 
+
| valign="top" style="border:solid windowtext 1.0pt;border-left:none; padding:0in 5.4pt 0in 5.4pt" |
+
'''Subject Matter Expert'''
+
 
+
| valign="top" style="border:solid windowtext 1.0pt;border-left:none; padding:0in 5.4pt 0in 5.4pt" |
+
'''Writer'''
+
 
+
|-
+
| valign="top" style="border:solid windowtext 1.0pt;border-top:none; padding:0in 5.4pt 0in 5.4pt" |
+
'''Enhanced Schema Provisioning: '''Schema upgrade to handle application version upgrades. Upon request the Schmea will be extended to add additional tables, columns, indexes.
+
 
+
| valign="top" style="border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt; border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt" |
+
Not yet available?
+
 
+
| valign="top" style="border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt; border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt" |
+
?
+
 
+
| valign="top" style="border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt; border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt" |
+
&nbsp;
+
 
+
|-
+
| valign="top" style="border:solid windowtext 1.0pt;border-top:none; padding:0in 5.4pt 0in 5.4pt" |
+
'''MetadataSource support for PU Properties: '''During the bootstrap of a JPA persistence unit the Metadatasource will provide additional PU properties that can come from an external source to customize the PU properties used in the EntityManagerFactory creation.
+
 
+
| valign="top" style="border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt; border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt" |
+
Not yet available?
+
 
+
| valign="top" style="border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt; border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt" |
+
?
+
 
+
| valign="top" style="border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt; border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt" |
+
&nbsp;
+
 
+
|-
+
| valign="top" style="border:solid windowtext 1.0pt;border-top:none; padding:0in 5.4pt 0in 5.4pt" |
+
'''JPA 2.1''': Provide early access to some of the JPA 2.1 defined features. This will depend on the progress the expert group makes.
+
 
+
| valign="top" style="border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt; border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt" |
+
Not yet available?
+
 
+
| valign="top" style="border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt; border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt" |
+
?
+
 
+
| valign="top" style="border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt; border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt" |
+
&nbsp;
+
 
+
|-
+
| valign="top" style="border:solid windowtext 1.0pt;border-top:none; padding:0in 5.4pt 0in 5.4pt" |
+
'''Gemini JPA''': With the Gemini JPA 1.0 release scheduled to come out this summer the current solution available (which we have deprecated) need to be fully transitioned to leverage the Gemini solutions. This will involve updates or migration of examples but may also involve a coordinated Gemini release if feature work is included
+
 
+
From the Gemini JPA wiki (http://www.eclipse.org/gemini/jpa/): "The Gemini JPA project is about modular implementations of Java Persistence API technology. This project currently provides the integration with the EclipseLink JPA provider to support the OSGi JPA specification approach that clients can use to get JPA support in an OSGi framework."
+
 
+
| valign="top" style="border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt; border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt" |
+
Not yet available?
+
 
+
| valign="top" style="border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt; border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt" |
+
?
+
 
+
| valign="top" style="border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt; border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt" |
+
&nbsp;
+
 
+
|}
+
 
+
==== MOXy Features ====
+
 
+
{| cellspacing="0" cellpadding="0" border="1" style="border-collapse:collapse;border:none" class="MsoNormalTable"
+
|-
+
| width="164" valign="top" style="width:123.3pt;border:solid windowtext 1.0pt; padding:0in 5.4pt 0in 5.4pt" |
+
'''Feature'''
+
 
+
| width="283" valign="top" style="width:212.2pt;border:solid windowtext 1.0pt; border-left:none;padding:0in 5.4pt 0in 5.4pt" |
+
'''Design documents, examples, any other source material'''
+
 
+
| width="124" valign="top" style="width:92.85pt;border:solid windowtext 1.0pt; border-left:none;padding:0in 5.4pt 0in 5.4pt" |
+
'''Subject Matter Expert'''
+
 
+
| width="67" valign="top" style="width:50.45pt;border:solid windowtext 1.0pt; border-left:none;padding:0in 5.4pt 0in 5.4pt" |
+
'''Writer'''
+
 
+
|-
+
| width="164" valign="top" style="width:123.3pt;border:solid windowtext 1.0pt; border-top:none;padding:0in 5.4pt 0in 5.4pt" |
+
'''Object-JSON''' Mapping support
+
 
+
| width="283" valign="top" style="width:212.2pt;border-top:none;border-left: none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt; padding:0in 5.4pt 0in 5.4pt" |
+
Not yet available?
+
 
+
| width="124" valign="top" style="width:92.85pt;border-top:none;border-left: none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt; padding:0in 5.4pt 0in 5.4pt" |
+
?
+
 
+
| width="67" valign="top" style="width:50.45pt;border-top:none;border-left: none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt; padding:0in 5.4pt 0in 5.4pt" |
+
Rick Sapir
+
 
+
|}
+
 
+
==== DBWS Features  ====
+
 
+
{| cellspacing="0" cellpadding="0" border="1" style="border-collapse:collapse;border:none" class="MsoNormalTable"
+
|-
+
| valign="top" style="border:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt" |
+
'''Feature'''
+
 
+
| valign="top" style="border:solid windowtext 1.0pt;border-left:none; padding:0in 5.4pt 0in 5.4pt" |
+
'''Design documents, examples, any other source material'''
+
 
+
| valign="top" style="border:solid windowtext 1.0pt;border-left:none; padding:0in 5.4pt 0in 5.4pt" |
+
'''Subject Matter Expert'''
+
 
+
| valign="top" style="border:solid windowtext 1.0pt;border-left:none; padding:0in 5.4pt 0in 5.4pt" |
+
'''Writer'''
+
 
+
|-
+
| valign="top" style="border:solid windowtext 1.0pt;border-top:none; padding:0in 5.4pt 0in 5.4pt" |
+
'''2.3 Features:'''
+
 
+
| valign="top" style="border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt; border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt" |
+
Meetings in progress
+
 
+
| valign="top" style="border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt; border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt" |
+
David Twelves
+
 
+
| valign="top" style="border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt; border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt" |
+
&nbsp;
+
 
+
|-
+
| valign="top" style="border:solid windowtext 1.0pt;border-top:none; padding:0in 5.4pt 0in 5.4pt" |
+
'''RESTful JPA''': Provide a JAX-RS solution for easily making a JPA persistence unit available through REST calls.
+
 
+
| valign="top" style="border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt; border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt" |
+
Not yet available?
+
 
+
| valign="top" style="border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt; border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt" |
+
David Twelves
+
 
+
| valign="top" style="border-top:none;border-left:none;border-bottom:solid windowtext 1.0pt; border-right:solid windowtext 1.0pt;padding:0in 5.4pt 0in 5.4pt" |
+
Rick Sapir
+
 
+
|}
+
 
+
&nbsp;  
+
 
+
== Scheduling and Reviews ==
+
 
+
Schedules must include time for:
+
 
+
*Documentation reviews by Dev/QA. Reviews will be conducted on the wiki.
+
*A final production review of the wiki including, but not limited to:
+
 
+
*Links to samples
+
*Links to Javadoc
+
*Cross-references
+
*Style consistency
+
 
+
All writers will contribute to the production review.
+
 
+
== Bugs ==
+
 
+
All writers must have BugZilla accounts and review and handle documentation bugs against their EclipseLink topics.
+
 
+
If a writer is responsible for a feature that has no corresponding design documentation or if the design documentation does not contain enough information (missing details, code snippets, release, etc.), the writer should file a BugZilla bug against Development. (Use your judgment: often a phone call or e-mail can clear up a problem.)
+
 
+
= Assignments  =
+
 
+
{| cellspacing="0" cellpadding="0" border="1" style="border-collapse:collapse;border:none" class="MsoNormalTable"
+
|-
+
| width="319" valign="top" style="width:239.4pt;border:solid windowtext 1.0pt; padding:0in 5.4pt 0in 5.4pt" |
+
Joe Garcia
+
 
+
| width="319" valign="top" style="width:239.4pt;border:solid windowtext 1.0pt; border-left:none;padding:0in 5.4pt 0in 5.4pt" |
+
Manager
+
 
+
|-
+
| width="319" valign="top" style="width:239.4pt;border:solid windowtext 1.0pt; border-top:none;padding:0in 5.4pt 0in 5.4pt" |
+
Donna Micozzi
+
 
+
| width="319" valign="top" style="width:239.4pt;border-top:none;border-left: none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt; padding:0in 5.4pt 0in 5.4pt" |
+
Manager
+
 
+
&nbsp;
+
 
+
|-
+
| width="319" valign="top" style="width:239.4pt;border:solid windowtext 1.0pt; border-top:none;padding:0in 5.4pt 0in 5.4pt" |
+
Ben Gelernter  
+
 
+
| width="319" valign="top" style="width:239.4pt;border-top:none;border-left: none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt; padding:0in 5.4pt 0in 5.4pt" |
+
Lead, JPA topics  
+
 
+
|-
+
| width="319" valign="top" style="width:239.4pt;border:solid windowtext 1.0pt; border-top:none;padding:0in 5.4pt 0in 5.4pt" |
+
Ed Spear  
+
 
+
| width="319" valign="top" style="width:239.4pt;border-top:none;border-left: none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt; padding:0in 5.4pt 0in 5.4pt" |
+
JPA topics (TBD)  
+
 
+
|-
+
| width="319" valign="top" style="width:239.4pt;border:solid windowtext 1.0pt; border-top:none;padding:0in 5.4pt 0in 5.4pt" |
+
Rick Sapir  
+
 
+
| width="319" valign="top" style="width:239.4pt;border-top:none;border-left: none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt; padding:0in 5.4pt 0in 5.4pt" |
+
MOXy
+
 
+
DBWS
+
 
+
|-
+
| width="319" valign="top" style="width:239.4pt;border:solid windowtext 1.0pt; border-top:none;padding:0in 5.4pt 0in 5.4pt" |
+
Tom Pfaeffle
+
 
+
| width="319" valign="top" style="width:239.4pt;border-top:none;border-left: none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt; padding:0in 5.4pt 0in 5.4pt" |
+
JPA topics (TBD)
+
 
+
|}
+
 
+
&nbsp;
+
 
+
== Issues  ==
+
 
+
*Printable Version
+
 
+
of the wiki topics and post that as the official documentation for a certain release. Updates may continue to be made on the wiki, but the PDF/HTML will not be regenerated until the next release.
+
 
+
Details about how to accomplish this are not yet resolved.
+
 
+
*Metadata to improve searching
+
</div>
+

Revision as of 10:09, 15 September 2011

Documentation Plan for EclipseLink 2.4

Change Record

Date

Author

Change Record

7/28/11

Ben Gelernter

First draft

8/11/11

Ben Gelernter

Incorporated changes from doc manager  review.

8/17/11

Ben Gelernter

Incorporated changes from doc team review

9/15/11

Ben Gelernter

Incorporated changes from Dev/QA/PM  review

 

This documentation plan describes how the documentation team will provide EclipseLink documentation for the EclipseLink; (EL) 2.4 release.

Schedule

Milestone

Date

Doc plan first draft

8/10/11

Doc plan posted

8/17/11

Doc plan comments due

8/24/11

Final doc plan

8/29/11

EclipseLink release 2.4

2.4.1 Juno: 2012-06-27
2.4.0: 2012-03-28

(See: <a href="http://www.eclipse.org/projects/project_summary.php?projectid=rt.eclipselink" target="_blank">http://www.eclipse.org/projects/project_summary.php?projectid=rt.eclipselink</a> for any changes to these dates.)

 

Audience

</table>

 

Audience

User

Description

Application Developers

Developers who want to develop applications using any of the following technologies for persistence services:

 <uy.php?projectid=rt.eclipselink"
 target="_blank">http://www.eclipse.org/projects/project_summary.php?projectid=rt.eclipselink</a>
 for any changes to these dates.)</span></p>

User

Description

Application Developers

Developers who want to develop applications using any of the following technologies for persistence services:

  • Java Persistence Architecture (JPA) 2.x plus the EclipseLink JPA extensions
  • Java Architecture for XML Binding 2.x (JAXB) plus the EclipseLink MOXy extensions.
  • Java API for XML Web Services 2.x (JAX-WS) plus EclipseLink Database Web Services (DBWS) features.

Developers should be familiar with the concepts and programming practices of the version of Java SE and Java EE supported by their deployment platform.

Assumed knowledge:

  • Developers using EclipseLink JPA should be familiar with the concepts and programming practices of JPA 2.x.
  • Developers using EclipseLink MOXy should be familiar with the concepts and programming practices of JAXB 2.x.
  • Developers using EclipseLink DBWS should be familiar with the concepts and programming practices of JAX-WS 2.x.

Administrator/Deployer

Users who want to deploy and manage applications using the EclipseLink persistence technologies.

Assumed knowledge:

These users should be familiar with basic operations of the chosen application server.

 

Planned Documentation Deliverables

The Documentation team will document EclipseLink-specific features for:

  • JPA
  • MOXy
  • DBWS

Note: JPA is the most commonly used and the biggest, therefore more resources will be devoted to JPA than the other services.

The Documentation team will not document EIS, SDO, or any other "native" TopLink functionality (i.e., non-JPA such as ORM, OX, etc.)..

Documentation Design

The wiki topics will be handled as follows:

  • All EclipseLink documentation will be maintained under the Documentation Center on the EclipseLink wiki at <a href="http://wiki.eclipse.org/EclipseLink/UserGuide">http://wiki.eclipse.org/EclipseLink/UserGuide</a>.
  • Versioning will be handled as follows:
    • A note "New in EL 2.n" will be placed next to new topics in the TOCs, where n refers to the release when the feature was introduced. This is currently handled using template {{EclipseLink/NewIn2n}}.
    • A note  " New in version 2.n." will be added at the beginning of a topic documenting a new feature.  This is currently handled using
      EL NewIn.png New in version 2.n.
      .
    • If a new feature is handled in an existing topic and the topic changes more than 50%, the note " New in version 2.n." will be placed at the beginning of the topic or at the beginning of the appropriate section.
    • Header and footers on the wiki page will contain no references to release numbers.
    • If a feature is deprecated, a note will placed next to the documentation for the feature.
  • Each topic will document one "feature." The term "feature" here is somewhat loose. In some cases, it is a single annotation. In some cases, the topic will document how to use multiple annotations together for a specific purpose, e.g., single-table multi=tenancy.
  • These topics are more-or-less "reference" topics. That is, they document the primary APIs and XML used to implement the feature. There can be limited discussion about how to use the code to achieve the purpose of the feature, but we will not attempt to put the feature in a larger context or to fully document all related features.
  • The JPA topics will primarily focus on using annotations, when they are available. For example, a topic may begin with something like, "Use the @Xyz annotation to…" and most or all examples and code snippets will show annotations. When the feature can also be coded using XML, the topic can discuss the XML (including a reference to the schema), but the documentation for XML will not be as extensive as the documentation for the annotation.
  • Every topic will cross-reference:
    •  Any associated example provided by Development and located in the Samples section of the wiki.
    • Any associated Javadoc. When an annotation is available, the reference will be to the annotation(s), not the "native API."
  • The Documentation team will not document features that are not EclipseLink-specific. In particular, features that are documented in the specification for the underlying technology. For example features documented in the JSR-000317 JavaTM Persistence 2.0 specification will not be documented.  However, anyone with permission to edit the wiki may add topics to the wiki. As time permits, the Documentation team may provide advice on the organization of topics. Any non-Documentation person adding topics is responsible for adding and maintaining the following:
    • Previous and Next browse sequence links at the bottom of the page
    • Links from the Table of Contents
    • Links from the parent, or container, topic, if there is one. For example, the JPA documentation includes a "Weaving Topic" which introduces several weaving-related topics under it.

Note: A container topic should not contain only a list of links. Every topic must include at least an overview sentence. For example:  "The EclipseLink cache is an in-memory repository that stores recently read or written objects based on class and primary key values. Caching is discussed in the following topics:"

  • Individual topics will not include cross references to the standard specifications (JPA, JAXB). There will be one overview topic (or an overview topic for each service) that will contain the link to the appropriate specification.
  • If design documents (specs) are not available or do not contain enough source material (including examples), writers will file bugs against Development via BugZilla.

Tasks/Deliverables

The following tasks are not specifically associated with the EclipseLink 2.4 release but will be handled by the Documentation team during this period:

General

Task/Deliverable

Writer

Identify topics in the JPA TOC that are documented in the JPA specification to clarify which existing items are the responsibility of Documentation and which are the responsibility of Development.

Ben Gelernter, Rick Sapir

Review JPA topics to make sure all 2.2 and 2.3 features are documented and reviewed. Update as needed.

 

Ben Gelernter

Create an Introduction/Overview section:

  • If introductory information exists elsewhere (e.g., the JPA intro section), move it to this section
  • Write any introductory information that is missing, including cross-references to the specifications (JPA, JAXB)

Ben Gelernter, Rick Sapir

Review existing topics for consistency, e.g.:

  • Navigation links
  • Lists of links in topics (TOCs for sections)
  • Headers/footers
  • Tables, examples
  • Key API links (qualified by path?)

Ben Gelernter

Create documentation style guide specific to EclipseLink.

The main source for documentation style is the Eclipse documentation standards. However, as EclipseLink-specific style issues that not covered by the Eclipse standards arise, the writers will post them on this wiki page. We will spend minimal time developing standards.

Eclipse Doc Style Guide (for Eclipse Help): <a href="http://wiki.eclipse.org/Eclipse_Doc_Style_Guide">http://wiki.eclipse.org/Eclipse_Doc_Style_Guide</a>

Writers may also find these pages useful: <a href="http://wiki.eclipse.org/DocumentationGuidelines">http://wiki.eclipse.org/DocumentationGuidelines</a> and <a href="http://wiki.eclipse.org/DocumentationGuidelines/StyleGuidelines">http://wiki.eclipse.org/DocumentationGuidelines/StyleGuidelines</a>

 Tom Pfaeffle (create the page)

Entire team may contribute.

 

 

The following tables show the features that will be documented for EL 2.4.

JPA Features

Feature         

Design documents, examples, any other source material

Subject Matter Expert

Writer

Enhanced Schema Provisioning: Schema upgrade to handle application version upgrades. Upon request the Schmea will be extended to add additional tables, columns, indexes.

Not yet available?

Peter Krogh and/or designee from his team

 

MetadataSource support for PU Properties: During the bootstrap of a JPA persistence unit the Metadatasource will provide additional PU properties that can come from an external source to customize the PU properties used in the EntityManagerFactory creation.

Not yet available?

"

 

JPA 2.1: Provide early access to some of the JPA 2.1 defined features. This will depend on the progress the expert group makes.

Not yet available?

"

 

Gemini JPA: With the Gemini JPA 1.0 release scheduled to come out this summer the current solution available (which we have deprecated) need to be fully transitioned to leverage the Gemini solutions. This will involve updates or migration of examples but may also involve a coordinated Gemini release if feature work is included

From the Gemini JPA wiki (http://www.eclipse.org/gemini/jpa/): "The Gemini JPA project is about modular implementations of Java Persistence API technology. This project currently provides the integration with the EclipseLink JPA provider to support the OSGi JPA specification approach that clients can use to get JPA support in an OSGi framework."

Not yet available?

"

 

Database Change Event Cache Invalidation: This project will provide an infrastructure for supporting database change events to invalidate the changed objects in the EclipseLink shared cache.

<a href="http://wiki.eclipse.org/EclipseLink/DesignDocs/356812" title="EclipseLink/DesignDocs/356812">Database Change Event Cache Invalidation</a>

"

 

MOXy Features

Feature        

Design documents, examples, any other source material

Subject Matter Expert

Writer

Object-JSON Mapping support

<a href="http://wiki.eclipse.org/EclipseLink/DesignDocs/350483">Object-to-JSON Binding Layer</a>

Blaise Doughan, David Twelves

Rick Sapir

Set of features to match extensions provided by JAXB RI

"We are currently developing and tracking this list through Bugzilla enhancements." [David Twelves]

David Twelves

 

DBWS Features

Feature

Design documents, examples, any other source material

Subject Matter Expert

Writer

Parse DDL to extract database metadata: Change the way type metadata is accessed by DBWSBuilder, providing support for the following enhancement requests:

  • DBWSProvider does not handle weakly-typed REF CURSORs (bug 325124)
  •  DBWSProvider does not handle strongly-typed REF CURSORs (bug 339721)
  • DBWSProvider does not handle optional arguments for Stored Procedures (bug 234385)
  • DBWS does not handle  %ROWTYPE mix of PL/SQL types and JDBC Advanced types bug 329435

<a href="http://wiki.eclipse.org/EclipseLink/Development/DBWS/ParseDDLforMetadata">Parsing DDL for Metadata Design Spec</a>

Mike Norman, David Twelves

Rick Sapir

RESTful JPA: Provide a JAX-RS solution for easily making a JPA persistence unit available through REST calls.

(<a href="http://wiki.eclipse.org/EclipseLink/Development/2.4.0">EclipseLink 2.4.0 Development Plans</a> page says "BWS Generation of JAX-RS Web Services."

Not yet available.

"Planned for later in 2.4 dev cycle." [David Twelves]

David Twelves

Rick Sapir

 

Printable Versions

We plan to provide a printable version of the EclipseLink wiki topics. When a new version of EclipseLink is released (and all documentation issues are wrapped up), we will  generate a PDF version (and, if possible an HTML version) of the wiki topics and post that as the official documentation for a certain release. Updates may continue to be made on the wiki, but the PDF/HTML will not be regenerated until the next release.

Details about how to accomplish this are not yet resolved.

Scheduling and Reviews

Schedules must include time for:

  • Documentation reviews by Dev/QA. Reviews will be conducted on the wiki.
  • A final production review of the wiki including, but not limited to:
    • Links to samples
    • Links to Javadoc
    • Cross-references
    • Style consistency

All writers will contribute to the production review.

Bugs

All writers must have BugZilla accounts and review and handle documentation bugs against their EclipseLink topics.

If a writer is responsible for a feature that has no corresponding design documentation or if the design documentation does not contain enough information (missing details, code snippets, release, etc.), the writer should file a BugZilla bug against Development. (Use your judgment: often a phone call or e-mail can clear up a problem.)

Assignments

Joe Garcia

Manager

Donna Micozzi

Manager

 

Ben Gelernter

Lead, JPA topics

Ed Spear

JPA topics (TBD)

Rick Sapir

MOXy

DBWS

</t