The information on these pages may be out of date, or may refer to
resources that have moved or have been made read-only.
For more information please refer to the Apache Attic
The following guidelines are currently PROPOSED and being discussed on the
development mailing list
direct comments and questions there.
The Harmony project class library ("classlib") 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.
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 the latest official release of the Java SE 5.0 RI.
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.
The following general guidelines apply when developing class library code for Apache Harmony:
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.
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.
Harmony classlib 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.
Generally, we could refer to the following steps.
If RI throws
we can throw
The Harmony class library code aims to be serialization compatible with the reference implementation (RI).
The Java Specification describes the serialized form of many Java types. Where given, classlib will follow the specified serialized form. When the serialized form is NOT 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 classlib code, and vice versa.
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.
To indicate that we are serialization-compatible we define an explicit Stream Unique Identifier (SUID) in each of the Harmony classlib serializable types that is equal to the SUID of the corresponding type in the RI.
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.