harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r396564 - in /incubator/harmony/standard/site: docs/subcomponents/classlibrary/ xdocs/subcomponents/classlibrary/
Date Mon, 24 Apr 2006 14:24:40 GMT
Author: tellison
Date: Mon Apr 24 07:24:35 2006
New Revision: 396564

URL: http://svn.apache.org/viewcvs?rev=396564&view=rev
Log:
Introduce proposed compatibility guidelines.
Remove proposed flag from package naming guidelines.

Added:
    incubator/harmony/standard/site/docs/subcomponents/classlibrary/compat.html   (with props)
    incubator/harmony/standard/site/xdocs/subcomponents/classlibrary/compat.xml   (with props)
Modified:
    incubator/harmony/standard/site/docs/subcomponents/classlibrary/index.html
    incubator/harmony/standard/site/docs/subcomponents/classlibrary/pkgnaming.html
    incubator/harmony/standard/site/xdocs/subcomponents/classlibrary/index.xml
    incubator/harmony/standard/site/xdocs/subcomponents/classlibrary/pkgnaming.xml

Added: incubator/harmony/standard/site/docs/subcomponents/classlibrary/compat.html
URL: http://svn.apache.org/viewcvs/incubator/harmony/standard/site/docs/subcomponents/classlibrary/compat.html?rev=396564&view=auto
==============================================================================
--- incubator/harmony/standard/site/docs/subcomponents/classlibrary/compat.html (added)
+++ incubator/harmony/standard/site/docs/subcomponents/classlibrary/compat.html Mon Apr 24
07:24:35 2006
@@ -0,0 +1,410 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+
+<!--
+Copyright 1999-2004 The Apache Software Foundation
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+
+<!-- Content Stylesheet for Site -->
+
+        
+<!-- start the processing -->
+    <!-- ====================================================================== -->
+    <!-- GENERATED FILE, DO NOT EDIT, EDIT THE XML FILE IN xdocs INSTEAD! -->
+    <!-- Main Page Section -->
+    <!-- ====================================================================== -->
+    <html>
+        <head>
+            <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/>
+
+                                                    <meta name="author" value="Harmony
Documentation Team">
+            <meta name="email" value="harmony-dev@incubator.apache.org">
+            
+           
+            
+            
+            
+            
+            
+            <title>Apache Harmony - Compatibility goals in the Apache Harmony Classlib</title>
+        </head>
+
+        <body bgcolor="#ffffff" text="#000000" link="#525D76">        
+            <table border="0" width="100%" cellspacing="0">
+                <!-- TOP IMAGE -->
+                <tr>
+                    <td align='LEFT'>
+                    <table><tr><td>
+                    <td align="left">
+<a href="http://incubator.apache.org/harmony/"><img  src="../../images/harmony-logo.png"
alt="Apache Harmony" border="0"/></a>
+</td>
+</td>
+                    </td></tr></table>
+                    </td>
+                    <td align='RIGHT'>
+                    <a href="http://incubator.apache.org/harmony/">
+                    <img src="http://incubator.apache.org/harmony/images/apache-incubator-logo.png"
+                    	alt="Apache Harmony" border="0"/></a>                    
+                    </td>
+                </tr>
+            </table>
+            <table border="0" width="100%" cellspacing="4">
+                <tr><td colspan="2">
+                    <hr noshade="" size="1"/>
+                </td></tr>
+
+                <tr>
+                    <!-- LEFT SIDE NAVIGATION -->
+                    <td width="20%" valign="top" nowrap="true">
+
+                    <!-- special ACon Logo - leave here for next time 
+                    <a href="http://apachecon.com/2005/US/">
+                        <img src="http://apache.org/images/ac2005us_blue_125x125.jpg"
height="125"
+                             width="125" border="0" alt="ApacheCon US 2005" />
+                    </a>
+                    -->
+
+                   <!-- regular menu -->
+
+                    
+    <!-- ============================================================ -->
+
+                <p><strong>General</strong></p>
+        <ul>
+                    <li>    <a href="../../index.html">Home</a>
+</li>
+            
+            <table>
+                        </table>
+                    <li>    <a href="../../license.html">License</a>
+</li>
+            
+            <table>
+                        </table>
+                    <li>    <a href="../../contribution_policy.html">Contribution
Policy</a>
+</li>
+            
+            <table>
+                        </table>
+                    <li>    <a href="../../guidelines.html">Project Guidelines</a>
+</li>
+            
+            <table>
+                        </table>
+                    <li>    <a href="http://www.apache.org/">ASF</a>
+</li>
+            
+            <table>
+                        </table>
+                    <li>    <a href="../../downloads.html">Downloads</a>
+</li>
+            
+            <table>
+                        </table>
+                </ul>
+            <p><strong>Community</strong></p>
+        <ul>
+                    <li>    <a href="../../get-involved.html">Get Involved</a>
+</li>
+            
+            <table>
+                        </table>
+                    <li>    <a href="../../contributors.html">Committers</a>
+</li>
+            
+            <table>
+                        </table>
+                    <li>    <a href="../../mailing.html">Mailing Lists</a>
+</li>
+            
+            <table>
+                        </table>
+                    <li>    <a href="../../documentation/documentation.html">Documentation</a>
+</li>
+            
+            <table>
+                        </table>
+                    <li>    <a href="../../faq.html">FAQ</a>
+</li>
+            
+            <table>
+                        </table>
+                    <li>    <a href="http://wiki.apache.org/harmony">Wiki</a>
+</li>
+            
+            <table>
+                        </table>
+                </ul>
+            <p><strong>Development</strong></p>
+        <ul>
+                    <li>    <a href="../../status.html">How Are We Doing?</a>
+</li>
+            
+            <table>
+                        </table>
+                    <li>    <a href="../../roadmap.html">Road Map / TODO</a>
+</li>
+            
+            <table>
+                        </table>
+                    <li>    <a href="../../svn.html">Source Code</a>
+</li>
+            
+            <table>
+                        </table>
+                    <li>    <a href="http://issues.apache.org/jira/browse/HARMONY">JIRA</a>
+</li>
+            
+            <table>
+                        </table>
+                    <li>    <a href="../../related.html">Other Projects</a>
+</li>
+            
+            <table>
+                        </table>
+                </ul>
+            <p><strong>Subcomponents</strong></p>
+        <ul>
+                    <li>    <a href="../../subcomponents/classlibrary/index.html">Class
Library</a>
+</li>
+            
+            <table>
+                          <tr><td>
+                &nbsp;&nbsp;    <a href="../../subcomponents/classlibrary/status.html">Status</a>
+              </td></tr>
+                        </table>
+                    <li>    <a href="../../subcomponents/jchevm/index.html">Virtual
Machine JCHEVM</a>
+</li>
+            
+            <table>
+                        </table>
+                </ul>
+                        </td>
+                    <td width="80%" align="left" valign="top">
+                                                                    <table border="0"
cellspacing="0" cellpadding="2" width="100%">
+      <tr><td bgcolor="#525D76">
+        <font color="#ffffff" face="arial,helvetica,sanserif">
+          <a name="Compatibility goals in the Apache Harmony Class Library"><strong>Compatibility
goals in the Apache Harmony Class Library</strong></a>
+        </font>
+      </td></tr>
+      <tr><td>
+        <blockquote>
+                                    <p>
+		<big><em>The following guidelines are currently PROPOSED and being discussed
on the
+		development mailing list <code>harmony-dev@incubator.apache.org</code>.  Please
+		direct comments and questions there.</em></big>
+	</p>
+                                                <p>
+		The Harmony project class library ("<b>classlib</b>") effort is committed
+		to producing a set of class library code that not only Java compliant but is also
+		compatible with existing Java implementations.
+		This page describes the class library code guidelines for ensuring that compatibility.
+	</p>
+                                                    <table border="0" cellspacing="0"
cellpadding="2" width="100%">
+      <tr><td bgcolor="#828DA6">
+        <font color="#ffffff" face="arial,helvetica,sanserif">
+          <a name="The "Reference Implementation""><strong>The "Reference Implementation"</strong></a>
+        </font>
+      </td></tr>
+      <tr><td>
+        <blockquote>
+                                    <a name="referenceImpl" />
+                                                <p>
+		The Harmony project
+		'<a href="http://incubator.apache.org/harmony/subcomponents/classlibrary">classlib</a>'
+		effort is producing a set of class library code that is compatible with
+		<a href="http://java.sun.com/j2se/1.5.0/docs/api/index.html">the Java SE 5.0 API
+		specification</a>.
+	</p>
+                                                <p>
+		At times (discussed below) it is necessary to augment the specification based on the
+		behavior of the reference implementation (RI) of the Java SE 5.0 specification.  In
+		such cases we use <a href="http://java.sun.com/j2se/1.5.0/download.jsp">the latest
+		official release of the Java SE 5.0 RI</a>.
+	</p>
+                                                <p>
+		We are aware that there are other compliant implementations of Java 5.0 available
+		but there is only one reference implementation of the Java specification.
+	</p>
+                            </blockquote>
+      </td></tr>
+      <tr><td><br/></td></tr>
+    </table>
+                                                    <table border="0" cellspacing="0"
cellpadding="2" width="100%">
+      <tr><td bgcolor="#828DA6">
+        <font color="#ffffff" face="arial,helvetica,sanserif">
+          <a name="General Compatibility Guidelines"><strong>General Compatibility
Guidelines</strong></a>
+        </font>
+      </td></tr>
+      <tr><td>
+        <blockquote>
+                                    <p>
+		The following general guidelines apply when developing class library code for Apache
+		Harmony:
+		<ul>
+			<li><b>Comply with the Java Specification</b>
+			<p>
+				In the first instance we follow the description of each part of the class
+				library given in the <a href="#referenceImpl">Java specification</a>.  To
+				the large part, this adequately describes the behavior of the class library
+				implementation including methods, exceptions, and serialization.  However,
+				where the specification is silent on a particular issue facing the implementor,
+				or the described behavior is clearly illogical, then we follow the behavior
+				of the reference implementation.
+			</p></li>
+			<li><b>Follow the Reference Implementation</b>
+			<p>
+				The Reference Implementation (RI) is used to resolve issues that are not
+				adequately addressed in the specification.  In such cases we use the RI as a
+				guide to the compliant and expected behavior; however, developers <em>must</em>
+				ensure that the behaviour of the RI is determined soley through exercising the
+				public Java APIs -- specifically we avoid any notion of reverse engineering or
+				exposition of the RI's implementation by exercising non-API types and methods.
+				</p>
+				<p>
+				There are a few occasions where both the specification is quiet on a given
+				issue, and the RI exhibits behaviour that we would consider illogical.  In such
+				cases we discuss the issue on
+				<a href="http://incubator.apache.org/harmony/mailing.html">the Harmony developers'
+				mailing list</a>, and code the class libraries to do what the development community
+				conclude is "the logical thing".
+			</p></li>
+			<li><b>Do "the Logical Thing"</b>
+			<p>
+				The final decision about how a piece of code should behave, on those rare occasions
+				where the specification and RI do not provide a satisfactory answer, is reached
+				by concensus on the Harmony developers' mailing list.  Each issue is debated based
+				on it's individual circumstances, but the developers are aware that breaking popular
+				applications is invariably not "the logical thing" to do.
+				<p>
+				</p>
+				Once a decision has been made it is documented in the code comments and an issue
+				raised in <a href="http://issues.apache.org/jira/browse/HARMONY">the Harmony JIRA
issue
+				tracking system</a> to record the conclusion.  It should be noted that very few
issues
+				need to be resolved this way.
+			</p></li>
+		</ul>
+	</p>
+                            </blockquote>
+      </td></tr>
+      <tr><td><br/></td></tr>
+    </table>
+                                                    <table border="0" cellspacing="0"
cellpadding="2" width="100%">
+      <tr><td bgcolor="#828DA6">
+        <font color="#ffffff" face="arial,helvetica,sanserif">
+          <a name="Exception-throwing compatibility"><strong>Exception-throwing
compatibility</strong></a>
+        </font>
+      </td></tr>
+      <tr><td>
+        <blockquote>
+                                    <p>
+		There are a number of methods in the Java specification that describe the conditions under
+		which exceptions are thrown.  However, in most cases the specification does not describe
all possible
+		exceptions that may be thrown, the order of exception throwing (i.e. where there are multiple
+		conditions that would result in an exception), and so on.
+	</p>
+                                                <p>
+		The Harmony class libary code aims to be fully compatible with the Reference Implementation
(RI)
+		of the Java Specification by matching the exception characteristics of each method.
+	</p>
+                                                <p>
+		Harmony
+		<b>classlib</b> developers write test cases that deliberately cause exceptions
to be thrown
+		so that we can match exception behaviour like-for-like.  Harmony class library code should
+		throw exceptions of the same type as the RI, other than in cases where the RI throws non-public
+		types whereupon Harmony will throw an exception with the same public supertype.
+	</p>
+                            </blockquote>
+      </td></tr>
+      <tr><td><br/></td></tr>
+    </table>
+                                                    <table border="0" cellspacing="0"
cellpadding="2" width="100%">
+      <tr><td bgcolor="#828DA6">
+        <font color="#ffffff" face="arial,helvetica,sanserif">
+          <a name="Serialization compatibility"><strong>Serialization compatibility</strong></a>
+        </font>
+      </td></tr>
+      <tr><td>
+        <blockquote>
+                                    <p>
+		The Harmony class library code aims to be serialization compatible with the reference
+		implementation (RI).
+	</p>
+                                                <p>
+		The Java Specification describes the serialized form of many Java types.  Where given,
<b>classlib</b> will follow
+		the specified serialized form.  When the serialized form is <u>not</u> given
we will ensure that the
+		serialization data is compatible with the RI by ensuring that objects serialized from the
RI
+		can be read by Harmony's <b>classlib</b> code, and vice versa.
+	</p>
+                                                <p>
+		Serialization tests are part
+		of our regular test suite and typically rely on having the persistent form of serialized
objects
+		written from the RI stored alongside our test suite code.
+	</p>
+                                                <p>
+		To indicate that we are serialization-compatible we define an explicit Stream Unique Identifier
+		(SUID) in each of the Harmony <b>classlib</b> serializable types that is equal
to the SUID of
+		the corresponding type in the RI.
+	</p>
+                                                <p>
+		Where the RI produces a serialized form that cannot be replicated by Harmony (e.g. the
RI serialized
+		form includes types that are not part of the Java specification) then Harmony cannot be
+		serialization compatible with the RI, and will both make a prominent note of such in the
relevant
+		type's JavaDoc comment, and raise a JIRA issue that describes the incompatibility.
+	</p>
+                            </blockquote>
+      </td></tr>
+      <tr><td><br/></td></tr>
+    </table>
+                            </blockquote>
+        </p>
+      </td></tr>
+      <tr><td><br/></td></tr>
+    </table>
+                                        </td>
+                </tr>
+
+                <!-- FOOTER -->
+                <tr><td colspan="2">
+                    <hr noshade="" size="1"/>
+                </td></tr>
+                <tr><td colspan="2">
+                    <div align="center"><font color="#525D76" size="-1"><em>
+                    Copyright &#169; 2003-2006, The Apache Software Foundation
+                    </em></font></div>
+                </td></tr>
+            </table>
+        </body>
+    </html>
+<!-- end the processing -->
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

