• ClasspathDecisionsPage

This page lists issues that summarize the result/outcome of decisions that been made on the mailing list or IRC (#classpath at irc.freenode.org). If you add new issues please file them respectively under Programming or Non-Programming related.

Index

Non-Programming related

Clickthrough licenses

• Last edit: 2005-01-10 rschuster
• Description:
  • When working on a Free implementation of a Java API you might stumble over a so-called clickthrough license that wraps a document you want to read. This situation often happens when your are searching the JCP for JSR specifications.
• Outcome:
  • In any case try to avoid a clickthrough license. Search for publicly available documentation (no license wrapped around) and do not refer to proprietary documentation. A good idea is refer to books or public online articles instead.

  • If you find yourself in a situation where only by accepting a license you can write a conforming implementation, then mail a link to the license along with a description why you think you need to accept it to the maintainer of GNU Classpath. The problem will then be resolved with the help of FSF legal.

    The download agreements of the <= Sun JDK 1.5 and its documentation are OK to be accepted. However you should delete the file containing the sourcecode of the JDK to avoid any hassles.

• References:

  • Initial request whether a license on jcp.org can be safely accepted.

  • Request whether the download agreement of the JDK do not constitue a NDA

Programming related

JNI independence through the VM interface

• Last edit: 2005-04-05
• Description:

  • The Java Native Interface (JNI) is a mean to bridge C/C++ with the Java world. It is the official specification for native interaction and GNU Classpath strives to support it. However there is software using the Java class library which will not support JNI by nature and we are going to support them, too. As an example have a look at the Java-based operating system JNode.

• Outcome:
  • In order to support this idea, it is a projected long-term goal to use the VM interface for this kind of JNI independence. Currently we have a mix of classes which are JNI-independent via the VM interface while others are still using native methods directly. Any help in this effort is appreciated and we are seeking for volunteers on this job.

    This kind of abstraction allows integration of CNI, too.

• References:

  • Wrapping native methods as a long-term goal

How to deal with stub implementations

• Last edit: 2005-01-11 rschuster
• Description:

  • GNU Classpath misses a lot of functionality of the official implementation. For some time it was common practice to implement methods with no real functionality (returning  null ,  0  or  false ). These methods are known as stub methods. They began to annoy users when their programs seemed to work first but finally crashed because of error propagation.

• Outcome:

  • To quote Jeroen there is only one short answer is: grep FIXME and start hacking :) A stub method is not considered in any way better than a missing method. Lengthy dicussions have taken place and considered throwing certain kinds of exceptions but no agreement could be reached.

  • There are only two agreements on stub methods:

    • They must be documented by FIXMEs to be easily found by tools like  grep .

    • They are inherently evil and must be implemented.
• References:

  • First discussion in 2003

  • Second discussion in 2003

  • A third approach in 2004

  • The agreement

Support for 1.5 API

• Last edit: 2005-04-14 gnu_andrew
• Description:
  • The question was raised whether features of the 1.5 API should be already included in GNU Classpath.
