JTF > Rationale > The JTF Subset

Chapter 9
The JTF Subset

In the public announcement of the ACM Java Task Force at SIGCSE 2004, the first item included in our list of deliverables was

A definition of a subset of the standard Java APIs appropriate for first-year computer science. This subset would involve restricting both the number of classes used as well as the number of public methods made visible within those classes. Note that this subset must be sufficient to have students write significant applications using Java. To this end, it will presumably be a superset of the AP Java subset [Astrachan00], which seeks to define what aspects of the language will be tested on the AP exam. [Roberts04b]

This task is clearly a perilous one, particularly given that any decisions we make are sure to upset those instructors who feel compelled to use some piece of the standard Java API that did not make it into the Task Force subset. At the same time, it is also true that the Task Force has a responsibility to provide guidance in this area. In a very real way, the most significant problem with Java is not any of the specific shortcomings that we have sought to address with the ACM packages but rather the enormous scale of the languages and its APIs.

In some ways, however, the issue can be made less contentious by redefining the goal. Rather than defining any sort of official “standard,” our current strategy is to define a subset that we agree to support as effectively as possible. That support has three components:

1. Define a set of the classes from the standard Java packages that we agree to use in our own development of JTF materials. We will then agree to use only those classes in any publications, online tutorials, downloadable examples, and extension packages. That subset is described in section 9.1.

2. Create documentation for the JTF subset that is more student-friendly than the existing javadoc material. The simplified javadoc design appears in section 9.2.

3. Enable implementors who stay within the JTF subset to make their code compatible with older versions of the JDK dating back to the 1.1 implementation. The strategies that make this goal possible were described in section 6.9 earlier in this document.

9.1 The JTF subset

Figure 9-1. Java classes that form the preferred JTF subset

java.applet:    Applet    AudioClip java.awt:    BorderLayout    Color    Component    Container    Dimension    Event    FlowLayout    Font    FontMetrics    Frame    Graphics    GridLayout    Image    LayoutManager    MediaTracker    Point    Rectangle    Toolkit java.awt.event:    ActionEvent    ActionListener    AdjustmentEvent    AdjustmentListener    ComponentEvent    ComponentListener    FocusEvent    FocusListener    KeyEvent    KeyListener    MouseEvent    MouseListener    MouseMotionListener    WindowEvent    WindowListener java.io:    BufferedReader    BufferedWriter    File    FileReader    FileWriter    IOException    PrintWriter    Reader    StreamTokenizer    StringReader    StringWriter    Writer java.lang:    Boolean    Character    Class    Cloneable    Comparable    Double    Enum    Float    Integer    Long    Math    Number    Object    Runnable    String    System    Thread java.math:    BigInteger java.net:    URL    URLConnection java.text:    DateFormat    DecimalFormat    NumberFormat java.util:    ArrayList    Arrays    BitSet    Collection    Comparator    HashMap    HashSet    Iterator    LinkedList    List    ListIterator    Map    PriorityQueue    Random    Scanner    Set    SortedMap    SortedSet    Stack    StringTokenizer javax.swing:    Box    BoxLayout    ButtonGroup    JApplet    JButton    JCheckBox    JComboBox    JComponent    JDialog    JFileChooser    JFrame    JLabel    JList    JOptionPane    JPanel    JPopupMenu    JRadioButton    JScrollBar    JScrollPane    JSlider    JSpinner    JTable    JTextArea    JTextField    JTextPane    JToggleButton    JWindow    KeyStroke    Timer javax.swing.event:    ChangeEvent    ChangeListener    ListDataEvent    ListDataListener    ListSelectionEvent    ListSelectionListener

In putting this list together, we undertook a mechanical survey of the code that is published on the web for several of the leading text books to see what classes they used. This survey provided us with considerable insights into how classes are used, but required some analysis to separate out various artifacts from the useful data. For example, one of the leading classes on the list is java.lang.StringBuffer, not because these textbooks refer to it directly, but because Java compilers generate references to StringBuffer (or its newer StringBuilder counterpart) whenever they process string constants. Thus, it was important to analyze the data and look for this type of outlier. In the end, we used the list developed by the automatic survey as a “sanity check” on our own consideration as to what classes one might reasonably present in the first-year curriculum.

We expect that this list will evolve slowly over time, but believe that it is likely to remain stable through the official release of the materials in spring 2006.

9.2 Simplifying the javadoc presentation

A public web site containing an updated javadoc reference manual for the approved Java subset. This web site would make it possible for students to browse the standard classes and methods defined in the subset without being overwhelmed by classes, methods, and concepts they are unlikely to use. For the classes and methods that are included, the web site will contain more examples and tutorial material than is currently supplied with the Java APIs.

After all, given that Java’s corporate creator assures us that “the network is the computer,” what matters is what’s described on the web rather than a standard buried in a bookcase somewhere.

Our proposal to use the javadoc documentation to define the JTF subset includes the following goals:

1. Create a web site for the Task Force that includes an abridged form of the standard Java documentation called the student view from which classes and methods unlikely to be used in an introductory course have been eliminated. The student view contains pointers to the complete view, which contains the full documentation.

2. Publish the documentation of the Java Task Force packages using the same split between the student and complete views. Students can browse a less overwhelming collection of documentation, while teachers and advanced users have access to the full capabilities of the class.

3. Make available the tools we use to produce the documentation, including the driver files that determine which parts of the complete documentation are included in the student view. In that way, any adopter who feels that something is missing can generate new documentation in which that class or method has been restored. And, perhaps more important in practice, instructors who believe that the Task Force has revealed too much can generate even more compact documentation that covers only the elements used in the local curriculum.

The current draft release of the Task Force materials implements the split between the student and complete view only for the documentation of the ACM packages. When you go to the web site, you come up in the student view. Each page in the student view contains a link in the navigation bar to the complete view for the same page (and vice versa), making it very easy to move back and forth between the two views. The primary characteristic of the student view is that it hides extraneous information. Figure 9-2, for example, shows the top of the page in the student view for the GLabel class in acm.graphics. What you see in the figure looks familiar enough and also illustrates the level of documentation we plan to associate with each of the classes. But what’s more important is what you don’t see. You don’t, for example, see a navigation tab directing you to the discussion of inner classes or deprecated methods. Similarly, you don’t discover that GLabel implements the mysterious interfaces Cloneable and Serializable. You do, of course, see these features in the complete view, but they are not getting in the way here.

Figure 9-2. Beginning of documentation page for the GLabel class Another important change in the student documentation view is that any inherited methods that the documentation designer chooses to include are listed in the summary section using a format similar to that of the methods implemented by this class. This feature is illustrated in Figure 9-3, which shows the first few entries in the summaries of the locally defined methods and those that are inherited from superclasses. These methods tend to have equal weight in the student’s mind, and it is useful to present them symmetrically. Contrast the view shown in Figure 9-3 with the standard presentation shown in Figure 9-4. In that form, the student has no sense of the structure of these methods and is exposed to several—the three versions of wait are an obvious example—that offer no help to novices.

Figure 9-3. Selections from the GLabel method summary

Figure 9-4. Standard javadoc presentation of inherited methods

The only other significant change in the student view is the inclusion of a “usage” line in the detailed presentation of methods, preceding the declaration of parameters and results. Student find a paradigmatic example extremely useful, particularly when they can cut it out of the documentation and paste it into their own code. This line is illustrated in Figure 9-5.

Figure 9-5. Standard javadoc presentation of inherited methods

Final Report—July 31, 2006