harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From nadi...@apache.org
Subject svn commit: r518091 [4/6] - in /harmony/standard/site: docs/ docs/subcomponents/classlibrary/ docs/subcomponents/drlvm/ xdocs/
Date Wed, 14 Mar 2007 10:37:57 GMT
Modified: harmony/standard/site/docs/subcomponents/classlibrary/compat.html
URL: http://svn.apache.org/viewvc/harmony/standard/site/docs/subcomponents/classlibrary/compat.html?view=diff&rev=518091&r1=518090&r2=518091
==============================================================================
--- harmony/standard/site/docs/subcomponents/classlibrary/compat.html (original)
+++ harmony/standard/site/docs/subcomponents/classlibrary/compat.html Wed Mar 14 03:37:45 2007
@@ -192,16 +192,20 @@
       <a name="Compatibility goals in the Apache Harmony Class Library">Compatibility goals in the Apache Harmony Class Library</a>
     </h1>
                         <p>
-		<big><em>The following guidelines are currently PROPOSED and being discussed on the
-		development mailing list <code>dev@harmony.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>
+                <big>
+                    <em>
+                        The following guidelines are currently PROPOSED and being discussed on the
+                        development mailing list <code>dev@harmony.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>
                                     
     <h2>
         <a name="The "Reference Implementation"">The "Reference Implementation"</a>
@@ -209,22 +213,26 @@
       
                         <a name="referenceImpl" />
                                 <p>
-		The Harmony project
-		'<a href="http://harmony.apache.org/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>
+                    The Harmony project
+                    '<a href="http://harmony.apache.org/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>
                    
                                     
     <h2>
@@ -232,52 +240,62 @@
     </h2>
       
                         <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="../../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>
+                    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="../../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>
                    
                                     
     <h2>
@@ -285,65 +303,72 @@
     </h2>
       
                         <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 throws exceptions 
-		of the same runtime class (or a subtype of that runtime class) 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>
-                                <p>
-		Generally, we could refer to the following steps.
-	<ul>
-		<li><b>If RI is compliant with the Java Specification</b>
-		<p>
-		We shall follow RI's behavior, that is, throws exactly the same exception or a subclass of the exception.
-		<ul>
-			<li>But there are some cases that RI throws an implementation specific exception, 
-			which is not in the Java Specification, we shall throw an equivalent Harmony specific exception, 
-			or its superclass in the Java Specification.
-			<p><i>
-			e.g., If RI throws sun.io.MalformedInputException, 
-			we could throw org.apache.harmony.io.MalformedInputException or java.io.CharConversionException.
-			</i></p>
-			</li>
-		</ul>
-		</p>
-		</li>
-		<li><b>If RI is not compliant with the Java Specification</b>
-		<p>
-		<ul>
-		<li>If the Java Specification describes the exceptional situation explicitly, 
-		and RI throws different kind of exception or even does not throw any exception, 
-		we shall discuss them case by case in harmony-dev mailing list.
-			<ul>
-				<li>If we decide to follow RI, we will raise an "Non-bug differences from Spec" JIRA.</li>
-				<li>If we decide to follow the Java Specification, we will raise an "Non-bug differences from RI" JIRA.</li>
-			</ul>
-		</li>
-		<li>If the Java Specification does NOT describe the exceptional situation explicitly, 
-		and RI's behavior is either hard to reproduce or illogical, we shall discuss them case by case.
-		And we may decide to:
-			<ul>
-				<li>Follow RI</li>
-				<li>Follow the Java Specification</li>
-				<li>Implement the functions in our own way</li>
-			</ul>
-		</li>
-		</ul>
-		</p>
-		</li>
-	</ul>
-	</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 throws exceptions
+                    of the same runtime class (or a subtype of that runtime class) 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>
+                                <p>
+                    Generally, we could refer to the following steps.
+                    <ul>
+                        <li>
+                            <b>If RI is compliant with the Java Specification</b>
+                            <p>
+                                We shall follow RI's behavior, that is, throws exactly the same exception or a subclass of the exception.
+                                <ul>
+                                    <li>
+                                        But there are some cases that RI throws an implementation specific exception,
+                                        which is not in the Java Specification, we shall throw an equivalent Harmony specific exception,
+                                        or its superclass in the Java Specification.
+                                        <p>
+                                            <i>
+                                                e.g., If RI throws sun.io.MalformedInputException,
+                                                we could throw org.apache.harmony.io.MalformedInputException or java.io.CharConversionException.
+                                            </i>
+                                        </p>
+                                    </li>
+                                </ul>
+                            </p>
+                        </li>
+                        <li>
+                            <b>If RI is not compliant with the Java Specification</b>
+                            <p>
+                                <ul>
+                                    <li>
+                                        If the Java Specification describes the exceptional situation explicitly,
+                                        and RI throws different kind of exception or even does not throw any exception,
+                                        we shall discuss them case by case in harmony-dev mailing list.
+                                        <ul>
+                                            <li>If we decide to follow RI, we will raise an "Non-bug differences from Spec" JIRA.</li>
+                                            <li>If we decide to follow the Java Specification, we will raise an "Non-bug differences from RI" JIRA.</li>
+                                        </ul>
+                                    </li>
+                                    <li>
+                                        If the Java Specification does NOT describe the exceptional situation explicitly,
+                                        and RI's behavior is either hard to reproduce or illogical, we shall discuss them case by case.
+                                        And we may decide to:
+                                        <ul>
+                                            <li>Follow RI</li>
+                                            <li>Follow the Java Specification</li>
+                                            <li>Implement the functions in our own way</li>
+                                        </ul>
+                                    </li>
+                                </ul>
+                            </p>
+                        </li>
+                    </ul>
+                </p>
                    
                                     
     <h2>
