prev next contents
invokespecial

invoke method belonging to a specific class

Jasmin Syntax


    invokespecial <method-spec>
<method-spec> is a method specification. It is a single token made up of three parts: a classname, a methodname and a descriptor. e.g.

     java/lang/StringBuffer/<init>()V
is the method called "<init>" (the special name used for instance initialization methods) in the class called "java.lang.StringBuffer", and it has the descriptor "()V" (i.e. it takes no arguments and no results). In Jasmin, the characters up to the '(' character in <method-spec> form the classname and methodname (the classname is all the characters up to the last '/' character, and the methodname is all the characters between the last '/' and the '(' character). The characters from '(' to the end of the string are the descriptor. This is illustrated in the following diagram:


     foo/baz/Myclass/myMethod(Ljava/lang/String;)V
     ---------------         ---------------------
           |         --------         |
           |            |             |
         classname  methodname    descriptor

Stack

Before

After
argN
[result]
---

arg2

arg1

objectref

...

Description

invokespecial is used in certain special cases to invoke a method Specifically, invokespecial is used to invoke:

the instance initialization method, <init>

a private method of this

a method in a superclass of this

The main use of invokespecial is to invoke an object's instance initialization method, <init>, during the construction phase for a new object. For example, when you write in Java:


new StringBuffer()
code like the following is generated:

new java/lang/StringBuffer         ; create a new StringBuffer
dup                                ; make an extra reference to the new instance
                                   ; now call an instance initialization method
invokespecial java/lang/StringBuffer/<init>()V
                                   ; stack now contains an initialized StringBuffer.
invokespecial is also used by the Java language by the 'super' keyword to access a superclass's version of a method. For example, in the class:

   class Example {
       // override equals
       public boolean equals(Object x) {
            // call Object's version of equals
            return super.equals(x);
       }
   }
the 'super.equals(x)' expression is compiled to:

aload_0  ; push 'this' onto the stack
aload_1  ; push the first argument (i.e. x) onto the stack
; now invoke Object's equals() method.
invokespecial java/lang/Object/equals(Ljava/lang/Object;)Z
Finally, invokespecial is used to invoke a private method. Remember that private methods are only visible to other methods belonging the same class as the private method.

Before performing the method invokation, the class and the method identified by <method-spec> are resolved. See Chapter 9 for a description of how methods are resolved.

invokespecial first looks at the descriptor given in <method-spec>, and determines how many argument words the method takes (this may be zero). It pops these arguments off the operand stack. Next it pops objectref (a reference to an object) off the operand stack. objectref must be an instance of the class named in <method-spec>, or one of its subclasses. The interpreter searches the list of methods defined by the class named in <method-spec>, looking for a method called methodname whose descriptor is descriptor. This search is not based on the runtime type of objectref, but on the compile time type given in <method-spec>.

Once a method has been located, invokespecial calls the method. First, if the method is marked as synchronized, the monitor associated with objectref is entered. Next, a new stack frame structure is established on the call stack. Then the arguments for the method (which were popped off the current method's operand stack) are placed in local variables of the new stack frame structure. arg1 is stored in local variable 1, arg2 is stored in local variable 2 and so on. objectref is stored in local variable 0 (the local variable used for the special Java variable this). Finally, execution continues at the first instruction in the bytecode of the new method.

Methods marked as native are handled slightly differently. For native methods, the runtime system locates the platform-specific code for the method, loading it and linking it into the JVM if necessary. Then the native method code is executed with the arguments popped from the operand stack. The exact mechanism used to invoke native methods is implementation-specific.

When the method called by invokespecial returns, any single (or double) word return result is placed on the operand stack of the current method. If the invoked method was marked as synchronized, the monitor associated with objectref is exited. Execution continues at the instruction that follows invokespecial in the bytecode.

Exceptions

NullPointerException - objectref is null

StackOverflowError - no more space in callstack for a new stack frame

Bytecode

In bytecode, after the invokespecial opcode is a 16-bit unsigned integer index. This is the index of an entry in the constant pool. The entry is tagged as a CONSTANT_Methodref entry. This entry has two fields. One field points to a CONSTANT_Class entry in the constant pool whose name is the classname from <method-spec>, and the other points to a CONSTANT_NameAndType entry in the constant pool whose name is the methodname from <method-spec> and whose descriptor is the type descriptor from <method-spec>.

Type

Description
u1
invokespecial opcode = 0xB7 (183)
u2
index
See Also

invokevirtual, invokeinterface, invokestatic

Notes

1. In Java Virtual Machine implementations prior to version JDK 1.02, this instruction was called invokenonvirtual, and was less restrictive than invokespecial - it wasn't limited to invoking only superclass, private or <init> methods. The class access flag ACC_SUPER (see Chapter 4) is used to indicate which semantics are used by a class. In older class files, the ACC_SUPER flag is unset. In all new classes, the ACC_SUPER flag should be set, indicating that the restrictions enforced by invokespecial are obeyed. (In practice, all the common uses of invokenonvirtual continue to be supported by invokespecial, so this change should have little impact on JVM users).


prev next contents
Java Virtual Machine, by Jon Meyer and Troy Downing, O'Reilly Associates