Propchange: incubator/harmony/standard/site/docs/subcomponents/classlibrary/compat.html
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: incubator/harmony/standard/site/docs/subcomponents/classlibrary/index.html
URL: http://svn.apache.org/viewcvs/incubator/harmony/standard/site/docs/subcomponents/classlibrary/index.html?rev=396564&r1=396563&r2=396564&view=diff
==============================================================================
--- incubator/harmony/standard/site/docs/subcomponents/classlibrary/index.html (original)
+++ incubator/harmony/standard/site/docs/subcomponents/classlibrary/index.html Mon Apr 24
07:24:35 2006
@@ -230,7 +230,7 @@
                                                     <table border="0" cellspacing="0"
cellpadding="2" width="100%">
       <tr><td bgcolor="#828DA6">
         <font color="#ffffff" face="arial,helvetica,sanserif">
-          <a name="Project conventions"><strong>Project conventions</strong></a>
+          <a name="Project Conventions"><strong>Project Conventions</strong></a>
         </font>
       </td></tr>
       <tr><td>
@@ -238,7 +238,13 @@
                                     <ul>
 		<li><a href="pkgnaming.html">Java package naming guidelines</a>
 			<p>
-				<b>Proposed</b> guidelines for package naming convention.
+				Guidelines for Harmony package naming convention.
+			</p>
+			</li>
+		<li><a href="compat.html">Compatibility guidelines</a>
+			<p>
+				<b>Proposed</b> guidelines for ensuring that the Harmony class library is
compatible
+				with other Java implementations.
 			</p>
 			</li>
 	</ul>

