Index: xdocs/documentation/build_website.xml =================================================================== --- xdocs/documentation/build_website.xml (revision 466968) +++ xdocs/documentation/build_website.xml (working copy) @@ -31,7 +31,7 @@

- The following tools are required to build the Harmony website + The following tools are required to build the Harmony website:

-

+

  1. - Download the website source from Harmony subversion repository + Download the website source from Harmony subversion repository:
  2. $ svn checkout https://svn.apache.org/repos/asf/incubator/harmony/standard/site
    - +
  3. - Change into the site directory and run the default ant script target -
    $ cd site
    -
    $ ant
    -
  4. + Change into the site directory: +
    $ cd site
    +
  5. Run the default ant script target:
  6. +
    $ ant
    +
-

+

- At this point, you have a complete generated website and documentation in the site/docs - subdirectory. Open the index.html page and start browsing. + At this point, you have a complete generated website and documentation in the + site/docs subdirectory. Open the index.html page and start browsing.

@@ -71,13 +72,14 @@

- Making changes is straightforward. All edits are made to the contents of the xdocs/ - subdirectory, and then rendered via the procedure above into the docs/ directory. -

+ Making changes is straightforward. All edits are made to the contents of the xdocs/ + subdirectory, and then rendered via the procedure above into the docs/ directory. +

+

- If you are a Harmony committer, you can simply checkin your changes. If you are not - a committer, any updates and additions to the site are very welcome. Please + If you are a Harmony committer, you can simply checkin your changes. If you are not + a committer, any updates and additions to the site are very welcome. Please see our Get Involved page for instructions on how to contribute your changes.

@@ -88,32 +90,31 @@

If you are a Harmony Committer, you can commit your changes into SVN and then - publish to the project website. Once the changes are in SVN, simply : + publish to the project website. Once the changes are in SVN, do the following:

-

  1. - SSH to minotaur.apache.org + SSH to minotaur.apache.org. Your login name will of course be your own.
  2. $ ssh geirm@minotaur.apache.org 
    - Your login name will of course be your own. - +
  3. - Go to the project website directory. + Go to the project website directory:
  4. $ cd /www/incubator.apache.org/harmony/
    - +
  5. - Update the local copy. There are two ways. A simple + Update the local copy in one of two ways:
    $ svn update
    - will update the local copy. If you need to delete the HTML and - re-checout use -
    $ `cat UPDATE`
    - as the UPDATE file has the command used to do a fresh svn checkout. -
  6. + If you need to delete the HTML and + re-checkout, use: +
    $ `cat UPDATE`
    +

    Note

    +

    The UPDATE file has the command performing a fresh svn checkout.

    +
-

+
Index: xdocs/subcomponents/buildtest/index.xml =================================================================== --- xdocs/subcomponents/buildtest/index.xml (revision 466968) +++ xdocs/subcomponents/buildtest/index.xml (working copy) @@ -30,16 +30,15 @@

The - 'build-test framework' is a simple configuration of - Cruise Control, - a framework for continuous build process. It also includes all the + build-test framework is a simple configuration of + CruiseControl, + a framework for continuous build process. It also includes all the necessary support to simplify installation.

- Currently, the framework does these distinct tasks, in order : -

- + Currently, the framework does the following distinct tasks, in order, + and only when code changes in the repository:

  1. Update the source for the class library from SVN
  2. Get any new dependencies needed for building the class library
  3. @@ -48,21 +47,15 @@
  4. Get and build any new dependencies needed for DRLVM
  5. Build and test the DRLVM
+ +
-

- It does these tasks in-order, and only when code changes in the repository. -

-
+ -
- - Pre-requisites -

- Basically, you need the tools needed to build the Apache Harmony - components, like Java, Ant, C/C++ compilers, etc. Please see - the other parts of the project for information on the necessary - toolchains. You need the following software installed : + Basically, you need the same tools, as for building the Apache Harmony + components, like Java, Ant, C/C++ compilers, etc. Install the following + software:

    @@ -70,91 +63,74 @@
  1. Apache Ant
  2. Subversion Client
