Brought to you by EarthWeb
ITKnowledge Logo Login Graphic Click Here!
Click Here!
ITKnowledge
Find:
 
EXPERT SEARCH ----- nav

EarthWeb Direct

EarthWeb sites: other sites

Previous Table of Contents Next


The API documentation

The javadoc documentation generally covers only the public and protected members of a class. This is not enough, especially when you’re trying to do things Java’s designers didn’t mean for you to do.

In particular, methods and fields that have default or package access may in fact be relevant to your classes. These are the members that do not have an access specifier; they are not declared as public, private, or protected. For example,

     int value;
     InputStream getData();
     Vector tokenize();

There are probably more members with package access in the classes in the Java class library than there are members with protected and private access combined. Methods and fields with no access specifiers are accessible only from within the package in which they’re declared.


Note:  In versions of Java before 1.1b3, although these package access members could be invoked only by other classes in the same package, subclasses in different packages could override these methods and fields. In these cases, another method in the package might call one of the overridden methods. The superclass’s behavior could be affected by the change in the overridden method, so by overriding a package member, you could change how any method that used the member behaved. Sun eventually decided this was a bug and fixed it in Java 1.1b3. This behavior is still present in virtual machines based on Java 1.0, however, and there are times when this is the best option. For example, you see in Chapter 12 that creating new encoders and decoders requires you to override these package access methods. In fact, the class was designed under the assumption that you would do this. Now that this is no longer possible, you have to create new classes in the sun.misc package instead.

Why bring this up now? Because often the only way to ensure that your overriding method does not unexpectedly interfere with the proper workings of a class is to carefully inspect the source code. By looking at the source, you can see what a method is supposed to do and what will change if you make it do something else.

Furthermore, although applets are expressly prohibited from adding new classes to existing packages, applications are not. When you build a stand-alone application, you can build it in such a way that you add new classes to existing sun or java packages. You can even completely replace existing classes if you prefer to use one of your own devising. It’s better to avoid this if you can, but there are times when you have no other choice. In Java 1.0, the only way to do a reverse lookup on an IP address (that is, to convert a dotted quad address like 204.178.32.1 into an Internet hostname like utopia.poly.edu) was to add a new package to the java.net package. You should try to avoid doing this if you can, but when you have to do it, you might as well do it right. The more you know about the internal workings of the classes with which you’ll be interfacing, the less likely you are to unintentionally break something else.


Note:  The bug that required this hack is fixed in Java 1.1.

What Versions of Java Are Covered?

You may rightly ask what versions of Java this book covers. The answer is “quite a few.” Although the documented parts of Java are well defined with version numbers and release dates, the undocumented parts described here are much less clear.

Nonetheless, I’ve chosen to focus on Java roughly as found in Sun’s JDK 1.1. I’ve chosen to focus on Sun’s JDK because it is the most widely distributed implementation of Java, especially when all of the other Java environments derived from it are factored in. Netscape’s Java virtual machine is based on Sun source code, for example. Even virtual machines that were written independently such as Roaster Technologies’ Roaster VM for the MacOS use Sun’s JDK class library with a few modifications.

I’m focusing on Version 1.1 because it’s the most current version of Java at the time of this writing. Even though right now 1.0.2 VMs are built into most Java-aware browsers, the life span of Java software is considerably shorter than the life span of Java books. The only way to avoid getting drowned by the fast-moving Java tidal wave is to stay as close to the front of the wave as possible. I expect that by the time you’re reading this, Java 1.1 will be in common use everywhere, and I hope that any further developments won’t make too much of what’s described here obsolete.

During the four months I spent writing this book, Sun’s Java JDK went through three beta releases and two release versions (1.0.2, 1.1b1, 1.1b2, 1.1b3, and 1.1), and this doesn’t even count any of the many releases by third parties. This has given me some practical experience at gauging what is and what is not likely to change. Surprisingly, I’ve discovered that the undocumented parts of Java change far more slowly than the documented parts.

Between 1.0.2 and 1.1, the .class file format and the virtual machine barely changed at all. The sun packages were expanded and some bugs were fixed, but very few classes were deleted or changed in incompatible ways. To the best of my knowledge, nothing in the sun classes was marked as deprecated, compared to many extremely common methods like action() and readLine() in the java packages. In fact, some of the sun classes appear to have been unchanged, aside from recompilations, since the 1.0 pre-beta. They probably would have lasted even longer had not changes to the language specification between alpha and beta broken more or less all of the existing source code. It does not appear that anybody is actively working on many of these classes. It therefore seems unlikely that they’ll change suddenly and unexpectedly.

Some Objections

Even the idea of Java SECRETS disturbs some people. Java is not supposed to need a book of secrets. It is supposed to be a truly open system that anyone can implement from freely available, well-documented specifications. It is supposed to provide everything a programmer needs. This is only partially true, however.


Previous Table of Contents Next
HomeAbout UsSearchSubscribeAdvertising InfoContact UsFAQs
Use of this site is subject to certain Terms & Conditions.
Copyright (c) 1996-1999 EarthWeb Inc. All rights reserved. Reproduction in whole or in part in any form or medium without express written permission of EarthWeb is prohibited. Read EarthWeb's privacy statement.