@@ -351,31 +376,31 @@
     </h2>
       
                         <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>
+                    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>
                    
                 <p><a href="#top">Back to top</a></p>
                     

Modified: harmony/standard/site/docs/subcomponents/classlibrary/pkgnaming.html
URL: http://svn.apache.org/viewvc/harmony/standard/site/docs/subcomponents/classlibrary/pkgnaming.html?view=diff&rev=518091&r1=518090&r2=518091
==============================================================================
--- harmony/standard/site/docs/subcomponents/classlibrary/pkgnaming.html (original)
+++ harmony/standard/site/docs/subcomponents/classlibrary/pkgnaming.html Wed Mar 14 03:37:45 2007
@@ -192,39 +192,48 @@
       <a name="Package Naming Conventions Used in the Apache Harmony Class Library">Package Naming Conventions Used in the Apache Harmony Class Library</a>
     </h1>
                         <p>
-		<small><em>This section is inspired by, and derived from,
-		<a href="http://wiki.eclipse.org/index.php/Naming_Conventions">the Eclipse package naming convention</a>
-		documentation.</em></small>
-	</p>
+                <small>
+                    <em>
+                        This section is inspired by, and derived from,
+                        <a href="http://wiki.eclipse.org/index.php/Naming_Conventions">the Eclipse package naming convention</a>
+                        documentation.
+                    </em>
+                </small>
+            </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
-		<code>org.apache.harmony</code>.
-	</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
+                <code>org.apache.harmony</code>.
+            </p>
                                 <p>
-		The public APIs are defined by the JSE specification, and as such as managed beyond
-		the direct control of the Apache Harmony project. The other packages are managed
-		by the project development team, and as such the project attributes the following
-		meaning to package names.
-	</p>
+                The public APIs are defined by the JSE specification, and as such as managed beyond
+                the direct control of the Apache Harmony project. The other packages are managed
+                by the project development team, and as such the project attributes the following
+                meaning to package names.
+            </p>
                                     
     <h2>
         <a name="All Packages Belong to a Specific Module">All Packages Belong to a Specific Module</a>
     </h2>
       
                         <p>
-		Each Java package is owned by a specific module of the Harmony class library.
-		The module name immediately follows the <code>org.apache.harmony</code> prefix.</p>
-                                <pre>org.apache.harmony.<b>&lt;module&gt;</b></pre>
+                    Each Java package is owned by a specific module of the Harmony class library.
+                    The module name immediately follows the <code>org.apache.harmony</code> prefix.
+                </p>
+                                <pre>
+                    org.apache.harmony.<b>&lt;module&gt;</b>
+                </pre>
                                 <p class="example">
-      Example
-    </p>
+                    Example
+                </p>
                                 <p class="exampletext">
-			<pre>org.apache.harmony.luni
-org.apache.harmony.security</pre>
-			
-	</p>
+                    <pre>
+                        org.apache.harmony.luni
+                        org.apache.harmony.security
+                    </pre>
+
+                </p>
                    
                                     
     <h2>
@@ -232,47 +241,67 @@
     </h2>
       
                         <p>
-		Modules are free to use whatever package names they choose with the
-		prefix <code>org.apache.harmony.<b>&lt;modulename&gt;</b></code>.
-	</p>
+                    Modules are free to use whatever package names they choose with the
+                    prefix <code>
+                        org.apache.harmony.<b>&lt;modulename&gt;</b>
+                    </code>.
+                </p>
                                 <p>