+

Please see the other parts of the project for information on the necessary + toolchains.

- Setup + +

+ Get the /harmony/enhanced/buildtest/ part of the Apache + Harmony project via zip or tgz files. You also can + check it out from the project Subversion repository:

-

- Get the /harmony/enhanced/buildtest/ part of the Apache - Harmony project. If you are reading this, you either have - it via a zip or tgz, or have checked it out from the project - Subversion repository. In the event that you don't have it - you can get it via subversion : -

+
svn co https://svn.apache.org/repos/asf/incubator/harmony/enhanced/buildtest/trunk
-
- svn co https://svn.apache.org/repos/asf/incubator/harmony/enhanced/buildtest/trunk -
-

- With Java, Ant and SVN installed, change into the buildtest/trunk - directory and type + With Java, Ant and SVN installed, change into the buildtest/trunk + directory and type:

-
- ant setup -
+
ant setup

- This should fetch CruiseControl, set it up with the Apache Harmony - configuration, and checkout the software to be built and tested + This command fetches CruiseControl, sets it up with the Apache Harmony + configuration, and checks out the software for building and testing from Apache Harmony.

- If you wish to have the tests run successfully, you need to do the - following manual steps for now : + To run the tests successfully, you need to do the + following manual steps for now:

  1. - build the classlib to create the deploy/jdk tree in classlib, first - fetching the dependencies -
    - cd cc/projects/classlib/trunk - ant fetch-depends - ant -
    + Build the classlib to create the deploy/jdk tree in classlib, + first fetching the dependencies: +
    cd cc/projects/classlib/trunk
    +ant fetch-depends
    +ant
  2. - get the appropriate IBM J9 VM for your platform (this will go - away when DRLVM is good enough + Get the appropriate IBM J9 VM for your platform (this will go + away when DRLVM is good enough): -
    - http://www-128.ibm.com/developerworks/java/jdk/harmony/index.html -
    +
    http://www-128.ibm.com/developerworks/java/jdk/harmony/index.html
  3. - unpack the above-fetched J9 distribution into the jdk directory (as - the distro assumes it's dropped into the jdk directory...) + Unpack the above-fetched J9 distribution into the jdk directory (as + the distro assumes it is dropped into thejdk directory): -
    - cd cc/projects/classlib/trunk/deploy/jdk/
    - tar zxf Harmony-vme-linux.IA32-v4.tar.gz -
    +
    cd cc/projects/classlib/trunk/deploy/jdk/
    +tar zxf Harmony-vme-linux.IA32-v4.tar.gz
+
+ - Starting CruiseControl -

- To start the system, just type : + To start the system, type the following command in + buildtest/trunk:

-
- ant -
+
ant
-

- in buildtest/trunk and that will launch CC with the full test set. - To check status, point your browser to -

+

The given command launches CruiseControl with the full test set. + To check status, point your browser to:

-
- http://localhost:8080/ -
- +
http://localhost:8080/
+
Index: xdocs/subcomponents/classlibrary/pkgnaming.xml =================================================================== --- xdocs/subcomponents/classlibrary/pkgnaming.xml (revision 466968) +++ xdocs/subcomponents/classlibrary/pkgnaming.xml (working copy) @@ -21,16 +21,16 @@ - Package naming conventions in the Apache Harmony Classlib + Package Naming Conventions in the Apache Harmony Classlib Harmony Documentation Team -
+

This section is inspired by, and derived from, - the Eclipse package naming convention + the Eclipse package naming convention documentation.

@@ -41,39 +41,40 @@

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 + 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.

- +

Each Java package is owned by a specific module of the Harmony class library. - The module name immediately follows the org.apache.harmony prefix. -

- org.apache.harmony.<module> -
- for example -
- org.apache.harmony.luni
- org.apache.harmony.security -
+ The module name immediately follows the org.apache.harmony prefix.

+
org.apache.harmony.<module>
+ +

+ Example +

+

+

org.apache.harmony.luni
+org.apache.harmony.security
+

- +

Modules are free to use whatever package names they choose with the - prefix org.apache.harmony.<modulename> + prefix org.apache.harmony.<modulename>.

- The following package name segements are

    reserved
to indicate the meanings - defined below: + The following package name segements are reserved to indicate the meanings + defined below:

  • org.apache.harmony.<modulename>.internal -

    +

    Packages with this prefix are implementation packages for use within - the given module. Types and fields that are visible within these + the given module. Types and fields that are visible within these packages MUST NOT be used outside the module itself. Some runtime environments may enforce this reduced visibility scope.

  • @@ -87,7 +88,7 @@
  • org.apache.harmony.<modulename>.examples

    Packages with this prefix contain example code that is not part of the - module API or implementation. Some builds may not include these + module API or implementation. Some builds may not include these packages.

  • org.apache.harmony.<modulename>.<anything_else> @@ -96,14 +97,13 @@ be referenced from any module.

-

-

+

In practice, this means that module developers are free to change the code within an internal package without expecting any consequences beyond the module - itself. However, module developers who modify code that is not in an + itself. However, module developers who modify code that is not in an internal package must do so in a manner that ensures - Java binary compatibility + Java binary compatibility.

Index: xdocs/subcomponents/classlibrary/ser_testing.xml =================================================================== --- xdocs/subcomponents/classlibrary/ser_testing.xml (revision 466968) +++ xdocs/subcomponents/classlibrary/ser_testing.xml (working copy) @@ -21,13 +21,13 @@ - Framework for testing serialization + Framework for Testing Serialization Harmony Documentation Team -
+

The framework for testing serialization is currently PROPOSED and being discussed on the development mailing list harmony-dev@incubator.apache.org. @@ -36,150 +36,151 @@

The framework for testing serialization is intended to simplify and formalize development of serialization tests. This document contains guidelines for - creating tests and conventions for resource files. + creating tests and conventions for resource files.

- +

- The testing framework provides support class + The testing framework provides the support class org.apache.harmony.testframework.serialization.SerializationTest for serialization testing.

-

- 1) Compatibility testing
- Verifies that an object serialized on certified implementation is - correctly deserialized on Harmony implementation.

- The support class provides 4 methods for compatibility testing: +

Compatibility Testing

+

Verifies that an object serialized on certified implementation is + correctly deserialized on Harmony implementation.
+ The support class provides four methods for compatibility testing:

- The first parameter TestCase is used to locate resource - file(s) that contains serialized object(s). The second parameter is an object +

+

The first parameter TestCase is used to locate resource + file(s) that contains serialized object(s).
+ The second parameter is an object or an array of objects to be compared with object(s) deserialized from - resource file(s). And the third parameter is optional.

+ resource file(s).
+ The third parameter is optional.

- So to create a compatibility test for selected class a developer should: +

To create a compatibility test for selected class, a developer should:

  • - serialize object(s) on certified implementation, store serialized - form(s) in resource file(s) and place it(them) according to conventions - below -
  • + Serialize object(s) on certified implementation, store serialized + form(s) in resource file(s) and place it(them) according to the + conventions
  • - add to an unit test a method: testSerializationCompatibility + Add the testSerializationCompatibility method to a unit test
  • - invoke one of the above methods with corresponding arguments + Invoke one of the methods, mentioned above, with corresponding arguments
- - For example, -
-public void testSerializationCompatibility()
+
+  

Example

+ +
		
+    public void testSerializationCompatibility()
         throws Exception {
 
     SerializationTest.verifyGolden(this, new SomeSerializableClass());
 }
-		
-

-

- 2) Self testing
- Verifies that an object can be smoothly serialized and deserialized on - Harmony implementation

