You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by na...@apache.org on 2007/03/13 14:17:31 UTC
svn commit: r517682 [4/5] - in /harmony/standard/site/xdocs: ./
subcomponents/classlibrary/ subcomponents/drlvm/
Modified: harmony/standard/site/xdocs/subcomponents/classlibrary/compat.xml
URL: http://svn.apache.org/viewvc/harmony/standard/site/xdocs/subcomponents/classlibrary/compat.xml?view=diff&rev=517682&r1=517681&r2=517682
==============================================================================
--- harmony/standard/site/xdocs/subcomponents/classlibrary/compat.xml (original)
+++ harmony/standard/site/xdocs/subcomponents/classlibrary/compat.xml Tue Mar 13 06:17:30 2007
@@ -3,11 +3,11 @@
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
+ contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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
+ the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
@@ -20,189 +20,214 @@
<document>
- <properties>
- <title>Compatibility goals in the Apache Harmony Classlib</title>
- <author email="dev@harmony.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>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>
-
-<subsection name="The "Reference Implementation"">
-<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>
-</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="../../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>
-</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 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>
-</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>
+ <properties>
+ <title>Compatibility goals in the Apache Harmony Classlib</title>
+ <author email="dev@harmony.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>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>
+
+ <subsection name="The "Reference Implementation"">
+ <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>
+ </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="../../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>
+ </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 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>
+ </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>
+ </section>
+ </body>
</document>
Modified: harmony/standard/site/xdocs/subcomponents/classlibrary/pkgnaming.xml
URL: http://svn.apache.org/viewvc/harmony/standard/site/xdocs/subcomponents/classlibrary/pkgnaming.xml?view=diff&rev=517682&r1=517681&r2=517682
==============================================================================
--- harmony/standard/site/xdocs/subcomponents/classlibrary/pkgnaming.xml (original)
+++ harmony/standard/site/xdocs/subcomponents/classlibrary/pkgnaming.xml Tue Mar 13 06:17:30 2007
@@ -3,11 +3,11 @@
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
+ contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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
+ the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
@@ -20,92 +20,121 @@
<document>
- <properties>
- <title>Package Naming Conventions in the Apache Harmony Classlib</title>
- <author email="dev@harmony.apache.org">Harmony Documentation Team</author>
- </properties>
-
-<body>
-
-<section name="Package Naming Conventions Used in the Apache Harmony Class Library">
- <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>
- <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>
-
-<subsection name="All Packages Belong to a Specific Module">
- <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><module></b></pre>
-
- <p class="example">
- Example
- </p>
- <p class="exampletext">
- <pre>org.apache.harmony.luni
-org.apache.harmony.security</pre>
-
- </p>
-</subsection>
-
-<subsection name="Package Names within a Module">
- <p>
- Modules are free to use whatever package names they choose with the
- prefix <code>org.apache.harmony.<b><modulename></b></code>.
- </p>
- <p>
- The following package name segements are <b>reserved</b> to indicate the meanings
- defined below:</p>
- <ul>
- <li><code>org.apache.harmony.<modulename>.<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.<modulename>.<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.<modulename>.<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.<modulename>.<b><anything_else></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>
-</subsection>
-</section>
-</body>
-</document>
\ No newline at end of file
+ <properties>
+ <title>Package Naming Conventions in the Apache Harmony Classlib</title>
+ <author email="dev@harmony.apache.org">Harmony Documentation Team</author>
+ </properties>
+
+ <body>
+
+ <section name="Package Naming Conventions Used in the Apache Harmony Class Library">
+ <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>
+ <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>
+
+ <subsection name="All Packages Belong to a Specific Module">
+ <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><module></b>
+ </pre>
+
+ <p class="example">
+ Example
+ </p>
+ <p class="exampletext">
+ <pre>
+ org.apache.harmony.luni
+ org.apache.harmony.security
+ </pre>
+
+ </p>
+ </subsection>
+
+ <subsection name="Package Names within a Module">
+ <p>
+ Modules are free to use whatever package names they choose with the
+ prefix <code>
+ org.apache.harmony.<b><modulename></b>
+ </code>.
+ </p>
+ <p>
+ The following package name segements are <b>reserved</b> to indicate the meanings
+ defined below:
+ </p>
+ <ul>
+ <li>
+ <code>
+ org.apache.harmony.<modulename>.<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.<modulename>.<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.<modulename>.<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.<modulename>.<b><anything_else></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>
+ </subsection>
+ </section>
+ </body>
+</document>
Modified: harmony/standard/site/xdocs/subcomponents/classlibrary/ser_testing.xml
URL: http://svn.apache.org/viewvc/harmony/standard/site/xdocs/subcomponents/classlibrary/ser_testing.xml?view=diff&rev=517682&r1=517681&r2=517682
==============================================================================
--- harmony/standard/site/xdocs/subcomponents/classlibrary/ser_testing.xml (original)
+++ harmony/standard/site/xdocs/subcomponents/classlibrary/ser_testing.xml Tue Mar 13 06:17:30 2007
@@ -3,11 +3,11 @@
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
+ contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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
+ the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
@@ -20,181 +20,232 @@
<document>
- <properties>
- <title>Framework for Testing Serialization</title>
- <author email="dev@harmony.apache.org">Harmony Documentation Team</author>
- </properties>
-
-<body>
-
-<section name="Framework for Testing Serialization">
- <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>
-
-<subsection name="Guidelines for Developing Serialization Tests">
- <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>
- <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>
-
-
- <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>
- <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 {
-
- 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>
-
- <pre>void assertDeserialized(Serializable reference, Serializable test);</pre>
-
-
-</subsection>
-
-<subsection name="Placement and Naming Conventions for Resource Files">
- <p>
- The resource files should follow the next <a name="conventions">conventions</a>:</p>
-
- <ul>
- <li>Root folder for resource files is <code><module root>/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><golden></code> keyword is used for files generated on RI
- </li>
-
- <li><code><harmony></code> keyword is used for files generated on
- Harmony implementation
- </li>
-
- <li><code><negative></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>
-</subsection>
-</section>
-</body>
+ <properties>
+ <title>Framework for Testing Serialization</title>
+ <author email="dev@harmony.apache.org">Harmony Documentation Team</author>
+ </properties>
+
+ <body>
+
+ <section name="Framework for Testing Serialization">
+ <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>
+
+ <subsection name="Guidelines for Developing Serialization Tests">
+ <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>
+ <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>
+
+
+ <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>
+ <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 {
+
+ 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>
+
+ <pre>void assertDeserialized(Serializable reference, Serializable test);</pre>
+
+
+ </subsection>
+
+ <subsection name="Placement and Naming Conventions for Resource Files">
+ <p>
+ The resource files should follow the next <a name="conventions">conventions</a>:
+ </p>
+
+ <ul>
+ <li>
+ Root folder for resource files is <code><module root>/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><golden></code> keyword is used for files generated on RI
+ </li>
+
+ <li>
+ <code><harmony></code> keyword is used for files generated on
+ Harmony implementation
+ </li>
+
+ <li>
+ <code><negative></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>
+ </subsection>
+ </section>
+ </body>
</document>
Modified: harmony/standard/site/xdocs/subcomponents/classlibrary/status.xml
URL: http://svn.apache.org/viewvc/harmony/standard/site/xdocs/subcomponents/classlibrary/status.xml?view=diff&rev=517682&r1=517681&r2=517682
==============================================================================
--- harmony/standard/site/xdocs/subcomponents/classlibrary/status.xml (original)
+++ harmony/standard/site/xdocs/subcomponents/classlibrary/status.xml Tue Mar 13 06:17:30 2007
@@ -2,11 +2,11 @@
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
+ contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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
+ the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
@@ -19,29 +19,31 @@
<document>
- <properties>
- <title>Apache Harmony</title>
- <author email="dev@harmony.apache.org">Harmony Documentation Team</author>
- </properties>
-
- <body>
-
-<section name="Class Library Component Status">
-
- <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>
+ <properties>
+ <title>Apache Harmony</title>
+ <author email="dev@harmony.apache.org">Harmony Documentation Team</author>
+ </properties>
+
+ <body>
+
+ <section name="Class Library Component Status">
+
+ <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>
+
+ </section>
+
+ </body>
+</document>
- </section>
- </body>
- </document>
Modified: harmony/standard/site/xdocs/subcomponents/classlibrary/testing.xml
URL: http://svn.apache.org/viewvc/harmony/standard/site/xdocs/subcomponents/classlibrary/testing.xml?view=diff&rev=517682&r1=517681&r2=517682
==============================================================================
--- harmony/standard/site/xdocs/subcomponents/classlibrary/testing.xml (original)
+++ harmony/standard/site/xdocs/subcomponents/classlibrary/testing.xml Tue Mar 13 06:17:30 2007
@@ -3,11 +3,11 @@
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
+ contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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
+ the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
@@ -20,110 +20,149 @@
<document>
- <properties>
- <title>Testing Conventions in the Apache Harmony Classlib</title>
- <author email="dev@harmony.apache.org">Harmony Documentation Team</author>
- </properties>
-
-<body>
-
-<section name="Testing Conventions Used in the Apache Harmony Class Library">
- <p>
- This document describes PROPOSED placement and package naming conventions for
+ <properties>
+ <title>Testing Conventions in the Apache Harmony Classlib</title>
+ <author email="dev@harmony.apache.org">Harmony Documentation Team</author>
+ </properties>
+
+ <body>
+
+ <section name="Testing Conventions Used in the Apache Harmony Class Library">
+ <p>
+ This document describes PROPOSED placement and package naming conventions for
different types of Harmony class library tests.
- </p>
- <p>
- The Harmony class library code is organized into modules that might have their own
+ </p>
+ <p>
+ 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>
- See also: <a href="ser_testing.html">Framework for Testing Serialization</a>
- </p>
-
-<subsection name="Location of the Tests in the Directory Tree">
- <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><modulename>/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><modulename>/src/test/<b>impl</b> - Harmony specific tests<br/>
-<modulename>/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><modulename>/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><modulename>/src/test/api/<b>java</b> - Classpath tests<br/>
-<modulename>/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><modulename>/src/test/api/<b>common</b><br/>
-<modulename>/src/test/api/<b>windows</b><br/>
-<modulename>/src/test/api/<b>linux</b></pre>
-
-
-</subsection>
-
-<subsection name="Package and Class Names for Different Types of the Tests">
- <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>
+ </p>
+ <p>
+ See also: <a href="ser_testing.html">Framework for Testing Serialization</a>
+ </p>
+
+ <subsection name="Location of the Tests in the Directory Tree">
+ <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><modulename>/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>
+ <modulename>/src/test/<b>impl</b> - Harmony specific tests<br/>
+ <modulename>/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>
+ <modulename>/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>
+ <modulename>/src/test/api/<b>java</b> - Classpath tests<br/>
+ <modulename>/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>
+ <modulename>/src/test/api/<b>common</b><br/>
+ <modulename>/src/test/api/<b>windows</b><br/>
+ <modulename>/src/test/api/<b>linux</b>
+ </pre>
+
+
+ </subsection>
+
+ <subsection name="Package and Class Names for Different Types of the Tests">
+ <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>
<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.<modulename>.tests.<b><package under test></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.<modulename>.<b><rest of the package name></b></pre>
- then the test's package is:
- <pre>org.apache.harmony.<modulename>.tests.<b><rest of the package name></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>
- <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>
-
-
-</subsection>
-</section>
-</body>
-</document>
\ No newline at end of file
+ <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.<modulename>.tests.<b><package under test></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.<modulename>.<b><rest of the package name></b>
+ </pre>
+ then the test's package is:
+ <pre>
+ org.apache.harmony.<modulename>.tests.<b><rest of the package name></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>
+ <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>
+
+
+ </subsection>
+ </section>
+ </body>
+</document>
Modified: harmony/standard/site/xdocs/subcomponents/drlvm/GettingStarted.html
URL: http://svn.apache.org/viewvc/harmony/standard/site/xdocs/subcomponents/drlvm/GettingStarted.html?view=diff&rev=517682&r1=517681&r2=517682
==============================================================================
--- harmony/standard/site/xdocs/subcomponents/drlvm/GettingStarted.html (original)
+++ harmony/standard/site/xdocs/subcomponents/drlvm/GettingStarted.html Tue Mar 13 06:17:30 2007
@@ -1,10 +1,10 @@
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
+ contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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
+ the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
@@ -18,192 +18,150 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
- <head>
- <meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
- <title>
- Getting Started with DRLVM
- </title>
- <link rel="Stylesheet" type="text/css" media="all" href="site.css" />
- </head>
- <body>
- <h1>
- <a id="TOP" name="TOP"></a>Getting Started with DRLVM
- </h1>
- <p>
- The Dynamic Runtime Layer virtual machine (DRLVM) is a clean-room implementation of the
- Java<a href="#*">*</a> virtual machine for Java 2 Platform, Standard Edition (J2SE<a
- href="#*">*</a>) 1.5.0. This document gives tips on how to start using
- the DRL virtual machine (VM). Use this page to learn where to get the
- code and how to use it. For documentation on the Harmony Java<a
- href="#*">*</a> class libraries, see the <a href="../classlibrary/index.html">classlib page</a>.
- </p>
- <p>
- To quickly start with DRL, read this page and follow the instructions.
- It is recommended that you strictly follow the instructions of this
- guide to ensure system stability and anticipated results. After
- completing this guide, you will be able to run and debug your own
- applications with DRLVM.
- </p>
- <h2>
- <a id="Overview" name="Overview"></a>Overview
- </h2>
- <p>
- For a definition of the DRL virtual machine and links to all docs
- describing it, see the DRLVM <a href="index.html">component page</a>.
- For instructions on how to get and build the code, and configure your
- environment, please visit the <a
- href="../../quickhelp_users.html">Getting Started for Users</a> page.
- If you fail to build the source code or come across other problems, go
- to our project <a href="http://wiki.apache.org/harmony/"
- target="_blank">Wiki resource</a> and search for your issue on the <a
- href="http://wiki.apache.org/harmony/DrlvmBuildTroubleshooting"
- target="_blank">DrlvmBuildTroubleshooting</a> page. If no known issue
- matches your problem, please write to the mailing list or add your
- issue to the wiki page.
- </p>
- <p>
- The README file supplied with the source code and the Quick Help
- instructions enable you to build the VM source code in the default
- configuration. To modify the code behavior, use the available
- command-line options, as indicated in the <a
- href="http://wiki.apache.org/harmony/DrlvmCommandLineOptions"
- target="_blank">Wiki command-line options page</a>. Read further
- for illustrations of command-line options usage.
- </p>
- <h1>
- <a id="Running_Hello" name="Running_Hello"></a>Running an Application
- </h1>
- <p>
- This scenario provides step-by-step instructions on running a
- <code>Hello</code> application in the Windows<a href="#*">*</a> or the
- Linux<a href="#*">*</a> console. The scenario uses a sample
- <code>Hello.class</code> Java<a href="#*">*</a> class for illustration.
- Please use your own application instead.
- </p>
- <ol>
- <li>
- To start DRL, change your current directory to the
- <code><<b>installation folder</b>>\bin</code> directory.
- </li>
- <li>
- Check that you have files <code>java.exe</code> on Windows<a
- href="#*">*</a> or <code>java</code> on Linux<a href="#*">*</a> and
- <code>Hello.class</code> in the <code>\bin</code> directory.<br />
- On Linux<a href="#*">*</a>, make sure that you can run
- applications and load dynamic libraries from the current directory.
- If you are using the Intel(R) C++ compiler, make sure the
- <code>LD_LIBRARY_PATH</code> variable contains location of the ICC
- libraries.
- </li>
- <li>
- Run the <code>Hello</code> application by entering:
-<pre>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
+ <title>Getting Started with DRLVM </title>
+ <link rel="Stylesheet" type="text/css" media="all" href="site.css" />
+</head>
+<body>
+ <h1>
+ <a id="TOP" name="TOP"></a>Getting Started with DRLVM
+ </h1>
+ <p>
+ The Dynamic Runtime Layer virtual machine (DRLVM) is a clean-room implementation
+ of the Java<a href="#*">*</a> virtual machine for Java 2 Platform, Standard Edition
+ (J2SE<a href="#*">*</a>) 1.5.0. This document gives tips on how to start using the
+ DRL virtual machine (VM). Use this page to learn where to get the code and how to
+ use it. For documentation on the Harmony Java<a href="#*">*</a> class libraries,
+ see the <a href="../classlibrary/index.html">classlib page</a>.
+ </p>
+ <p>
+ To quickly start with DRL, read this page and follow the instructions. It is recommended
+ that you strictly follow the instructions of this guide to ensure system stability
+ and anticipated results. After completing this guide, you will be able to run and
+ debug your own applications with DRLVM.
+ </p>
+ <h2>
+ <a id="Overview" name="Overview"></a>Overview
+ </h2>
+ <p>
+ For a definition of the DRL virtual machine and links to all docs describing it,
+ see the DRLVM <a href="index.html">component page</a>. For instructions on how to
+ get and build the code, and configure your environment, please visit the <a href="../../quickhelp_users.html">
+ Getting Started for Users</a> page. If you fail to build the source code or
+ come across other problems, go to our project <a href="http://wiki.apache.org/harmony/"
+ target="_blank">Wiki resource</a> and search for your issue on the <a href="http://wiki.apache.org/harmony/DrlvmBuildTroubleshooting"
+ target="_blank">DrlvmBuildTroubleshooting</a> page. If no known issue matches
+ your problem, please write to the mailing list or add your issue to the wiki page.
+ </p>
+ <p>
+ The README file supplied with the source code and the Quick Help instructions enable
+ you to build the VM source code in the default configuration. To modify the code
+ behavior, use the available command-line options, as indicated in the <a href="http://wiki.apache.org/harmony/DrlvmCommandLineOptions"
+ target="_blank">Wiki command-line options page</a>. Read further for illustrations
+ of command-line options usage.
+ </p>
+ <h1>
+ <a id="Running_Hello" name="Running_Hello"></a>Running an Application
+ </h1>
+ <p>
+ This scenario provides step-by-step instructions on running a <code>Hello</code>
+ application in the Windows<a href="#*">*</a> or the Linux<a href="#*">*</a> console.
+ The scenario uses a sample <code>Hello.class</code> Java<a href="#*">*</a> class
+ for illustration. Please use your own application instead.
+ </p>
+ <ol>
+ <li>To start DRL, change your current directory to the <code><<b>installation folder</b>>\bin</code>
+ directory. </li>
+ <li>Check that you have files <code>java.exe</code> on Windows<a href="#*">*</a> or
+ <code>java</code> on Linux<a href="#*">*</a> and <code>Hello.class</code> in the
+ <code>\bin</code> directory.<br />
+ On Linux<a href="#*">*</a>, make sure that you can run applications and load dynamic
+ libraries from the current directory. If you are using the Intel(R) C++ compiler,
+ make sure the <code>LD_LIBRARY_PATH</code> variable contains location of the ICC
+ libraries. </li>
+ <li>Run the <code>Hello</code> application by entering:
+ <pre>
java Hello
</pre>
<p>
- You will see “<i>Hello World!</i>" printed on the screen.
- This means that you have successfully launched the virtual
- machine, and that it has processed the <code>Hello.class</code>
- Java<a href="#*">*</a> class to execute the <code>Hello</code>
- application.
+ You will see “<i>Hello World!</i>" printed on the screen. This means that
+ you have successfully launched the virtual machine, and that it has processed the
+ <code>Hello.class</code> Java<a href="#*">*</a> class to execute the <code>Hello</code>
+ application.
</p>
- </li>
- </ol>
- <h1>
- Developing Code in Eclipse
- </h1>
- <h2>
- <a id="Eclipse_Hello_world" name="Eclipse_Hello_world"></a> Running an
- Application in Eclipse
- </h2>
- <p>
- In this section, a simple scenario shows how to create an application
- and run it in Eclipse<a href="#*">*</a> with our virtual machine.
- </p>
- <p class="note">
- Note
- </p>
- <p class="notetext">
- If you are using Eclipse, see the page <a href="../../documentation/dev_eclipse.html">
- Working with Harmony Code in
- Eclipse </a> for specific setup instructions.
- </p>
- <p>
- This scenario provides step-by-step instructions on running a Java
- application in the Eclipse environment. In the scenario, you will
- launch Eclipse, create a new project and a new Java class within this
- project, and finally you will run the new application.
- </p>
- <ol start="0">
- <li>
- If you have no Eclipse, download the package at <a
- href="http://download.eclipse.org/eclipse/downloads/"
- target="_blank">http://download.eclipse.org/eclipse/downloads/</a>,
- and unpack this distribution.<br />
- Set up Eclipse as described in <a href="../../documentation/dev_eclipse.html">
- Working with Harmony Code in Eclipse</a>.
- </li>
- <li>
- Start Eclipse and create a new Java project.
- </li>
- <li>
- In the project workspace, create a <code>HelloWorld</code> class with the
- <code>public static void main(String[] args)</code> method containing the following code:
- <pre>
+ </li>
+ </ol>
+ <h1>
+ Developing Code in Eclipse
+ </h1>
+ <h2>
+ <a id="Eclipse_Hello_world" name="Eclipse_Hello_world"></a>Running an Application
+ in Eclipse
+ </h2>
+ <p>
+ In this section, a simple scenario shows how to create an application and run it
+ in Eclipse<a href="#*">*</a> with our virtual machine.
+ </p>
+ <p class="note">
+ Note
+ </p>
+ <p class="notetext">
+ If you are using Eclipse, see the page <a href="../../documentation/dev_eclipse.html">
+ Working with Harmony Code in Eclipse </a>for specific setup instructions.
+ </p>
+ <p>
+ This scenario provides step-by-step instructions on running a Java application in
+ the Eclipse environment. In the scenario, you will launch Eclipse, create a new
+ project and a new Java class within this project, and finally you will run the new
+ application.
+ </p>
+ <ol start="0">
+ <li>If you have no Eclipse, download the package at <a href="http://download.eclipse.org/eclipse/downloads/"
+ target="_blank">http://download.eclipse.org/eclipse/downloads/</a>, and unpack this
+ distribution.<br />
+ Set up Eclipse as described in <a href="../../documentation/dev_eclipse.html">Working
+ with Harmony Code in Eclipse</a>. </li>
+ <li>Start Eclipse and create a new Java project. </li>
+ <li>In the project workspace, create a <code>HelloWorld</code> class with the <code>
+ public static void main(String[] args)</code> method containing the following code:
+ <pre>
int i=18;
System.out.println("Hello, World!");</pre>
- </li>
-
- <li>
- Save the file.
- </li>
- <li>
- Run the <code>HelloWorld</code> class. The result of the execution
- is printed in the <b>Console</b> tab of your workspace: <i>"Hello,
- World!"</i> appears.
- </li>
- </ol>
- <h2>
- <a id="Eclipse_debug_scenario" name="Eclipse_debug_scenario"></a>
- Debugging an Application in Eclipse
- </h2>
- <p>
- This scenario provides instructions on how to debug a simple
- application in Eclipse<a href="#*">*</a>.
- </p>
- <ol start="0">
- <li>
- Repeat steps 0 to 4 of the previous scenario to set up the
- workspace and create a new class in the new project.
- </li>
- <li>
- Set up breakpoints for debugging purposes, as needed. In the example with the
- <code>HelloWorld</code> class, set the breakpoint on the following
- line:
-<pre>
+ </li>
+ <li>Save the file. </li>
+ <li>Run the <code>HelloWorld</code> class. The result of the execution is printed in
+ the <b>Console</b> tab of your workspace: <i>"Hello, World!"</i> appears. </li>
+ </ol>
+ <h2>
+ <a id="Eclipse_debug_scenario" name="Eclipse_debug_scenario"></a>Debugging an Application
+ in Eclipse
+ </h2>
+ <p>
+ This scenario provides instructions on how to debug a simple application in Eclipse<a
+ href="#*">*</a>.
+ </p>
+ <ol start="0">
+ <li>Repeat steps 0 to 4 of the previous scenario to set up the workspace and create
+ a new class in the new project. </li>
+ <li>Set up breakpoints for debugging purposes, as needed. In the example with the <code>
+ HelloWorld</code> class, set the breakpoint on the following line:
+ <pre>
System.out.println ("Hello, World!");
</pre>
- </li>
- <li>
- Start the debug operation on your class -
- <code>HelloWorld.java</code> in the example.<br />
- <br />
- After the debug run completes, the workspace gets updated with new
- results.
- </li>
- <li>
- After you are done, resume the application. When the run has
- completed, the <b>Console</b> tab at the bottom displays the result
- of execution. In our example, <em>H</em><i>ello World!</i> is
- printed.
- </li>
- </ol>
-
- <p>
- <a id="*" name="*">*</a> Other brands and names are the property of
- their respective owners.
- </p>
- </body>
+ </li>
+ <li>Start the debug operation on your class - <code>HelloWorld.java</code> in the example.<br />
+ <br />
+ After the debug run completes, the workspace gets updated with new results. </li>
+ <li>After you are done, resume the application. When the run has completed, the <b>Console</b>
+ tab at the bottom displays the result of execution. In our example, <em>H</em><i>ello
+ World!</i> is printed. </li>
+ </ol>
+ <p>
+ <a id="*" name="*">*</a> Other brands and names are the property of their respective
+ owners.
+ </p>
+</body>
</html>