-		The following package name segements are <b>reserved</b> to indicate the meanings
-		defined below:</p>
+                    The following package name segements are <b>reserved</b> to indicate the meanings
+                    defined below:
+                </p>
                                 <ul>
-			<li><code>org.apache.harmony.&lt;modulename&gt;.<b>internal</b></code>
-        <p>
-				Packages with this prefix are implementation packages for use within
-				the given module. Types and fields that are visible within these
-				packages <em>MUST NOT</em> be used outside the module itself.
-				Some runtime environments may enforce this reduced visibility scope.
-			</p></li>
-			<li><code>org.apache.harmony.&lt;modulename&gt;.<b>tests</b></code>
-			<p>
-				Packages with this prefix contain test code that is not part of the
-				module API or implementation.  Some builds may not include these
-				packages. See <a href="testing.html">Testing conventions in the Apache Harmony Classlib</a>
-                                for details.
-			</p></li>
-			<li><code>org.apache.harmony.&lt;modulename&gt;.<b>examples</b></code>
-			<p>
-				Packages with this prefix contain example code that is not part of the
-				module API or implementation. Some builds may not include these
-				packages.
-			</p></li>
-			<li><code>org.apache.harmony.&lt;modulename&gt;.<b>&lt;anything_else&gt;</b></code>
-			<p>
-				All other packages within a module contain internal APIs that may
-				be referenced from any module.
-			</p></li>
-		</ul>
+                    <li>
+                        <code>
+                            org.apache.harmony.&lt;modulename&gt;.<b>internal</b>
+                        </code>
+                        <p>
+                            Packages with this prefix are implementation packages for use within
+                            the given module. Types and fields that are visible within these
+                            packages <em>MUST NOT</em> be used outside the module itself.
+                            Some runtime environments may enforce this reduced visibility scope.
+                        </p>
+                    </li>
+                    <li>
+                        <code>
+                            org.apache.harmony.&lt;modulename&gt;.<b>tests</b>
+                        </code>
+                        <p>
+                            Packages with this prefix contain test code that is not part of the
+                            module API or implementation.  Some builds may not include these
+                            packages. See <a href="testing.html">Testing conventions in the Apache Harmony Classlib</a>
+                            for details.
+                        </p>
+                    </li>
+                    <li>
+                        <code>
+                            org.apache.harmony.&lt;modulename&gt;.<b>examples</b>
+                        </code>
+                        <p>
+                            Packages with this prefix contain example code that is not part of the
+                            module API or implementation. Some builds may not include these
+                            packages.
+                        </p>
+                    </li>
+                    <li>
+                        <code>
+                            org.apache.harmony.&lt;modulename&gt;.<b>&lt;anything_else&gt;</b>
+                        </code>
+                        <p>
+                            All other packages within a module contain internal APIs that may
+                            be referenced from any module.
+                        </p>
+                    </li>
+                </ul>
                                 <p>
-		In practice, this means that module developers are free to change the code within an
-		<code>internal</code> package without expecting any consequences beyond the module
-		itself. However, module developers who modify code that is not in an
-		<code>internal</code> package must do so in a manner that ensures
-		<a href="http://java.sun.com/docs/books/jls/second_edition/html/binaryComp.doc.html">
-		Java binary compatibility</a>.
-	</p>
+                    In practice, this means that module developers are free to change the code within an
+                    <code>internal</code> package without expecting any consequences beyond the module
+                    itself. However, module developers who modify code that is not in an
+                    <code>internal</code> package must do so in a manner that ensures
+                    <a href="http://java.sun.com/docs/books/jls/second_edition/html/binaryComp.doc.html">
+                        Java binary compatibility
+                    </a>.
+                </p>
                    
                 <p><a href="#top">Back to top</a></p>
                     

Modified: harmony/standard/site/docs/subcomponents/classlibrary/ser_testing.html
URL: http://svn.apache.org/viewvc/harmony/standard/site/docs/subcomponents/classlibrary/ser_testing.html?view=diff&rev=518091&r1=518090&r2=518091
==============================================================================
--- harmony/standard/site/docs/subcomponents/classlibrary/ser_testing.html (original)
+++ harmony/standard/site/docs/subcomponents/classlibrary/ser_testing.html Wed Mar 14 03:37:45 2007
@@ -192,101 +192,139 @@
       <a name="Framework for Testing Serialization">Framework for Testing Serialization</a>
     </h1>
                         <p>
