BBj Custom Objects Tutorial: Methods

The methods of a custom object class represent the actions or operations that are available for that class. The parameters and return types of these methods are strongly typed, and a return type is required as part of the declaration of each method other than constructors.

A class method is similar to a BBj user-defined function in that it has a start (the line of code that begins with the method verb) and an end (the line of code that begins with the methodend verb. The code in between these lines will be executed when the method is invoked with the correct types of arguments.

A method also represents a “limited visibility” scope for any variables defined inside of that method—those variables are not visible to any other code, including other class methods. The only method variables shared between the custom class method and the code that called it are those that are passed in the method’s parameter list.

Sample 6. Example Method of the Book Class

BBj’s method verb starts the definition of a class method. It is only valid inside of a custom object class definition, and must be outside of every other method of that class (nested methods are not supported). Every method begins with method, and ends with methodend.

Using the checkOut() method in Sample 6 as an example, we see that each method of a custom object class must have an explicitly defined access level (following the method verb). Method access levels, like field access levels, can be any one of three values:

Access Level	Description
private	The method can only be accessed by other methods of the class (the method has class scope). This is the most restrictive access level.
protected	The method can be accessed by other methods of the class AND by methods of any class that extends this class (a subclass).
public	The method can be accessed by other methods of the class AND by methods of any subclass AND from code outside of the class. This is the least restrictive access level.

In Sample 6, the checkOut() method has an access level of public.

Each method of a custom object class (other than constructors) must have an explicit return type. In the example above, the checkOut() method has a return type of void. The keyword void indicates that the method will not actually return a value.

Returning Values

Class methods return a value by using the methodret verb to tell BBj what value to return. If the method specifies a non-void return type, then:

• BBj must encounter a methodret line before reaching methodend. If not, BBj will generate an error when it reaches the methodend statement.

• The methodret verb must be followed by an expression that evaluates to the declared return type of the method. If it is not, BBj will generate an error.

• Method execution always terminates and control returns to the caller when BBj encounters a methodret statement.

If the method specifies a void return type (the checkOut() method in Sample 6), then:

• If your void method explicitly contains a methodret line, it must not be followed by any expression (it must be “empty”)

• If your void method does not explicitly have a methodret line, BBj will place an implicit methodret line just prior to the methodend statement

The getID() method in Sample 5 shows the methodret verb being used correctly.

Static Methods

There is an optional keyword, static, that can be inserted between the access level (public in Sample 6) and the return type (void in that example). Methods like checkOut(), that do not have the keyword static, are instance (or non-static) methods. Instance methods can only be invoked from other instance methods of the class, or from outside of the class by creating an instance of the class and using the dot notation described later in this document.

Static methods are special: they may be invoked directly from the class name (without actually creating an instance of that class). Because of this, static methods may not refer to any non-static fields of the class and may not invoke any non-static methods of the class.

For examples of this difference, see the Externally Invoking Methods section below.

Some points to remember about static methods:

• They can be invoked directly from the class name (without actually creating an instance of that class).

• They can also be invoked from an instance of the class.

• They are called “static” because they can not access any “instance” fields. They can only access class fields that are also designated as “static”.

Invoking Methods

The methods of a custom object can be invoked based on two different models: external code (code outside of the class) and internal code (code in a method of the class). Let’s examine the invocation model in each case.

Externally Invoking Methods: The “.” Dot Notation

Any method of a custom object can be invoked (think “executed”) from outside of the class by using the “.” dot notation that is common to most object-oriented languages. However, static methods are invoked with the dot notation slightly differently than instance methods are. Let’s look at the differences.

Externally Invoking Instance Methods

The code in Sample 7 (below) invokes the setID() and getID() instance methods on an instance of the Book class:

Sample 7. Externally Invoking an Instance Method

Instance (non-static) methods can only be invoked by first instantiating an instance of the class, and then invoking the desired method on that instance. The result of invoking an instance method on any particular class instance will likely depend on the values of its instance fields.

Externally Invoking Static Methods

The code in Sample 8 below invokes a static add() method on a Math class:

Sample 8. Externally Invoking a Static Method

Static methods can be invoked using dot notation together with the class name (as shown in Sample 8), OR they can be invoked like an instance method. The result of invoking a static method on any particular class instance should be the same as the result from invoking it using the class name (without a class instance).

Internally Invoking Methods: The # Prefix

Any method of a custom object can be invoked by code inside the class by prefixing a # character to the method name (similar to using the # character prefix to access a field). Code in the class can directly access any of its methods, including any static methods, or any protected or public methods of any superclass, with this model. To demonstrate this, Sample 9 shows how to invoke the markPage() method from inside the updateProgress() method:

Sample 9. Internally Invoking a Class Method

Next Step: Using Custom Objects

BBj Custom Objects Tutorial Contents

BBj Custom Objects Tutorial: Introduction

BBj Custom Objects Tutorial: Interfaces

BBj Custom Objects Tutorial: Classes

BBj Custom Objects Tutorial: Fields

BBj Custom Objects Tutorial: Methods

BBj Custom Objects Tutorial: Using Custom Objects

BBj Custom Objects Tutorial: Program #1 - Writing a Check

BBj Custom Objects Tutorial: Program #2 - Protected and Private Fields

BBj Custom Objects Tutorial: Program #3: The Static Keyword

BBj Custom Objects Tutorial: Program #4 - Error Handling

BBj Custom Objects Tutorial: Program #5 - Class Inheritance

BBj Custom Objects Tutorial: Program #6 - Callback Choices

BBj Custom Objects Tutorial: Program #7 - Constructors and Field Initialization