Making Java Signatures Simple

Methods have names. For example, System.out.println() is usually called "print line", though we'd probably say "system-out-print line" for it as I've written it here.

Unfortunately, the word "name" doesn't have a technical meaning. And even if we gave it one, it might lead to misunderstanding when we're switching back between technical terms and nontechnical ones. So there's a technical term for names of methods in Java: signatures.

The way we've used "name" above refers to the same thing as the Java term "simple signature." The simple signature of a method is its text name, ignoring everything in the parentheses, its return type, and so on. So println() and println(String) have the same simple signature.

The full signature, which is what we mean when we just say "signature", includes the full typing of the method and its parameters. So the full signature includes the type or class of everything in the parentheses of the method as well as the name of the method. This is what Java looks at when it's compiling.

That's why you get a runtime error if you do the following:

public static void main(){
...

The Java compiler will compile this just fine. It will create a .class file with a method that's got the signature main().

Then when you try to run it, the JRE will look for a method with the signature main(String[]), that is, a method with the text name main followed by a parameter list that includes an array of strings. If the array of strings isn't there, it doesn't match the signature that the JRE is looking for. So you get an error when you try to run your program. This will also happen if you do this:

public static void main(String arg){
...

You've got a method whose signature is main(String) not main(String[]), that is, its parameter is a String, not an array of Strings.

An example of methods that have the same name but different signatures are the constructor methods for the Color class. You can create a new Color in any of several different ways:

Color(int r, g, b)
Color(int r, g, b, a)
Color(int rgb)
Color(float r, g, b)
and so on.

In the first we give the constructor three different integer values for the red, green, and blue values of the new Color. In the second we give four integer values--the same three as before plus an alpha (transparency) value. Or we can pass one integer value that has all three of the red, green, and blue values in one number. Or we can pass separate red, green, and blue values as floating point numbers rather than integers. There are more ways, yet.

While all these constructors have the same name, or simple signature ("Color"), they each have a different signature based on their parameter list. That way Java is able to tell them apart, and know what value types it should expect to work with. That way if you give two values as integers, and a third as a floating point value Java will realize it doesn't know how to deal with that and recognize an error in the code.

That means when you're calling a method, and the compiler spits it out and says it's not found you need to make sure you've:

1. spelled the name right,
2. got the right type and number of parameters,
3. and imported the appropriate packages and classes.

Java's Documentation: A Closer Look

I started discussing the place to look up Java's classes and methods in Java's Reference Manual and the place to look up the language's syntax and elements in The Java Language Manual. Here I'm going to take a deeper look at the documentation of Java's classes, interfaces, and so on in the the Java API Reference.

At first glance the page that's presented to you by the API reference can be overwhelming. Too much information!

First let's look at what's in each panel. If you don't have the API reference open in another tab or window of your browser, open it now. I'll be referring to what you see. The link is the Java API Reference. Bookmark it. Put it on your bookmark bar. Don't tattoo it on your forearm, though--there'll be a new URL when a new version of Java hits the streets and you'd be really embarassed to walk around with an old URL tattooed on your arm, wouldn't you? Writing it on a sticky and putting it on your monitor's bezel is probably good enough.

In the upper left frame, we have the list of packages. So far so good. If you know what package has what you're looking for in it, you can reduce the stuff listed elsewhere a lot by clicking on the name of the package. For example, JFrame is in javax.swing. If you click on javax.swing in the upper left frame, you'll see a change in the display. Now only the classes, interfaces, and enums and exceptions defined in javax.swing are listed in the lower left frame. It's a much smaller list to scroll through. If you don't know the package you're looking for, then you'll just have to go through the long list, which is in alphabetical order.

In the upper left frame, click on "All Classes" at the top of the list to list all the classes, interfaces, enums, and exceptions in the API again.

Once you find your class on the lower left, you'll get its documentation in the main panel on the right. This can be overwhelming as well. Since we've already talked about JFrame, let's look at it. Click on JFrame in the lower left panel. You can select javax.swing in the upper left panel first to make selecting JFrame easier if you wish.

In the main window, you'll see the big title "Class JFrame". Immediately above that in small type is the package it is in. If you didn't already know that JFrame is in javax.swing, now you would know. Remember the package for when you think you're going to look something up again later. Or, if you want to include a class and don't know what package to import, this is a good way to find out.

Beneath Class JFrame you'll see a list of other classes with little stairsteps leading down from one to another. These are the parent classes of JFrame, from the most basic object class in Java, java.lang.Object to JFrame itself. JFrame inherits from all these classes. Every method and field that they have, JFrame has, too.

You can see the documentation for any of them by simply clicking on the class's name. But don't just yet, we're going to look at more of JFrame's documentation first.

Next down the page is the list of interfaces that JFrame implements. This means that JFrame has the methods implemented in it that these interfaces call for. There's a lot more to an interface than this, but that's a subject for another time. In essence, JFrame inherits the functions of these interfaces by implementing the methods they define.

Below the line, we have a text description of JFrame headed by a pseudocode definition of JFrame. Some of these text descriptions in Java's API Specification are very useful, others are less useful. The one for JFrame is middle of the road. Like many descriptions, it comes in at the middle of the story, assuming that you have complete and perfect familiarity with some other part of Java that isn't what you're looking up here. This results in some look-ups turning into searches for the start of the story. You look up JFrame, it refers to Frame, then you go back to Window to understand what they're talking about in java.awt.Frame's documentation. Then you're reading all about java.awt.Component, and so on. Before you know it, you're looking at java.lang.Object and wondering what your original question was, and where all the time has gone.

So don't rely to heavily on these. Scan them, but if you're not getting what you want, keep moving down. Usually the later parts of the section are far more informative and direct. If there's some meta-information you're looking for on a class, check the related tutorial at Sun, or do a web search and look for a good intro or tutorial article. (You might even scroll down below my articles to where I keep a long index to my articles.)

I'm going to skip on down past the Nested Class Summary and list of nested classes inherited, too, and jump right into the Field Summary below them.

Fields are the variables and constants defined for the class. The first listed have been defined directly in this class. The listing tells you what they've been defined as, and their purpose. Following that is a list of ones inherited from each of the parent classes.

The Constructor Summary tells you what constructors are available for this class. If you were hoping for a JFrame constructor that lets you set it visible and give it a size right at the outset, you'll see you're out of luck. JFrame's constructors only allow you to define either or both of the JFrame's title and graphics configuration when it's instantiated (that is, when the Constructor makes a new one.) So you'll have to set the size and visibility later.

How you set size and visibility, and do a bunch of other things with a JFrame comes next. They're part of the Method Summary. First there's the list of methods defined in JFrame. These are the new methods that JFrame adds to its parents' methods. Each lists its type and name and parameter list along with a brief description. Following comes the long, long list of inherited methods. JFrames have all these methods, too, but their description lies in the document page for the class they were originally defined in. Click on their name to go there.

Following this come the detailed descriptions of JFrame's fields and methods. You could have gotten here the fast way by clicking on one of the field or method names in the summaries above. These are the real meat of the Java API specification. They tell you how to use the class methods, and what they do. Once you know them, the short description in the summary will usually be enough for you (if you need even that.)

Having the whole document hyperlinked makes it far more useful than a paper document would be. There'd just be too much page-flipping.

If you want to have a copy right on your own machine, you can download the entire thing. The PDF is available from Sun for Java 6, or you can get it for different versions from links on the Java SE reference page.

That way you don't have to be on the network all the time, or held hostage to the speed of your connection to look up something.