-		<big><em>The framework for testing serialization is currently PROPOSED and being 
-		discussed on the development mailing list <code>dev@harmony.apache.org</code>.  
-		Please direct comments and questions there.</em></big>
-	</p>
-                                <p>
-		The framework for testing serialization is intended to simplify and formalize
-		development of serialization tests. This document contains guidelines for
-		creating tests and <a href="#conventions">conventions</a> for resource files.
-	</p>
+                <big>
+                    <em>
+                        The framework for testing serialization is currently PROPOSED and being
+                        discussed on the development mailing list <code>dev@harmony.apache.org</code>.
+                        Please direct comments and questions there.
+                    </em>
+                </big>
+            </p>
+                                <p>
+                The framework for testing serialization is intended to simplify and formalize
+                development of serialization tests. This document contains guidelines for
+                creating tests and <a href="#conventions">conventions</a> for resource files.
+            </p>
                                     
     <h2>
         <a name="Guidelines for Developing Serialization Tests">Guidelines for Developing Serialization Tests</a>
     </h2>
       
                         <p>
-		The testing framework provides the support class
-		<code>org.apache.harmony.testframework.serialization.SerializationTest</code>
-		for serialization testing.
-	</p>
+                    The testing framework provides the support class
+                    <code>org.apache.harmony.testframework.serialization.SerializationTest</code>
+                    for serialization testing.
+                </p>
                                 <h3>Compatibility Testing</h3>
-                                <p>Verifies that an object serialized on certified implementation is
-		correctly deserialized on Harmony implementation.<br />
-		The support class provides four methods for compatibility testing:
-		<ul><code>
-			<li>verifyGolden(TestCase, Object)</li>
-			<li>verifyGolden(TestCase, Object, <a href="#assert">SerializableAssert</a>)</li>
-			<li>verifyGolden(TestCase, Object[])</li>
-			<li>verifyGolden(TestCase, Object[], <a href="#assert">SerializableAssert</a>)</li>
-		</code></ul></p>
-                                <p>The first parameter <code>TestCase</code> is used to locate resource
-		file(s) that contains serialized object(s).<br />
-    The second parameter is an object
-		or an array of objects to be compared with object(s) deserialized from
-		resource file(s).<br />
-    The third parameter is optional.</p>
-                                <p>To create a <em>compatibility</em> test for selected class, a developer should:</p>
+                                <p>
+                    Verifies that an object serialized on certified implementation is
+                    correctly deserialized on Harmony implementation.<br />
+                    The support class provides four methods for compatibility testing:
+                    <ul>
+                        <code>
+                            <li>verifyGolden(TestCase, Object)</li>
+                            <li>
+                                verifyGolden(TestCase, Object, <a href="#assert">SerializableAssert</a>)
+                            </li>
+                            <li>verifyGolden(TestCase, Object[])</li>
+                            <li>
+                                verifyGolden(TestCase, Object[], <a href="#assert">SerializableAssert</a>)
+                            </li>
+                        </code>
+                    </ul>
+                </p>
+                                <p>
+                    The first parameter <code>TestCase</code> is used to locate resource
+                    file(s) that contains serialized object(s).<br />
+                    The second parameter is an object
+                    or an array of objects to be compared with object(s) deserialized from
+                    resource file(s).<br />
+                    The third parameter is optional.
+                </p>
+                                <p>
+                    To create a <em>compatibility</em> test for selected class, a developer should:
+                </p>
                                 <ul>
-			<li>
-			Serialize object(s) on certified implementation, store serialized
-			form(s) in resource file(s) and place it(them) according to the <a href="#conventions">
-       conventions</a> </li>
-			
-			<li>
-			Add the <code>testSerializationCompatibility</code> method to a unit test 
-			</li>
-			
-			<li>
-			Invoke one of the methods, mentioned above, with corresponding arguments
-			</li>
-		</ul>
+                    <li>
+                        Serialize object(s) on certified implementation, store serialized
+                        form(s) in resource file(s) and place it(them) according to the <a href="#conventions">
+                            conventions
+                        </a>
+                    </li>
+
+                    <li>
+                        Add the <code>testSerializationCompatibility</code> method to a unit test
+                    </li>
+
+                    <li>
+                        Invoke one of the methods, mentioned above, with corresponding arguments
+                    </li>
+                </ul>
                                 <p class="example">Example</p>
-                                <pre>		
-    public void testSerializationCompatibility()
-        throws Exception {
-
-    SerializationTest.verifyGolden(this, new SomeSerializableClass());
-}
-</pre>
+                                <pre>
+                    public void testSerializationCompatibility()
+                    throws Exception {
+
+                    SerializationTest.verifyGolden(this, new SomeSerializableClass());
+                    }
+                </pre>
                                 <h3>Self-Testing</h3>