- The support class provides 4 methods for self-testing: +

+ + +

Self-Testing

+

Verifies that an object can be smoothly serialized and deserialized on + Harmony implementation.
+ The support class provides four methods for self-testing:

- The provided object(s) is(are) serialized/deserialized and compared with - initial object(s).

+

The provided object(s) is(are) serialized/deserialized and compared with + initial object(s).

- So to create a self test for selected class a developer should: +

To create a self test for a selected class, a developer should:

  • - add to an unit test a method: testSerializationSelf + Add the testSerializationSelf method to a unit test
  • - invoke one of the above methods with corresponding arguments + Invoke one of the methods with corresponding arguments
- For example, -
-public void testSerializationSelf() throws Exception {
+  

Example

+
  
+     public void testSerializationSelf() throws Exception {
 
-    SerializationTest.verifySelf(new SomeSerializableClass(),
-            new MyComparator());
+     SerializationTest.verifySelf(new SomeSerializableClass(),
+     new MyComparator());
 }
-		
-

-

- 3) Negative testing
+

+ + +

Negative Testing

TBD -

-

- Interface SerializableAssert
- A test has to implement the interface in case if class of object(s) - to be compared doesn't have equals(Object) method or the testing - framework can not find appropriate comparator. The interface has only - one method to be implemented:

- - void assertDeserialized(Serializable reference, Serializable test); - -

+ + +

Interface SerializableAssert

+

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:

+ +
void assertDeserialized(Serializable reference, Serializable test);
+ +
- +

- The resource files should follow the next conventions: + The resource files should follow the next conventions:

  • Root folder for resource files is <module root>/src/test/resources/serialization
  • -
  • Relative path to a resource file MUST match a test's package name. +
  • Relative path to a resource file MUST match a test's package name
  • -
  • A resource file MUST start with a test's name. +
  • A resource file MUST start with a test's name
  • -
  • A resource file MUST contain keywords pointing out to testing scenario. +
  • A resource file MUST contain keywords pointing out to testing scenario
    1. <golden> keyword is used for files generated on RI
    2. <harmony> keyword is used for files generated on - Harmony implementation. + Harmony implementation
    3. <negative> keyword is used for files that contain - broken serial form. + broken serial form
  • -
  • A resource file name MUST contain some index.
    - Note: if there is only one file the index is not required +
  • A resource file name MUST contain some index +

    Note

    +

    If only one file exists, the index is not required.

    +
  • -
  • Extension for resource files is 'ser'. -
  • - -
- - For example, for test org.apache.harmony.tests.java.lang.SomeClassTest we have following: -
-
+			
  • Extension for resource files is ser + +

    Example

    +

    For the test org.apache.harmony.tests.java.lang.SomeClassTest, + we have the following resource files:

    +
     modules/luni/src/test/resources/serialization
          |
          \---org/apache/harmony/tests/java/lang
    @@ -190,10 +191,9 @@
                   SomeClassTest.harmony.0.ser
                   SomeClassTest.harmony.1.ser
                   SomeClassTest.negative.ser
    -		
    -
  • + -

    +
    Index: xdocs/subcomponents/classlibrary/testing.xml =================================================================== --- xdocs/subcomponents/classlibrary/testing.xml (revision 466968) +++ xdocs/subcomponents/classlibrary/testing.xml (working copy) @@ -21,13 +21,13 @@ - Testing conventions in the Apache Harmony Classlib + Testing Conventions in the Apache Harmony Classlib Harmony Documentation Team -
    +

    This document describes PROPOSED placement and package naming conventions for different types of Harmony class library tests. @@ -38,96 +38,91 @@ adapted/modified to reflect module specifics.

    - See also: Framework for testing serialization + See also: Framework for Testing Serialization

    - +

    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 -

    - <modulename>/src/test -
    - Tests that are specific for Harmony, testing Harmony implementation details, and may fail + classes are located under:

    +
    <modulename>/src/test
    +

    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. -

    - <modulename>/src/test/impl - Harmony specific tests
    - <modulename>/src/test/api - Implementation-independent tests -
    - Special-purpose tests like stress tests or tests that require special configuration are - separated from general-purpose tests. -
    - <modulename>/src/test/stress -
    + tests that must pass on RI and all conformant implementations.

    + +
    <modulename>/src/test/impl - Harmony specific tests
    +<modulename>/src/test/api - Implementation-independent tests
    + +

    Special-purpose tests like stress tests or tests that require special configuration are + separated from general-purpose tests.

    +
    <modulename>/src/test/stress
    + - Tests are not separated by functionality under test, e.g. tests against clone() +

    Tests are not separated by functionality under test, for example, tests against clone() methods are not separated from tests against equals() methods. - Classpath tests are separated from bootclasspath tests on a directory level: -

    - <modulename>/src/test/api/java - Classpath tests
    - <modulename>/src/test/api/java.injected - Bootclasspath tests
    -
    - More details below.

    + Classpath tests are separated from bootclasspath tests on a directory level:

    + +
    <modulename>/src/test/api/java - Classpath tests
    +<modulename>/src/test/api/java.injected - Bootclasspath tests
    + +

    Find more details + below.

    - Some modules might have platform specific tests that are in the case separated on a directory - level: -
    - <modulename>/src/test/api/common
    - <modulename>/src/test/api/windows
    - <modulename>/src/test/api/linux -
    -

    +

    Some modules might have platform specific tests that are in the case separated on a directory + level:

    + +
    <modulename>/src/test/api/common
    +<modulename>/src/test/api/windows
    +<modulename>/src/test/api/linux
    + +
    - +

    - If the test is designed to be run from bootclasspath then its package is the same - as the package of the class under test + 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.

    - If the test is designed to be run from classpath then:
    - If the package under test belongs to a public package (i.e. that is a part of the API specification) - then the test's package is -

    - org.apache.harmony.<modulename>.tests.<package under test> -
    - Example: -
    - org.apache.harmony.luni.tests.java.lang
    - org.apache.harmony.crypto.tests.javax.crypto
    - org.apache.harmony.auth.tests.org.ietf.jgss -
    + If the test is designed to be run from classpath then:

    +
      +
    1. 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: +
      org.apache.harmony.<modulename>.tests.<package under test>
      +

      Example

      + +
      org.apache.harmony.luni.tests.java.lang
      +org.apache.harmony.crypto.tests.javax.crypto
      +org.apache.harmony.auth.tests.org.ietf.jgss
      +
    2. +
    3. If the package under test belongs to org.apache.harmony + namespace so that class's package is: +
      org.apache.harmony.<modulename>.<rest of the package name>
      + then the test's package is: +
      org.apache.harmony.<modulename>.tests.<rest of the package name>
      +

      Example

      +

      + org.apache.harmony.luni.internal.net.www.protocol - package under test
      +org.apache.harmony.luni.tests.internal.net.www.protocol - package for the test

      + +
    - If the package under test belongs to org.apache.harmony namespace so that class's package is -
    - org.apache.harmony.<modulename>.<rest of the package name> -
    - then the test's package is -
    - org.apache.harmony.<modulename>.tests.<rest of the package name> -
    - Example: -
    - org.apache.harmony.luni.internal.net.www.protocol - package under test
    - org.apache.harmony.luni.tests.internal.net.www.protocol - package for the test -
    - - -

    +

    - To avoid collision of test results for various type of tests, test type might be reflected in test name - for example, to separate impl test results from api test results impl test names end with - _ImplTest -

    - javax.crypto.CipherTest - Implementation independent bootclasspath test for javax.crypto.Cipher
    - javax.crypto.Cipher_ImplTest - Implementation specific bootclasspath test for javax.crypto.Cipher
    -
    + To avoid collision of test results for various type of tests, reflect a test type in a test name.

    +

    Example

    +

    To separate the impl test results from + the api ones, the impl test names end with + _ImplTest:
    + javax.crypto.CipherTest - Implementation independent bootclasspath + test for javax.crypto.Cipher
    +javax.crypto.Cipher_ImplTest - Implementation specific bootclasspath +test for javax.crypto.Cipher

    -

    +