Generic Methods

You can put an object in a Box by invoking put, which returns false if the box is already full. You can get something out of a Box by invoking get, which returns a null reference if the box is empty.

If put and get were not synchronized, and two threads were executing methods for the same instance of Box at the same time, then the code could misbehave. It might, for example, lose track of an object because two invocations to put occurred at the same time.

8.4.4 Generic Methods

A method is generic if it declares one or more type variables (§4.4).

These type variables are known as the type parameters of the method. The form of the type parameter section of a generic method is identical to the type parameter section of a generic class (§8.1.2).

A generic method declaration defines a set of methods, one for each possible invocation of the type parameter section by type arguments. Type arguments may not need to be provided explicitly when a generic method is invoked, as they can often be inferred (§15.12.2.7).

The scope and shadowing of a method's type parameter is specified in §6.3.

8.4.5 Method Return Type

The result of a method declaration either declares the type of value that the method returns (the return type), or uses the keyword void to indicate that the method does not return a value.

Result:

Type

void

Return types may vary among methods that override each other if the return types are reference types. The notion of return-type-substitutability supports covariant returns, that is, the specialization of the return type to a subtype.

A method declaration d1 with return type R1 is return-type-substitutable for another method d2 with return type R2, if and only if the following conditions hold:

•If R1 is void then R2 is void.

•If R1 is a primitive type, then R2 is identical to R1.

•If R1 is a reference type then:

226

CLASSES Method Throws 8.4.6

An unchecked conversion is allowed in the definition, despite being unsound, as a special allowance to allow smooth migration from non-generic to generic code. If an unchecked conversion is used to determine that R1 is return-type-substitutable for R2, then R1 is necessarily not a subtype of R2 and the rules for overriding (§8.4.8.3, §9.4.1) will require a compile-time unchecked warning.

8.4.6 Method Throws

A throws clause is used to declare any checked exception classes (§11.1.1) that the statements in a method or constructor body can throw (§11.2.2).

Throws:

throws ExceptionTypeList

ExceptionTypeList:

ExceptionType

ExceptionTypeList , ExceptionType

ExceptionType:

ClassType

TypeVariable

It is a compile-time error if any ExceptionType mentioned in a throws clause is not a subtype (§4.10) of Throwable.

Type variables are allowed in a throws clause even though they are not allowed in a catch clause.

Example 8.4.6-1. Type Variables as Thrown Exception Types

import java.io.FileNotFoundException;

interface PrivilegedExceptionAction<E extends Exception> { void run() throws E;

}

class AccessController {

public static <E extends Exception>

Object doPrivileged(PrivilegedExceptionAction<E> action) throws E { action.run();

return "success";

}

}

227

8.4.7 Method Body CLASSES

class Test {

public static void main(String[] args) { try {

AccessController.doPrivileged(

new PrivilegedExceptionAction<FileNotFoundException>() { public void run() throws FileNotFoundException {

// ... delete a file ...

}

});

} catch (FileNotFoundException f) { /* Do something */ }

}

}

It is permitted but not required to mention unchecked exception classes (§11.1.1) in a throws clause.

The relationship between a throws clause and the exception checking for a method or constructor body is specified in §11.2.3.

Essentially, for each checked exception that can result from execution of the body of a method or constructor, a compile-time error occurs unless its exception type or a supertype of its exception type is mentioned in a throws clause in the declaration of the method or constructor.

The requirement to declare checked exceptions allows a Java compiler to ensure that code for handling such error conditions has been included. Methods or constructors that fail to handle exceptional conditions thrown as checked exceptions in their bodies will normally cause compile-time errors if they lack proper exception types in their throws clauses. The Java programming language thus encourages a programming style where rare and otherwise truly exceptional conditions are documented in this way.

The relationship between the throws clause of a method and the throws clauses of overridden or hidden methods is specified in §8.4.8.3.

8.4.7 Method Body

A method body is either a block of code that implements the method or simply a semicolon, indicating the lack of an implementation.

MethodBody:

Block

;

It is a compile-time error if a method declaration is either abstract or native and has a block for its body.

It is a compile-time error if a method declaration is neither abstract nor native and has a semicolon for its body.

228