-                                <p>Verifies that an object can be smoothly serialized and deserialized on
-		Harmony implementation.<br />
-		The support class provides four methods for self-testing:</p>
-                                <ul><code>
-			<li>verifySelf(Object)</li>
-			<li>verifySelf(Object, <a href="#assert">SerializableAssert</a>)</li>
-			<li>verifySelf(Object[])</li>
-			<li>verifySelf(Object[], <a href="#assert">SerializableAssert</a>)</li>
-		</code></ul>
-                                <p>The provided object(s) is(are) serialized/deserialized and compared with
-		initial object(s).</p>
-                                <p>To create a <em>self</em> test for a selected class, a developer should:</p>
+                                <p>
+                    Verifies that an object can be smoothly serialized and deserialized on
+                    Harmony implementation.<br />
+                    The support class provides four methods for self-testing:
+                </p>
                                 <ul>
-			<li>
-			Add the <code>testSerializationSelf</code> method to a unit test
-			</li>
-			
-			<li>
-			Invoke one of the methods with corresponding arguments
-			</li>
-		</ul>
+                    <code>
+                        <li>verifySelf(Object)</li>
+                        <li>
+                            verifySelf(Object, <a href="#assert">SerializableAssert</a>)
+                        </li>
+                        <li>verifySelf(Object[])</li>
+                        <li>
+                            verifySelf(Object[], <a href="#assert">SerializableAssert</a>)
+                        </li>
+                    </code>
+                </ul>
+                                <p>
+                    The provided object(s) is(are) serialized/deserialized and compared with
+                    initial object(s).
+                </p>
+                                <p>
+                    To create a <em>self</em> test for a selected class, a developer should:
+                </p>
+                                <ul>
+                    <li>
+                        Add the <code>testSerializationSelf</code> method to a unit test
+                    </li>
+
+                    <li>
+                        Invoke one of the methods with corresponding arguments
+                    </li>
+                </ul>
                                 <p class="example">Example</p>
-                                <pre>  
-     public void testSerializationSelf() throws Exception {
+                                <pre>
+                    public void testSerializationSelf() throws Exception {
 
-     SerializationTest.verifySelf(new SomeSerializableClass(),
-     new MyComparator());
-}
-</pre>
+                    SerializationTest.verifySelf(new SomeSerializableClass(),
+                    new MyComparator());
+                    }
+                </pre>
                                 <h3>Negative Testing</h3>
-                                <big><em>TBD</em></big>
-                                <p class="class">Interface <a name="assert"><code>SerializableAssert</code></a></p>
-                                <p> If a class of object(s) to be compared does not have 
-    equals(Object) method or the testing framework can not find appropriate comparator, a 
-    test has to implement the interface. The interface has only
-		one method to be implemented:</p>
+                                <big>
+                    <em>TBD</em>
+                </big>
+                                <p class="class">
+                    Interface <a name="assert">
+                        <code>SerializableAssert</code>
+                    </a>
+                </p>
+                                <p>
+                    If a class of object(s) to be compared does not have
+                    equals(Object) method or the testing framework can not find appropriate comparator, a
+                    test has to implement the interface. The interface has only
+                    one method to be implemented:
+                </p>
                                 <pre>void assertDeserialized(Serializable reference, Serializable test);</pre>
                    
                                     
@@ -295,59 +333,72 @@
     </h2>
       
                         <p>
-		The resource files should follow the next <a name="conventions">conventions</a>:</p>
+                    The resource files should follow the next <a name="conventions">conventions</a>:
+                </p>
                                 <ul>
-			<li>Root folder for resource files is <code>&lt;module root&gt;/src/test/resources/serialization</code>
-			</li>
-			
-			<li>Relative path to a resource file <em>MUST</em> match a test's package name
-			</li>
-			
-			<li>A resource file <em>MUST</em> start with a test's name
-			</li>
-			
-			<li>A resource file <em>MUST</em> contain keywords pointing out to testing scenario
-				<ol>
-
-				<li><code>&lt;golden&gt;</code> keyword is used for files generated on RI
-				</li>
-
-				<li><code>&lt;harmony&gt;</code> keyword is used for files generated on
-				Harmony	implementation
-				</li>
-
-				<li><code>&lt;negative&gt;</code> keyword is used for files that contain
-				broken serial form
-				</li>
-
-				</ol>
-			</li>
-			
-			<li>A resource file name <em>MUST</em> contain some index
-      <p class="note">Note</p>
-        <p class="notetext">If only one file exists, the index is not required.</p>
-		 
-			</li>
-
-			<li>Extension for resource files is <code>ser</code>
-			
-  <p class="example">Example</p>
-		<p class="exampletext">For the test <code>org.apache.harmony.tests.java.lang.SomeClassTest</code>,
-      we have the following resource files:</p>
-    		<pre>
-modules/luni/src/test/resources/serialization
-     |
-     \---org/apache/harmony/tests/java/lang
-          |
-          \---SomeClassTest.golden.0.ser
-              SomeClassTest.golden.1.ser
-              SomeClassTest.golden.2.ser
-              SomeClassTest.harmony.0.ser
-              SomeClassTest.harmony.1.ser
-              SomeClassTest.negative.ser
-		</pre></li>
+                    <li>
+                        Root folder for resource files is <code>&lt;module root&gt;/src/test/resources/serialization</code>
+                    </li>
+
+                    <li>
+                        Relative path to a resource file <em>MUST</em> match a test's package name
+                    </li>
+
+                    <li>
+                        A resource file <em>MUST</em> start with a test's name
+                    </li>
+
+                    <li>
+                        A resource file <em>MUST</em> contain keywords pointing out to testing scenario
+                        <ol>
+
+                            <li>
+                                <code>&lt;golden&gt;</code> keyword is used for files generated on RI
+                            </li>
+
+                            <li>
+                                <code>&lt;harmony&gt;</code> keyword is used for files generated on
+                                Harmony	implementation
+                            </li>
+
+                            <li>
+                                <code>&lt;negative&gt;</code> keyword is used for files that contain
+                                broken serial form
+                            </li>
+
+                        </ol>
+                    </li>
+
+                    <li>
+                        A resource file name <em>MUST</em> contain some index
+                        <p class="note">Note</p>
+                        <p class="notetext">If only one file exists, the index is not required.</p>
+
+                    </li>
+
+                    <li>
+                        Extension for resource files is <code>ser</code>
+
+                        <p class="example">Example</p>
+                        <p class="exampletext">
+                            For the test <code>org.apache.harmony.tests.java.lang.SomeClassTest</code>,
+                            we have the following resource files:
+                        </p>
+                        <pre>
+                            modules/luni/src/test/resources/serialization
+                            |
+                            \---org/apache/harmony/tests/java/lang
+                            |
+                            \---SomeClassTest.golden.0.ser
+                            SomeClassTest.golden.1.ser
+                            SomeClassTest.golden.2.ser
+                            SomeClassTest.harmony.0.ser
+                            SomeClassTest.harmony.1.ser
+                            SomeClassTest.negative.ser
+                        </pre>
+                    </li>
 
-		</ul>
+                </ul>
                    
                 <p><a href="#top">Back to top</a></p>
                     

Modified: harmony/standard/site/docs/subcomponents/classlibrary/status.html
URL: http://svn.apache.org/viewvc/harmony/standard/site/docs/subcomponents/classlibrary/status.html?view=diff&rev=518091&r1=518090&r2=518091
==============================================================================
--- harmony/standard/site/docs/subcomponents/classlibrary/status.html (original)
+++ harmony/standard/site/docs/subcomponents/classlibrary/status.html Wed Mar 14 03:37:45 2007
@@ -192,14 +192,14 @@
       <a name="Class Library Component Status">Class Library Component Status</a>
     </h1>
                         <p>
-	    Stuart Ballard of the Kaffe project is generously creating automated coverage comparisons
-	    of 
-	    <a href="http://www.kaffe.org/~stuart/japi/htmlout/h-jdk14-harmony.html">JDK 1.4</a>
-	    and 
-	    <a href="http://www.kaffe.org/~stuart/japi/htmlout/h-jdk15-harmony.html">JDK 1.5</a>.
-	    against the
-	    <a href="http://people.apache.org/builds/harmony/snapshots/">Harmony class library snapshots.</a>
-	</p>
+                Stuart Ballard of the Kaffe project is generously creating automated coverage comparisons
+                of
+                <a href="http://www.kaffe.org/~stuart/japi/htmlout/h-jdk14-harmony.html">JDK 1.4</a>
+                and
+                <a href="http://www.kaffe.org/~stuart/japi/htmlout/h-jdk15-harmony.html">JDK 1.5</a>.
+                against the
+                <a href="http://people.apache.org/builds/harmony/snapshots/">Harmony class library snapshots.</a>
+            </p>
                 <p><a href="#top">Back to top</a></p>
                     
                                                             </td>

Modified: harmony/standard/site/docs/subcomponents/classlibrary/testing.html
URL: http://svn.apache.org/viewvc/harmony/standard/site/docs/subcomponents/classlibrary/testing.html?view=diff&rev=518091&r1=518090&r2=518091
==============================================================================
--- harmony/standard/site/docs/subcomponents/classlibrary/testing.html (original)
+++ harmony/standard/site/docs/subcomponents/classlibrary/testing.html Wed Mar 14 03:37:45 2007
@@ -192,48 +192,68 @@
       <a name="Testing Conventions Used in the Apache Harmony Class Library">Testing Conventions Used in the Apache Harmony Class Library</a>
     </h1>
                         <p>