• Outcome:
  • In short: Getting pre-1.5 features stable has precedence before adding new stuff. However nobody is objected if you add a method or new constructor that was added in 1.5 and does not depend on the new language features. In case that the new API changes the existing one in a binary compatible way (e.g. access modifier changed from protected to public) you should add a "@specnote" tag describing the change. Since August 2004 GNU Classpath has a branch where API relying on the new language features can be committed. There was an agreement on its two lifetime criterias:
    1. A majority of Classpath-using VM implementors agree that they have access to a compiler suitable for compiling the branch.
    2. A majority of Classpath-using VMs can actually use this version of Classpath, though perhaps not perfectly. (In particular here it may be probably ok if the new reflection code does not work - the VM will still be able to bootstrap, it just won't implement all of 1.5 faithfully.)
    To find out what "the majority of Classpath-using VMs" actually is, a discussion was suggested to be held when the branch is ready.

    If you want to checkout the sources use the branch generics-branch of the module classpath. This branch is currently only buildable using the Eclipse compiler, ecj, due to the use of the new language features. It has also been successfully tested at run-time using JamVM 1.3. Tom Tromey currently develops the experimental compiler GCJX that among other things aims to support the Java5 language features. The development moved to gcc.gnu.org on January 16th 2005 in a branch called 'gcjx-branch' of the GCC.

• References:

  • Request on when 1.5 API will be supported in GNU Classpath

  • Old project page for GCJX on sourceforge

  • Announcement of the generics branch

  • generics branch (ViewCVS)

Locale implementation

• Last edit: 2005-01-16 rschuster
• Description:
  • GNU Classpath' implementation of locales has undergone many changes. This issue displays the present situation and the plans for the future.
• Outcome:

  • The locale data for GNU Classpath is currently being auto-generated using the data provided by the CLDR project. CLDR provides locale data in XML files using LDML version 1.2. The tools gnu.localegen and gnu.currencygen written by Guilhelm Lavaux convert that data into a format suitable for GNU Classpath (These tools are located in the CVS module "cp-tools".)

    By calling gnu.localegen with an URI to the XML file(s) Java source files named LocaleInformation_*.java are created in the current directory. These files need to be moved into the gnu.java.locale package of GNU Classpath. Using that technique we (should) support all 255 locales that are provided by CLDR.

    The default values for all locales in gnu.java.locale.LocaleInformation are maintained manually. We need to write a tool or improve an existing one to parse the root.xml file provided by CLDR. Additionally CLDR has an extra XML file with collation rules for which we have no parser currently. We still use the old collation rules in our locale informations.

    There are still some bugs in our class library with handling Locales. Michael Koch will work on them and they will hopefully be fixed soon. Please send bugs dealing with our locale data or it's handling to this list or to the bug tracker.

• References:

  • Michael Koch about latest achievements on locale data generation

  • Localization chapter in GNU Classpath Hacker's Guide

Implementing OutOfMemoryError handling

• Last edit: 2005-01-24 rschuster
• Description:

  • Handling the OutOfMemoryError properly is one of the critical aspects of a VM implementation. Rather than giving the one right way to do it, this issues describes the approaches taken by others.

• Outcome:

  • Go the stacktrace-less route: Only throw the OutOfMemoryError and do not provide and entire stack trace with it. That way one can get away with a single instance of the error per entire JVM, as it has no state. One can try to fit stack in there - but the place for it has to be preallocated. Memory usage can start to sum up if one will preallocate it for every thread out there. However this looks like optimizing for very rare case and making more garbage in the heap that it is needed for all normal runs.

    Approach taken by JCVM:

    1. For all exceptions that can be instantiated by the VM itself, there is a single stacktrace-less "backup" instance. This instance is thrown in a thread when we try to instantiate a normal instance but the same exception is triggered recursively. This idea is borrowed from SableVM and prevents any infinite loops when instantiating exceptions within the VM (recursive exceptions within normal Java code are OK).

    2. When a heap allocation fails, we perform up to 3 garbage collector cycles to try to make memory available:
       • The first GC cycle is normal: Only weak references are cleared.
       • The second GC cycle enables clearing soft references, too.
       • Before the third GC cycle, we run the finalizer.

       If all 3 attempts fail, we then set the per-thread "out of memory" flag (see #3) and then instantiate and throw an OutOfMemoryError.

    3. A small percentage of the heap is reserved. The reserved portion of the heap is only available to threads with the "out of memory" flag set. When a GC cycle occurs, all "out of memory" flags for all threads are cleared. But if a thread has already started its 3 GC attempts (see #2) then it won't notice this flag being cleared until the current allocation attempt completes.

    • The net result is that OutOfMemoryErrors are thrown very reliably, with stack traces, because they get to draw from the reserved area. Also, because of the multiple GC attempts, typically only one thread will throw an OutOfMemoryError. When it does, it frees up memory that other threads can then use, so they don't throw one also.

      Also, the "out of memory" flag is not cleared in a thread until the next GC cycle. If you clear it too soon (e.g., immediately after you create the OutOfMemoryError instance), then often the thread will throw another one. The extra time gives it a chance to "clean up" after itself before restricting it back to the non-reserved portion of the heap.

    Sidenote: J2ME CLDC VMs are not required to handle  Error  via the exception handling

mechanism, which kind of implies that other VMs should try to do so.

• References:

  • Question about OOME handling

  • GNU Classpath FAQ entry about OOME handling

Use the former Corba COST project for testing Classpath CORBA implementation

• Last edit: 2005-06-04 audriusa

• Description: The SourceForge contains a large project, called Corba COST (http://sourceforge.net/projects/corba-cost/). It contains a numerous CORBA tests, written by various development groups.

• Outcome: In README the maintainer, Duncan Grisby, writes:
  • CORBA Open Source Testing. This source tree contains several test suites for CORBA implementations in C++ and Java. The code originally came from the OMG's CORBA Open Source Testing project, which lived at cost.omg.org. That site no longer exists. All the contributing companies agreed to release their tests under the terms of the GNU Lesser General Public License, available in the file COPYING.LIB.
  • Audrius Meskauskas suggested to use that code in the Mauve project for testing Classpath CORBA implementation but decided to ask for the list opinion, as the code is probably not written by the current maintainer.
  • Tom Tromey said he thinks we can take this project at its word, unless we have some particular reason to suspect it. Also, since it is a test suite we are less concerned about it, as we aren't going to ship it, just use it for testing.
  • The decision was accepted to start using classes from this project. This includes adaptation for the Mauve environment, removing tests that are not yet supported by Java 1.4 API and adding such adapted classes into Mauve project. LGPL allows to use the modified content under GPL. The classes from this project will contain a marker string "cost.omg.org" that can be used to remove them later if any problems appear.

Usage of assertions

• Last edit: 2005-09-18 rschuster

• Description: Since a long time the usage of the assert statement in GNU Classpath' code was not possible because GCJ was not able to compile it correctly.

• Outcome:

  • With the snapshot release 0.18 GNU Classpath dropped support for GCJ below version 4.0.0 and so the usage of assert is possible and encouraged.

• References:

  • http://lists.gnu.org/archive/html/classpath/2005-09/msg00099.html

  • Hints on Java's 'assert'