Java > Open Source Codes > org > apache > derby > iapi > services > compiler > MethodBuilder


1 /*
2
3    Derby - Class org.apache.derby.iapi.services.compiler.MethodBuilder
4
5    Licensed to the Apache Software Foundation (ASF) under one or more
6    contributor license agreements. See the NOTICE file distributed with
7    this work for additional information regarding copyright ownership.
8    The ASF licenses this file to you under the Apache License, Version 2.0
9    (the "License"); you may not use this file except in compliance with
10    the License. You may obtain a copy of the License at
11
12       http://www.apache.org/licenses/LICENSE-2.0
13
14    Unless required by applicable law or agreed to in writing, software
15    distributed under the License is distributed on an "AS IS" BASIS,
16    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17    See the License for the specific language governing permissions and
18    limitations under the License.
19
20  */
21
22 package org.apache.derby.iapi.services.compiler;
23
24 /**
25     MethodBuilder is used to generate the code for a method.
26     <P>
27
28     The code for a method is built in a way that corresponds to the
29     layout of the stack machine that is the Java Virtual Machine.
30     Values are pushed on the stack, moved about on the stack
31     and then popped off the stack by operations such as method
32     calls. An understanding of hoe the JVM operates is useful
33     before using this class.
34
35     <P>
36     All the method descriptions below are generating bytecode
37     to achieved the desired behaviour when the generated class
38     is loaded. None of this class's methods calls actually
39     invoke methods or create objects described by the callers.
40  */
41 public interface MethodBuilder {
42
43     /**
44      * Declare the method throws an exception.
45        Must be called before any code is added
46        to the method.
47      */
48     public void addThrownException(String exceptionClass);
49
50     /**
51      * return the name of the method.
52      */
53     public String getName();
54
55     /**
56         Indicate the method is complete. Once this
57         call has been made the caller must discard
58         the reference to this object.
59      */
60     public void complete();
61
62     /**
63         Push a parameter value.
64         <PRE>
65         Stack ... =>
66               ...,param_value
67         </PRE>
68         @param id position of the parameter (zero based).
69     */
70     public void getParameter(int id);
71
72     /**
73         Push a byte constant onto the stack
74         <PRE>
75         Stack ... =>
76               ...,byte_value
77         </PRE>
78     */
79     public void push(byte value);
80
81     /**
82         Push a boolean constant onto the stack
83         <PRE>
84         Stack ... =>
85               ...,boolean_value
86         </PRE>
87     */
88     public void push(boolean value);
89
90     /**
91         Push a short constant onto the stack
92         <PRE>
93         Stack ... =>
94               ...,short_value
95         </PRE>
96     */
97     public void push(short value);
98
99     /**
100         Push a int constant onto the stack
101         <PRE>
102         Stack ... =>
103               ...,int_value
104         </PRE>
105     */
106     public void push(int value);
107
108     /**
109         Push a long constant onto the stack
110         <PRE>
111         Stack ... =>
112               ...,long_value
113         </PRE>
114     */
115     public void push(long value);
116
117     /**
118         Push a float constant onto the stack
119         <PRE>
120         Stack ... =>
121               ...,float_value
122         </PRE>
123     */
124     public void push(float value);
125
126     /**
127         Push a double constant onto the stack
128         <PRE>
129         Stack ... =>
130               ...,double_value
131         </PRE>
132     */
133     public void push(double value);
134
135     /**
136         Push a String constant onto the stack
137         <PRE>
138         Stack ... =>
139               ...,String_value
140         </PRE>
141     */
142     public void push(String value);
143
144     /**
145         Push a typed null onto the stack
146         <PRE>
147         Stack ... =>
148               ...,null
149         </PRE>
150     */
151     public void pushNull(String className);
152
153     /**
154         Push the contents of the local field onto the stack.
155         This call pushes the this instance required to access the field itself.
156         <PRE>
157         Stack ... =>
158               ...,field_value
159         </PRE>
160
161     */
162     public void getField(LocalField field);
163
164     /**
165         Push the contents of the described field onto the stack.
166         This call requires the instance (reference) to be pushed by the caller.
167
168         <PRE>
169         Stack ...,field_ref =>
170               ...,field_value
171         </PRE>
172         
173     */
174     public void getField(String declaringClass, String fieldName, String fieldType);
175
176     /**
177         Push the contents of the described static field onto the stack.
178         <PRE>
179         Stack ... =>
180               ...,field_value
181         </PRE>
182     */
183     public void getStaticField(String declaringClass, String fieldName, String fieldType);
184
185     /**
186     Pop the top stack value and store it in the local field.
187     This call pushes the this instance required to access the field itself.
188     This call does not leave any value on the stack.
189
190     <PRE>
191     Stack ...,value =>
192           ...
193     </PRE>
194     */
195     public void setField(LocalField field);
196
197     /**
198         Pop the top stack value and store it in the local field.
199         This call pushes the this instance required to access the field itself.
200         Like the Java language 'field = value', this leaves the value on the stack.
201
202         <PRE>
203         Stack ...,value =>
204               ...,value
205         </PRE>
206     */
207     public void putField(LocalField field);
208
209     /**
210         Pop the top stack value and store it in the instance field of this class.
211         This call pushes the this instance required to access the field itself.
212         Like the Java language 'field = value', this leaves the value on the stack.
213
214         <PRE>
215         Stack ...,value =>
216               ...,value
217         </PRE>
218     */
219     public void putField(String fieldName, String fieldType);
220
221     /**
222         Pop the top stack value and store it in the field.
223         This call requires the instance to be pushed by the caller.
224         Like the Java language 'field = value', this leaves the value on the stack.
225
226         <PRE>
227         Stack ...,field_ref,value =>
228               ...,value
229         </PRE>
230     */
231     public void putField(String declaringClass, String fieldName, String fieldType);
232
233     /**
234         Initiate a sequence that calls a constructor, equivalent to the new operator in Java.
235         After this call, the caller must push any arguments and then complete the
236         construction with a call to pushNewComplete(). Only arguments to the constructor
237         can be pushed onto the stack between the pushNewStart() and pushNewComplete() method
238         calls.
239
240         <PRE>
241         Stack ... => [unchanged]
242               ...
243         </PRE>
244
245         @param className class name of object to be created.
246     */
247     public void pushNewStart(String className);
248
249
250     /**
251         Complete the sequence that was started with pushNewStart().
252         Pop the arguments to the constructor and push the reference
253         to the newly created object.
254
255         <PRE>
256         Stack ...,value* => [numArgs number of values will be popped]
257               ...,new_ref
258         </PRE>
259
260         @param numArgs number of arguments to the constructor (can be 0).
261     */
262     public void pushNewComplete(int numArgs);
263
264     /**
265         Create an instance of an array and push it onto the stack.
266
267         <PRE>
268         Stack ... =>
269               ...,array_ref
270         </PRE>
271
272         @param className - type of array.
273         @param size - number of elements in the array
274     */
275     public void pushNewArray(String className, int size);
276
277
278     /**
279         Push this onto the stack.
280         <PRE>
281         Stack ... =>
282               ...,this_ref
283         </PRE>
284     */
285     public void pushThis();
286
287     /**
288         Upcast the top stack value. This is used for correct method resolution
289         by upcasting method parameters. It does not put any casting code into the
290         byte code stream. Can only be used for refrences.
291         <PRE>
292         Stack ...,ref =>
293               ...,ref
294         </PRE>
295     */
296     public void upCast(String className);
297
298     /**
299         Cast the top stack value. Correctly down-casts a reference or casts
300         a primitive type (e.g. int to short).
301         <PRE>
302         Stack ...,value =>
303               ...,cast_value
304         </PRE>
305
306         @param className type (primitive, interface or class) to cast to.
307     */
308     public void cast(String className);
309
310     /**
311         Pop the top stack value and push a boolean that is the result of
312         an instanceof check on the popped reference.
313         <PRE>
314         Stack ...,ref =>
315               ...,boolean_value
316         </PRE>.
317     */
318     public void isInstanceOf(String className);
319     
320     /**
321      * Pop the top value off the stack
322         <PRE>
323         Stack ..., value =>
324               ...
325         </PRE>.
326     */
327     public void pop();
328         
329     /**
330         End a statement.
331         Pops the top-word of the stack, if any.
332         Must only be called if zero or one item exists
333         on the stack.
334         <PRE>
335         Stack value =>
336               :empty:
337         or
338
339         Stack :empty: =>
340               :empty:
341
342         </PRE>.
343     */
344     public void endStatement();
345
346     /**
347         Return from a method, optionally with a value.
348         Must only be called if zero or one item exists
349         on the stack. If the stack contains a single
350         value then that is popped and used as the returned value.
351         <PRE>
352         Stack value =>
353               :empty:
354         or
355
356         Stack :empty: =>
357               :empty:
358
359         </PRE>.
360     */
361     public void methodReturn();
362
363     /**
364         Initiate a conditional sequence.
365         The top value on the stack (a reference) is popped and compared to 'null'.
366         If the value is null then the code following this call until the startElseCode()
367         will be executed at runtime, otherwise the code following startElseCode() until
368         the completeConditional() is called.
369         <BR>
370         E.g.
371
372         <PRE>
373         mb.callMethod(...); // pushes an object onto the stack
374         mb.conditionalIfNull();
375           mb.push(3);
376         mb.startElseCode();
377           mb.push(5);
378         mb.completeConditional();
379         // at this point 3 or 5 will be on the stack
380         </PRE>
381
382         Each path through the ?: statement must leave the stack at the same depth
383         as the other.
384         <BR>
385         If the if or else code pops values from the stack that were before the conditional
386         value, then they must use the same number of values from the stack.
387
388         <PRE>
389         Stack ...,ref =>
390               ...
391         </PRE>.
392
393     */
394
395     public void conditionalIfNull();
396     
397     /**
398         Initiate a conditional sequence.
399         The top value on the stack must be a boolean and will be popped. If it
400         is true then the code following this call until the startElseCode()
401         will be executed at runtime, otherwise the code following startElseCode() until
402         the completeConditional() is called. See conditionalIfNull() for example
403         and restrictions.
404
405         <PRE>
406         Stack ...,boolean_value =>
407               ...
408         </PRE>.
409     */
410     public void conditionalIf();
411
412     /**
413         Complete the true code path of a conditional.
414     */
415     public void startElseCode();
416
417     /**
418         Complete a conditional which completes the false code path.
419     */
420     public void completeConditional();
421
422     /**
423         Call a method. The instance (receiver or reference) for non-static methods
424         must be pushed by the caller. The instance (for non-static) and the arguments
425         are popped of the stack, and the return value (if any) is pushed onto the stack.
426         <BR>
427         The type needs to be one of:
428         <UL>
429         <LI> VMOpcode.INVOKESTATIC - call a static method
430         <LI> VMOpcode.INVOKEVIRTUAL - call method declared in the class or super-class.
431         <LI> VMOpcode.INVOKEINTERFACE - call a method declared in an interface
432         </UL>
433
434
435         <PRE>
436         static methods
437
438         Stack ...,value* => [numArgs number of values will be popped]
439               ...,return_value [void methods will not push a value]
440
441         non-static methods
442
443         Stack ...,ref,value* => [numArgs number of values will be popped]
444               ...,return_value [void methods will not push a value]
445         </PRE>
446
447         <BR>
448         The type of the arguments to the methods must exactly match the declared types
449         of the parameters to the methods. If a argument is of the incorrect type the
450         caller must up cast it or down cast it.
451
452         @param type type of method invocation
453         @param declaringClass Class or interface the method is declared in. If it is a non-static
454             method call then if declaringClass is null, the declared type is taken to be the
455             type of the reference that will be popped.
456
457         @param methodName name of the method
458         @param returnType class name or primitive type (including "void") of the return type of the method, can not be null.
459         @param numArgs number of arguments to the method (can be 0).
460
461     */
462     public int callMethod(short type, String declaringClass, String methodName,
463         String returnType, int numArgs);
464
465     /**
466         Return an object that efficiently (to the implementation) describes a zero-argument method and
467         can be used with the single argument callMethod(). Descriptions for the parameters to this
468         method are the same as the five argument callMethod(). This allows the caller to cache frequently
469         used methods. The returned object is only valid for use by this MethodBuilder.
470         <BR>
471         This call does not affect the Stack.
472     */
473     public Object describeMethod(short opcode, String declaringClass, String methodName, String returnType);
474
475     /**
476         Call a method previously described by describeMethod().
477         <PRE>
478         static methods
479
480         Stack ...,value* => [numArgs number of values will be popped]
481               ...,return_value [void methods will not push a value]
482
483         non-static methods
484
485         Stack ...,ref,value* => [numArgs number of values will be popped]
486               ...,return_value [void methods will not push a value]
487         </PRE>
488
489     */
490     public int callMethod(Object methodDescriptor);
491
492     /**
493         Call super(). Caller must only add this to a constructor.
494         <PRE>
495
496         Stack ... =>
497               ...
498         </PRE>
499
500     */
501     public void callSuper();
502
503     /**
504         Pop an array refrence off the stack and push an element from that array.
505         <PRE>
506         Stack ...,array_ref =>
507               ...,value
508         </PRE>
509
510         @param element Offset into the array (zero based)
511     */
512     public void getArrayElement(int element);
513
514     /**
515         Pop an array reference off the stack, store a value in the array at the passed in offset.
516         <PRE>
517         Stack ...,array_ref, value =>
518               ...
519         </PRE>
520
521         @param element Offset into the array (zero based)
522     */
523     public void setArrayElement(int element);
524
525
526     /**
527         Swap the top two values on the stack.
528         <PRE>
529         Stack ...,valueA,valueB =>
530               ...,valueB,valueA
531         </PRE>
532     */
533     public void swap();
534
535     /**
536         Duplicate the top value on the stack.
537         <PRE>
538         Stack ...,value =>
539               ...,value,value
540         </PRE>
541     */
542     public void dup();
543
544     /**
545         Tell if statement number in this method builder hits limit. This
546         method builder keeps a counter of how many statements are added to it.
547         Caller should call this function every time it tries to add a statement
548         to this method builder (counter is increased by 1), then the function
549         returns whether the accumulated statement number hits a limit.
550         The reason of doing this is that Java compiler has a limit of 64K code
551         size for each method. We might hit this limit if an extremely long
552         insert statement is issued, for example (see beetle 4293). Counting
553         statement number is an approximation without too much overhead.
554     */
555     public boolean statementNumHitLimit(int noStatementsAdded);
556 }
557
558

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags