This package "contains" other packages that specify parts of the JDK, and other libraries for JML.

Conventions

We use the following conventions for the specifications.

Copyright

The copyright for the specifications should be the LGPL, not the usual GPL. This is so that some clients can use the JML runtime library for commerical code. See (or copy) the file ../org/jmlspecs/lgpl-copyright-for-java.txt for the text to use.

No code

Don't copy any method bodies or other executable code (such as initializer blocks) into the specifications. Code is certainly something that we need to avoid due to copyright issues.

For the same reason, don't copy the javadocs into the specifications.

No incomplete interfaces

It's important that you don't add a specification for a type that is incomplete. That is, don't give the interface for just a single method, but include all of the (public and protected) interface of each type you specify.

To deal with differences among JDK versions, you may have to include declarations for additional methods that are not in earlier versions of the JDK in your specification files.

The set of interfaces you specify should be closed in the sense that the tests pass without having to have other information available. In some cases this will mean you will have to specify extra types to allow the tests to pass.

Use .spec files for interfaces

At present the only types that we can compile with jmlc are interfaces. To do that automatically, use a .spec file for each interface instead of some other suffix. For other files, any suffix except .java is fine, but we suggest using .refines-spec or .refines-java.

Creation

Creating initial versions of these specifications can be done with the jmlspec tool. Use the --protected flag so that you get (only) the public and protected members and ignore the private and package visibility members.

Document the Normal Behavior

We suggest that you only specify normal behavior, at least at first.

Don't Specify package and private Features

You should only document public and protected features of these classes, and ignore package and private visibility features.

Ghost vs. Model

When in doubt about whether to use a ghost field or a model field, use a model field.

Imports

If an import is only used in the bodies of methods and other executable code, but is not needed in the code's interface, then you should remove it from the specification. In particular, this will allow us to keep references from the com.sun packages out of the specifications.