-		This document describes PROPOSED placement and package naming conventions for
+                This document describes PROPOSED placement and package naming conventions for
                 different types of Harmony class library tests.
-	</p>
+            </p>
                                 <p>
-		The Harmony class library code is organized into modules that might have their own
+                The Harmony class library code is organized into modules that might have their own
                 specifics. This document provides general guidlines and recomendations that might be
                 adapted/modified to reflect module specifics.
-	</p>
+            </p>
                                 <p>
-		See also: <a href="ser_testing.html">Framework for Testing Serialization</a>
-	</p>
+                See also: <a href="ser_testing.html">Framework for Testing Serialization</a>
+            </p>
                                     
     <h2>
         <a name="Location of the Tests in the Directory Tree">Location of the Tests in the Directory Tree</a>
     </h2>
       
                         <p>
-		Each Java class belongs to a specific module of the Harmony class library. Tests against
-                classes belonging to a module belong to the same module. Tests, their resources, and support
-                classes are located under: </p>
+                    Each Java class belongs to a specific module of the Harmony class library. Tests against
+                    classes belonging to a module belong to the same module. Tests, their resources, and support
+                    classes are located under:
+                </p>
                                 <pre>&lt;modulename&gt;/src/test</pre>
-                                <p>Tests that are specific for Harmony, testing Harmony implementation details, and may fail
-                on RI or other compliant implementations are separated from the imlpementation-independent
-                tests that must pass on RI and all conformant implementations.</p>
-                                <pre>&lt;modulename&gt;/src/test/<b>impl</b> - Harmony specific tests<br />
-&lt;modulename&gt;/src/test/<b>api</b> - Implementation-independent tests</pre>
-                                <p>Special-purpose tests like stress tests or tests that require special configuration are 
-                separated from general-purpose tests.</p>
-                                <pre>&lt;modulename&gt;/src/test/<b>stress</b></pre>
-                                <p>Tests are not separated by functionality under test, for example, tests against <code>clone()</code>
-                methods are <b>not</b> separated from tests against <code>equals()</code> methods.
+                                <p>
+                    Tests that are specific for Harmony, testing Harmony implementation details, and may fail
+                    on RI or other compliant implementations are separated from the imlpementation-independent
+                    tests that must pass on RI and all conformant implementations.
+                </p>
+                                <pre>
+                    &lt;modulename&gt;/src/test/<b>impl</b> - Harmony specific tests<br />
+                    &lt;modulename&gt;/src/test/<b>api</b> - Implementation-independent tests
+                </pre>
+                                <p>
+                    Special-purpose tests like stress tests or tests that require special configuration are
+                    separated from general-purpose tests.
+                </p>
+                                <pre>
+                    &lt;modulename&gt;/src/test/<b>stress</b>
+                </pre>
+                                <p>
+                    Tests are not separated by functionality under test, for example, tests against <code>clone()</code>
+                    methods are <b>not</b> separated from tests against <code>equals()</code> methods.
 
-                Classpath tests are separated from bootclasspath tests on a directory level:</p>
-                                <pre>&lt;modulename&gt;/src/test/api/<b>java</b> - Classpath tests<br />
-&lt;modulename&gt;/src/test/api/<b>java.injected</b> - Bootclasspath tests</pre>
-                                <p> Find more details <a href="#Package and Class Names for Different Types of the Tests">
-                 below</a>.</p>
-                                <p>Some modules might have platform specific tests that are in the case separated on a directory 
-                level:</p>
-                                <pre>&lt;modulename&gt;/src/test/api/<b>common</b><br />
-&lt;modulename&gt;/src/test/api/<b>windows</b><br />
-&lt;modulename&gt;/src/test/api/<b>linux</b></pre>
+                    Classpath tests are separated from bootclasspath tests on a directory level:
+                </p>
+                                <pre>
+                    &lt;modulename&gt;/src/test/api/<b>java</b> - Classpath tests<br />
+                    &lt;modulename&gt;/src/test/api/<b>java.injected</b> - Bootclasspath tests
+                </pre>
+                                <p>
+                    Find more details <a href="#Package and Class Names for Different Types of the Tests">
+                        below
+                    </a>.
+                </p>
+                                <p>
+                    Some modules might have platform specific tests that are in the case separated on a directory
+                    level:
+                </p>
+                                <pre>
+                    &lt;modulename&gt;/src/test/api/<b>common</b><br />
+                    &lt;modulename&gt;/src/test/api/<b>windows</b><br />
+                    &lt;modulename&gt;/src/test/api/<b>linux</b>
+                </pre>
                    
                                     
     <h2>
