Method instruction
method name[([arglist])]
[visibility] [modifier]
[protect]
[returns termr]
[signals signallist];
where arglist is a list of one or more assignments, separated by commas
and visibility is one of:
inheritable
private
public
and modifier is one of:
abstract
constant
final
native
static
and signallist is a list of one or more terms, separated by commas.
The method instruction is used to introduce a method within a class, as described in Program structure, and define its attributes. The method must be given a name, which must be a non-numeric symbol. This is its short name.
If the short name of a method matches the short name of the class in which it appears, it is a constructor method. Constructor methods are used for constructing values (objects), and are described in detail in Methods and Constructors.
The body of the method consists of all clauses following the method instruction (if any) until the next method or class instruction, or the end of the program.
The visibility, modifier, and protect keywords, and the returns and signals phrases, may appear in any order.
Arguments
The arglist on a method instruction, immediately following the method name, is optional and defines a list of the arguments for the method. An argument is a value that was provided by the caller when the method was invoked.
If there are no arguments, this may optionally be indicated by an 'empty' pair of parentheses.
In the arglist, each argument has the syntax of an assignment, where the '=' and the following expression may be omitted. The name in the assignment provides the name for the argument (which must not be the same as the name of any property in the class). Each argument is also optionally assigned a type, or type and default value, following the usual rules of assignment. If there is no assignment, the argument is assigned the NetRexx string type, Rexx.
If there is no assignment (that is, there is no '=') or the expression to the right of the '=' returns just a type, the argument is required (that is, it must always be specified by the caller when the method is invoked).
If an explicit value is given by the expression then the argument is optional; when the caller does not provide an argument in that position, then the expression is evaluated when the method is invoked and the result is provided to the method as the argument.
Optional arguments may be omitted 'from the right' only. That is, arguments may not be omitted to the left of arguments that are not omitted.
Examples:
method fred
method fred()
method fred(width, height)
method fred(width=int, height=int 10)
In these examples, the first two method instructions are equivalent, and take no arguments. The third example takes two arguments, which are both strings of type Rexx. The final example takes two arguments, both of type int; the second argument is optional, and if not supplied will default to the value 10 (note that any valid expression could be used for the default value).
Visibility
Methods may be public, inheritable, or private:
- A public method is visible to (that is, may be used by) all other classes to which the current class is visible.
- An inheritable method is visible to (that is, may be used by) all classes in the same package and also those classes that extend (that is, are subclasses of) the current class.
- A private method is visible only within the current class.
By default (i.e., if no visibility keyword is specified), methods are public.
Modifier
Most methods consist of instructions that follow the method instruction and implement the method; the method is associated with an object constructed by the class. These are called standard methods. The modifier keywords define that the method is not a standard method -- it is special in some way. Only one of the following modifier keywords is allowed:
- abstract
An abstract method has the name of the method and the types (but not values) of its arguments defined, but no instructions to implement the method are provided (or permitted).
If a class contains any abstract methods, an object cannot be constructed from it, and so the class itself must be abstract; the abstract keyword must be present on the class instruction.
Within an interface class, the abstract keyword is optional on the methods of the class, as all methods must be abstract. No other modifier is allowed on the methods of an interface class.
- constant
A constant method is a static method that cannot be overridden by a method in a subclass of the current class. That is, it is both final and static (see below).
- final
A final method is considered to be complete; it cannot be overridden by a subclass of the current class. private methods are implicitly final.[1]
- native
A native method is a method that is implemented by the environment, not by instructions in the current class. Such methods have no NetRexx instructions to implement the method (and none are permitted), and they cannot be overridden by a method in a subclass of the current class.
Native methods are used for accessing primitive operations provided by the underlying operating system or by implementation-dependent packages.
- static
A static method is a method that is not a constructor and is associated with the class, rather than with an object constructed by the class. It cannot use properties directly, except those that are also static (or constant).
Static methods may be invoked in the following ways:
- Within the initialization expression of a static or constant property (such methods are invoked when the class is first loaded).
- By qualifying the name of the method with the name of its class (qualified by the package name if necessary), for example, using 'Math.Sin(1.3)' or 'java.lang.Math.Sin(1.3)'. Methods called in this way are in effect functions.
- By implicitly qualifying the name by including the name of its class in the uses phrase in the class instruction for the current class. Static methods in classes listed in this way can be used directly, without qualification, for example, as 'Sin(1.3)'. They may be still be qualified, if preferred.
In the reference implementation, stand-alone applications are started by the java command invoking a static method called main which takes a single argument (of type java.lang.String[]) and returns no result.
Protect
The keyword protect indicates that the method protects the current object (or class, for a static method) while the instructions in the method are executed. That is, the instructions in the method have exclusive access to the object; if some other method (or construct) is executing in parallel with the invocation of the method and is protecting the same object then the method will not start execution until the object is no longer protected.
Note that if a method or construct protecting an object invokes a method (or starts a new construct) that protects the same object then execution continues normally. The inner method or construct is not prevented from executing, because it is not executing in parallel.
Returns
The returns keyword is followed by a term, termr, that must evaluate to a type. This type is used to define the type of values returned by return instructions within the method.
The returns phrase is only required if the method is to return values of a type that is not NetRexx strings (class Rexx). If returns is specified, all return instructions within the method must specify an expression.
Example:
method filer(path, name) returns File
return File(path||name)
This method always returns a value which is a File object.
Signals
The signals keyword introduces a list of terms that evaluate to types that are Exceptions. This list enumerates and documents the exceptions that are signalled within the method (or by a method which is called from the current method) but are not caught by a catch clause in a control construct.
Example:
method soup(cat) signals IOException, DivideByZero
It is considered good programming practice to use this list to document 'unusual' exceptions signalled by a method. Implementations that support the concept of checked exceptions must report as an error any checked exception that is incorrectly included in the list (that is, if the exception is never signalled or would always be caught). Such implementations may also offer an option that enforces the listing of all or some checked exceptions.
Duplicate methods
Methods may not duplicate properties or other methods in the same class. Specifically:
- The short name of a method must not be the same as the name of any property in the same class.
- The number (zero or more) and types of the arguments of a method (or any subset permitted by omitting optional arguments) must not be the same as those of any other method of the same name in the class (also checking any subset permitted by omitting optional arguments).
Note that the second rule does allow multiple methods with the same name in a class, provided that the number of arguments differ or at least one argument differs in type.