Modified: incubator/harmony/standard/site/docs/subcomponents/classlibrary/pkgnaming.html
URL: http://svn.apache.org/viewcvs/incubator/harmony/standard/site/docs/subcomponents/classlibrary/pkgnaming.html?rev=396564&r1=396563&r2=396564&view=diff
==============================================================================
--- incubator/harmony/standard/site/docs/subcomponents/classlibrary/pkgnaming.html (original)
+++ incubator/harmony/standard/site/docs/subcomponents/classlibrary/pkgnaming.html Mon Apr
24 07:24:35 2006
@@ -206,11 +206,6 @@
 		documentation.</em></small>
 	</p>
                                                 <p>
-		<big><em>The following guidelines are currently PROPOSED and being discussed
on the
-		development mailing list <code>harmony-dev@incubator.apache.org</code>.  Please
-		direct comments and questions there.</em></big>
-	</p>
-                                                <p>
 		The Harmony class library code is organized into Java packages comprising the
 		public API (packages such as <code>java.lang</code>, <code>org.omg.CORBA</code>
 		and so on) and internal implementation packages that all begin

Added: incubator/harmony/standard/site/xdocs/subcomponents/classlibrary/compat.xml
URL: http://svn.apache.org/viewcvs/incubator/harmony/standard/site/xdocs/subcomponents/classlibrary/compat.xml?rev=396564&view=auto
==============================================================================
--- incubator/harmony/standard/site/xdocs/subcomponents/classlibrary/compat.xml (added)
+++ incubator/harmony/standard/site/xdocs/subcomponents/classlibrary/compat.xml Mon Apr 24
07:24:35 2006
@@ -0,0 +1,164 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+
+    Copyright 2006 The Apache Software Foundation
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+
+<document>
+
+ <properties>
+  <title>Compatibility goals in the Apache Harmony Classlib</title>
+  <author email="harmony-dev@incubator.apache.org">Harmony Documentation Team</author>
+ </properties>
+
+<body>
+
+<section name="Compatibility goals in the Apache Harmony Class Library">
+	<p>
+		<big><em>The following guidelines are currently PROPOSED and being discussed
on the
+		development mailing list <code>harmony-dev@incubator.apache.org</code>.  Please
+		direct comments and questions there.</em></big>
+	</p>
+	<p>
+		The Harmony project class library (&quot;<b>classlib</b>&quot;) effort
is committed
+		to producing a set of class library code that not only Java compliant but is also
+		compatible with existing Java implementations.
+		This page describes the class library code guidelines for ensuring that compatibility.
+	</p>
+
+<subsection name="The &quot;Reference Implementation&quot;">
+<a name="referenceImpl"/>
+	<p>
+		The Harmony project
+		'<a href="http://incubator.apache.org/harmony/subcomponents/classlibrary">classlib</a>'
+		effort is producing a set of class library code that is compatible with
+		<a href="http://java.sun.com/j2se/1.5.0/docs/api/index.html">the Java SE 5.0 API
+		specification</a>.
+	</p>
+	<p>
+		At times (discussed below) it is necessary to augment the specification based on the
+		behavior of the reference implementation (RI) of the Java SE 5.0 specification.  In
+		such cases we use <a href="http://java.sun.com/j2se/1.5.0/download.jsp">the latest
+		official release of the Java SE 5.0 RI</a>.
+	</p>
+	<p>
+		We are aware that there are other compliant implementations of Java 5.0 available
+		but there is only one reference implementation of the Java specification.
+	</p>
+</subsection>
+
+<subsection name="General Compatibility Guidelines">
+	<p>
+		The following general guidelines apply when developing class library code for Apache
+		Harmony:
+		<ul>
+			<li><b>Comply with the Java Specification</b>
+			<p>
+				In the first instance we follow the description of each part of the class
+				library given in the <a href="#referenceImpl">Java specification</a>.  To
+				the large part, this adequately describes the behavior of the class library
+				implementation including methods, exceptions, and serialization.  However,
+				where the specification is silent on a particular issue facing the implementor,
+				or the described behavior is clearly illogical, then we follow the behavior
+				of the reference implementation.
+			</p></li>
+			<li><b>Follow the Reference Implementation</b>
+			<p>
+				The Reference Implementation (RI) is used to resolve issues that are not
+				adequately addressed in the specification.  In such cases we use the RI as a
+				guide to the compliant and expected behavior; however, developers <em>must</em>
+				ensure that the behaviour of the RI is determined soley through exercising the
+				public Java APIs -- specifically we avoid any notion of reverse engineering or
+				exposition of the RI's implementation by exercising non-API types and methods.
+				</p>
+				<p>
+				There are a few occasions where both the specification is quiet on a given
+				issue, and the RI exhibits behaviour that we would consider illogical.  In such
+				cases we discuss the issue on
+				<a href="http://incubator.apache.org/harmony/mailing.html">the Harmony developers'
+				mailing list</a>, and code the class libraries to do what the development community
+				conclude is &quot;the logical thing&quot;.
+			</p></li>
+			<li><b>Do &quot;the Logical Thing&quot;</b>
+			<p>
+				The final decision about how a piece of code should behave, on those rare occasions
+				where the specification and RI do not provide a satisfactory answer, is reached
+				by concensus on the Harmony developers' mailing list.  Each issue is debated based
+				on it's individual circumstances, but the developers are aware that breaking popular
+				applications is invariably not &quot;the logical thing&quot; to do.
+				<p>
+				</p>
+				Once a decision has been made it is documented in the code comments and an issue
+				raised in <a href="http://issues.apache.org/jira/browse/HARMONY">the Harmony JIRA
issue
+				tracking system</a> to record the conclusion.  It should be noted that very few
issues
+				need to be resolved this way.
+			</p></li>
+		</ul>
+	</p>
+</subsection>
+
+<subsection name="Exception-throwing compatibility">
+	<p>
+		There are a number of methods in the Java specification that describe the conditions under
+		which exceptions are thrown.  However, in most cases the specification does not describe
all possible
+		exceptions that may be thrown, the order of exception throwing (i.e. where there are multiple
+		conditions that would result in an exception), and so on.
+	</p>
+	<p>
+		The Harmony class libary code aims to be fully compatible with the Reference Implementation
(RI)
+		of the Java Specification by matching the exception characteristics of each method.
+	</p>
+	<p>
+		Harmony
+		<b>classlib</b> developers write test cases that deliberately cause exceptions
to be thrown
+		so that we can match exception behaviour like-for-like.  Harmony class library code should
+		throw exceptions of the same type as the RI, other than in cases where the RI throws non-public
+		types whereupon Harmony will throw an exception with the same public supertype.
+	</p>
+</subsection>
+
+<subsection name="Serialization compatibility">
+	<p>
+		The Harmony class library code aims to be serialization compatible with the reference
+		implementation (RI).
+	</p>
+	<p>
+		The Java Specification describes the serialized form of many Java types.  Where given,
<b>classlib</b> will follow
+		the specified serialized form.  When the serialized form is <u>not</u> given
we will ensure that the
+		serialization data is compatible with the RI by ensuring that objects serialized from the
RI
+		can be read by Harmony's <b>classlib</b> code, and vice versa.
+	</p>
+	<p>
+		Serialization tests are part
+		of our regular test suite and typically rely on having the persistent form of serialized
objects
+		written from the RI stored alongside our test suite code.
+	</p>
+	<p>
+		To indicate that we are serialization-compatible we define an explicit Stream Unique Identifier
+		(SUID) in each of the Harmony <b>classlib</b> serializable types that is equal
to the SUID of
+		the corresponding type in the RI.
+	</p>
+	<p>
+		Where the RI produces a serialized form that cannot be replicated by Harmony (e.g. the
RI serialized
+		form includes types that are not part of the Java specification) then Harmony cannot be
+		serialization compatible with the RI, and will both make a prominent note of such in the
relevant
+		type's JavaDoc comment, and raise a JIRA issue that describes the incompatibility.
+	</p>
+</subsection>
+
+</section>
+</body>
+</document>
\ No newline at end of file