@@ -241,42 +261,62 @@
     </h2>
       
                         <p>
-		If the test is designed to be run from bootclasspath, then its package is the same
-                as the package of the class under the test.
-	</p>
+                    If the test is designed to be run from bootclasspath, then its package is the same
+                    as the package of the class under the test.
+                </p>
                                 <p>
-		If the test is designed to be run from classpath then:</p>
+                    If the test is designed to be run from classpath then:
+                </p>
                                 <ol>
-                  <li>If the package under test belongs to a public package, for example, it 
-                  is a part of the API specification, then the test's package is: 
-			<pre>org.apache.harmony.&lt;modulename&gt;.tests.<b>&lt;package under test&gt;</b></pre>
-    <p class="example">Example</p>
-     
-			<pre>org.apache.harmony.luni.tests.<b>java.lang</b><br />
-org.apache.harmony.crypto.tests.<b>javax.crypto</b><br />
-org.apache.harmony.auth.tests.<b>org.ietf.jgss</b></pre>
-</li>
-    <li>If the package under test belongs to <code>org.apache.harmony</code> 
-    namespace so that class's package is:
-			<pre>org.apache.harmony.&lt;modulename&gt;.<b>&lt;rest of the package name&gt;</b></pre>
-                then the test's package is: 
-			<pre>org.apache.harmony.&lt;modulename&gt;.tests.<b>&lt;rest of the package name&gt;</b></pre> 
-    <p class="example">Example</p>
-      <p class="notetext">
-			<code>org.apache.harmony.luni.internal.net.www.protocol</code> - package under test<br />
-<code>org.apache.harmony.luni.tests.internal.net.www.protocol</code> - package for the test</p>
-			
-</li></ol>
+                    <li>
+                        If the package under test belongs to a public package, for example, it
+                        is a part of the API specification, then the test's package is:
+                        <pre>
+                            org.apache.harmony.&lt;modulename&gt;.tests.<b>&lt;package under test&gt;</b>
+                        </pre>
+                        <p class="example">Example</p>
+
+                        <pre>
+                            org.apache.harmony.luni.tests.<b>java.lang</b><br />
+                            org.apache.harmony.crypto.tests.<b>javax.crypto</b><br />
+                            org.apache.harmony.auth.tests.<b>org.ietf.jgss</b>
+                        </pre>
+                    </li>
+                    <li>
+                        If the package under test belongs to <code>org.apache.harmony</code>
+                        namespace so that class's package is:
+                        <pre>
+                            org.apache.harmony.&lt;modulename&gt;.<b>&lt;rest of the package name&gt;</b>
+                        </pre>
+                        then the test's package is:
+                        <pre>
+                            org.apache.harmony.&lt;modulename&gt;.tests.<b>&lt;rest of the package name&gt;</b>
+                        </pre>
+                        <p class="example">Example</p>
+                        <p class="notetext">
+                            <code>org.apache.harmony.luni.internal.net.www.protocol</code> - package under test<br />
+                            <code>org.apache.harmony.luni.tests.internal.net.www.protocol</code> - package for the test
+                        </p>
+
+                    </li>
+                </ol>
                                 <p>
-   To avoid collision of test results for various type of tests, reflect a test type in a test name.</p>
+                    To avoid collision of test results for various type of tests, reflect a test type in a test name.
+                </p>
                                 <p class="example">Example</p>
-                                <p class="notetext">To separate the <code>impl</code> test results from 
-    the <code>api</code> ones, the <code>impl</code> test names end with 
-                <code>_ImplTest</code>:<br />
-			<code>javax.crypto.<b>CipherTest</b></code> - Implementation independent bootclasspath 
-      test for <code>javax.crypto.Cipher</code><br />
-<code>javax.crypto.<b>Cipher_ImplTest</b></code> - Implementation specific bootclasspath 
-test for <code>javax.crypto.Cipher</code></p>
+                                <p class="notetext">
+                    To separate the <code>impl</code> test results from
+                    the <code>api</code> ones, the <code>impl</code> test names end with
+                    <code>_ImplTest</code>:<br />
+                    <code>
+                        javax.crypto.<b>CipherTest</b>
+                    </code> - Implementation independent bootclasspath
+                    test for <code>javax.crypto.Cipher</code><br />
+                    <code>
+                        javax.crypto.<b>Cipher_ImplTest</b>
+                    </code> - Implementation specific bootclasspath
+                    test for <code>javax.crypto.Cipher</code>
+                </p>
                    
                 <p><a href="#top">Back to top</a></p>
                     



Mime
View raw message