Propchange: incubator/harmony/standard/site/xdocs/subcomponents/classlibrary/compat.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: incubator/harmony/standard/site/xdocs/subcomponents/classlibrary/index.xml
URL: http://svn.apache.org/viewcvs/incubator/harmony/standard/site/xdocs/subcomponents/classlibrary/index.xml?rev=396564&r1=396563&r2=396564&view=diff
==============================================================================
--- incubator/harmony/standard/site/xdocs/subcomponents/classlibrary/index.xml (original)
+++ incubator/harmony/standard/site/xdocs/subcomponents/classlibrary/index.xml Mon Apr 24
07:24:35 2006
@@ -46,11 +46,17 @@
 	</ul>
 </subsection>
 
-<subsection name="Project conventions">
+<subsection name="Project Conventions">
 	<ul>
 		<li><a href="pkgnaming.html">Java package naming guidelines</a>
 			<p>
-				<b>Proposed</b> guidelines for package naming convention.
+				Guidelines for Harmony package naming convention.
+			</p>
+			</li>
+		<li><a href="compat.html">Compatibility guidelines</a>
+			<p>
+				<b>Proposed</b> guidelines for ensuring that the Harmony class library is
compatible
+				with other Java implementations.
 			</p>
 			</li>
 	</ul>

Modified: incubator/harmony/standard/site/xdocs/subcomponents/classlibrary/pkgnaming.xml
URL: http://svn.apache.org/viewcvs/incubator/harmony/standard/site/xdocs/subcomponents/classlibrary/pkgnaming.xml?rev=396564&r1=396563&r2=396564&view=diff
==============================================================================
--- incubator/harmony/standard/site/xdocs/subcomponents/classlibrary/pkgnaming.xml (original)
+++ incubator/harmony/standard/site/xdocs/subcomponents/classlibrary/pkgnaming.xml Mon Apr
24 07:24:35 2006
@@ -33,11 +33,6 @@
 		documentation.</em></small>
 	</p>
 	<p>
-		<big><em>The following guidelines are currently PROPOSED and being discussed
on the
-		development mailing list <code>harmony-dev@incubator.apache.org</code>.  Please
-		direct comments and questions there.</em></big>
-	</p>
-	<p>
 		The Harmony class library code is organized into Java packages comprising the
 		public API (packages such as <code>java.lang</code>, <code>org.omg.CORBA</code>
 		and so on) and internal implementation packages that all begin



Mime
View raw message