Mercurial > hg > blitz_stable

comparison src/com/go/trove/classfile/CodeAssembler.java @ 0:3dc0c5604566

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Initial checkin of blitz 2.0 fcs - no installer yet.
author Dan Creswell <dan.creswell@gmail.com>
date Sat, 21 Mar 2009 11:00:06 +0000
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:3dc0c5604566
1 /* ====================================================================
2 * Trove - Copyright (c) 1997-2000 Walt Disney Internet Group
3 * ====================================================================
4 * The Tea Software License, Version 1.1
5 *
6 * Copyright (c) 2000 Walt Disney Internet Group. All rights reserved.
7 *
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions
10 * are met:
11 *
12 * 1. Redistributions of source code must retain the above copyright
13 * notice, this list of conditions and the following disclaimer.
14 *
15 * 2. Redistributions in binary form must reproduce the above copyright
16 * notice, this list of conditions and the following disclaimer in
17 * the documentation and/or other materials provided with the
18 * distribution.
19 *
20 * 3. The end-user documentation included with the redistribution,
21 * if any, must include the following acknowledgment:
22 * "This product includes software developed by the
23 * Walt Disney Internet Group (http://opensource.go.com/)."
24 * Alternately, this acknowledgment may appear in the software itself,
25 * if and wherever such third-party acknowledgments normally appear.
26 *
27 * 4. The names "Tea", "TeaServlet", "Kettle", "Trove" and "BeanDoc" must
28 * not be used to endorse or promote products derived from this
29 * software without prior written permission. For written
30 * permission, please contact opensource@dig.com.
31 *
32 * 5. Products derived from this software may not be called "Tea",
33 * "TeaServlet", "Kettle" or "Trove", nor may "Tea", "TeaServlet",
34 * "Kettle", "Trove" or "BeanDoc" appear in their name, without prior
35 * written permission of the Walt Disney Internet Group.
36 *
37 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
38 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
39 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
40 * DISCLAIMED. IN NO EVENT SHALL THE WALT DISNEY INTERNET GROUP OR ITS
41 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
42 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
43 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
44 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
45 * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
46 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
47 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
48 * ====================================================================
49 *
50 * For more information about Tea, please see http://opensource.go.com/.
51 */
52
53 package com.go.trove.classfile;
54
55 /******************************************************************************
56 * CodeAssembler is a high-level interface for assembling Java Virtual Machine
57 * byte code. It can also be used as a visitor to a disassembler.
58 *
59 * @author Brian S O'Neill
60 * @version
61 * <!--$$Revision: 1.1 $-->, <!--$$JustDate:--> 9/07/00 <!-- $-->
62 */
63 public interface CodeAssembler {
64 /**
65 * Returns LocalVariable references for all the parameters passed into
66 * the method being assembled, not including any "this" reference.
67 * Returns a zero-length array if there are no passed in parameters.
68 *
69 * <p>The names of the LocalVariables returned by this method are initially
70 * set to null. It is encouraged that a name be provided.
71 */
72 public LocalVariable[] getParameters();
73
74 /**
75 * Creates a LocalVariable reference from a name and type. Although name
76 * is optional, it is encouraged that a name be provided. Names do not
77 * need to be unique.
78 *
79 * @param name Optional name for the LocalVariable.
80 * @param type The type of data that the requested LocalVariable can
81 * store.
82 */
83 public LocalVariable createLocalVariable(String name,
84 TypeDescriptor type);
85
86 /**
87 * Creates a label, whose location must be set. To create a label and
88 * locate it here, the following example demonstrates how the call to
89 * setLocation can be chained:
90 *
91 * <pre>
92 * CodeBuilder builder;
93 * ...
94 * Label label = builder.createLabel().setLocation();
95 * </pre>
96 *
97 * @see Label#setLocation
98 */
99 public Label createLabel();
100
101 /**
102 * Sets up an exception handler located here, the location of the next
103 * code to be generated.
104 *
105 * @param startLocation Location at the start of the section of
106 * code to be wrapped by an exception handler.
107 * @param endLocation Location directly after the end of the
108 * section of code.
109 * @param catchClassName The name of the type of exception to be caught;
110 * if null, then catch every object.
111 */
112 public void exceptionHandler(Location startLocation,
113 Location endLocation,
114 String catchClassName);
115
116 /**
117 * Map the location of the next code to be generated to a line number
118 * in source code. This enables line numbers in a stack trace from the
119 * generated code.
120 */
121 public void mapLineNumber(int lineNumber);
122
123 // load-constant-to-stack style instructions
124
125 /**
126 * Generates code that loads a constant string value onto the stack.
127 * If value is null, the generated code loads a null onto the stack.
128 * Strings that exceed 65535 UTF encoded bytes in length are loaded by
129 * creating a StringBuffer, appending substrings, and then converting to a
130 * String.
131 */
132 public void loadConstant(String value);
133
134 /**
135 * Generates code that loads a constant boolean value onto the stack.
136 */
137 public void loadConstant(boolean value);
138
139 /**
140 * Generates code that loads a constant int, char, short or byte value
141 * onto the stack.
142 */
143 public void loadConstant(int value);
144
145 /**
146 * Generates code that loads a constant long value onto the stack.
147 */
148 public void loadConstant(long value);
149
150 /**
151 * Generates code that loads a constant float value onto the stack.
152 */
153 public void loadConstant(float value);
154
155 /**
156 * Generates code that loads a constant double value onto the stack.
157 */
158 public void loadConstant(double value);
159
160 // load-local-to-stack style instructions
161
162 /**
163 * Generates code that loads a local variable onto the stack. Parameters
164 * passed to a method and the "this" reference are all considered local
165 * variables, as well as any that were created.
166 *
167 * @param local The local variable reference
168 */
169 public void loadLocal(LocalVariable local);
170
171 /**
172 * Loads a reference to "this" onto the stack. Static methods have no
173 * "this" reference, and an exception is thrown when attempting to
174 * generate "this" in a static method.
175 */
176 public void loadThis();
177
178 // store-from-stack-to-local style instructions
179
180 /**
181 * Generates code that pops a value off of the stack into a local variable.
182 * Parameters passed to a method and the "this" reference are all
183 * considered local variables, as well as any that were created.
184 *
185 * @param local The local variable reference
186 */
187 public void storeLocal(LocalVariable local);
188
189 // load-to-stack-from-array style instructions
190
191 /**
192 * Generates code that loads a value from an array. An array
193 * reference followed by an index must be on the stack. The array
194 * reference and index are replaced by the value retrieved from the array
195 * after the generated instruction has executed.
196 *
197 * <p>The type doesn't need to be an exact match for objects. Object.class
198 * works fine for all objects. For primitive types, use the class that
199 * matches that type. For an int the type is int.class.
200 *
201 * @param type The type of data stored in the array.
202 */
203 public void loadFromArray(Class type);
204
205 // store-to-array-from-stack style instructions
206
207 /**
208 * Generates code that stores a value to an array. An array
209 * reference followed by an index, followed by a value (or two if a long
210 * or double) must be on the stack. All items on the stack are gone
211 * after the generated instruction has executed.
212 *
213 * <p>The type doesn't need to be an exact match for objects. Object.class
214 * works fine for all objects. For primitive types, use the class that
215 * matches that type. For an int the type is int.class.
216 *
217 * @param type The type of data stored in the array.
218 */
219 public void storeToArray(Class type);
220
221 // load-field-to-stack style instructions
222
223 /**
224 * Generates code that loads a value from a field from this class.
225 * An object reference must be on the stack. After the generated code
226 * has executed, the object reference is replaced by the value retrieved
227 * from the field.
228 */
229 public void loadField(String fieldName,
230 TypeDescriptor type);
231
232 /**
233 * Generates code that loads a value from a field from any class.
234 * An object reference must be on the stack. After the generated code
235 * has executed, the object reference is replaced by the value retrieved
236 * from the field.
237 */
238 public void loadField(String className,
239 String fieldName,
240 TypeDescriptor type);
241
242 /**
243 * Generates code that loads a value from a static field from this class.
244 * After the generated code has executed, the value retrieved is placed
245 * on the stack.
246 */
247 public void loadStaticField(String fieldName,
248 TypeDescriptor type);
249
250 /**
251 * Generates code that loads a value from a static field from any class.
252 * After the generated code has executed, the value retrieved is placed
253 * on the stack.
254 */
255 public void loadStaticField(String className,
256 String fieldName,
257 TypeDescriptor type);
258
259 // store-to-field-from-stack style instructions
260
261 /**
262 * Generates code that stores a value into a field from this class.
263 * An object reference and value must be on the stack. After the generated
264 * code has executed, the object reference and value are gone from
265 * the stack.
266 */
267 public void storeField(String fieldName,
268 TypeDescriptor type);
269
270 /**
271 * Generates code that stores a value into a field from any class.
272 * An object reference and value must be on the stack. After the generated
273 * code has executed, the object reference and value are gone from
274 * the stack.
275 */
276 public void storeField(String className,
277 String fieldName,
278 TypeDescriptor type);
279
280 /**
281 * Generates code that stores a value into a field from this class.
282 * A value must be on the stack. After the generated
283 * code has executed, the value is gone from the stack.
284 */
285 public void storeStaticField(String fieldName,
286 TypeDescriptor type);
287
288 /**
289 * Generates code that stores a value into a field from any class.
290 * A value must be on the stack. After the generated
291 * code has executed, the value is gone from the stack.
292 */
293 public void storeStaticField(String className,
294 String fieldName,
295 TypeDescriptor type);
296
297 // return style instructions
298
299 /**
300 * Generates code that returns void.
301 */
302 public void returnVoid();
303
304 /**
305 * Generates code that returns an object or primitive type. The value to
306 * return must be on the stack.
307 *
308 * <p>The type doesn't need to be an exact match for objects. Object.class
309 * works fine for all objects. For primitive types, use the class that
310 * matches that type. For an int the type is int.class.
311 */
312 public void returnValue(Class type);
313
314 // numerical conversion style instructions
315
316 /**
317 * Generates code that converts the value of a primitive type already
318 * on the stack.
319 */
320 public void convert(Class fromType, Class toType);
321
322 // invocation style instructions
323
324 /**
325 * Generates code to invoke a virtual method in this class. The object
326 * reference and the method's argument(s) must be on the stack.
327 *
328 * @param ret May be null if method returns void.
329 * @param params May be null if method takes no parameters.
330 */
331 public void invokeVirtual(String methodName,
332 TypeDescriptor ret,
333 TypeDescriptor[] params);
334
335 /**
336 * Generates code to invoke a virtual method in any class. The object
337 * reference and the method's argument(s) must be on the stack.
338 *
339 * @param ret May be null if method returns void.
340 * @param params May be null if method takes no parameters.
341 */
342 public void invokeVirtual(String className,
343 String methodName,
344 TypeDescriptor ret,
345 TypeDescriptor[] params);
346
347 /**
348 * Generates code to invoke a static method in this class. The method's
349 * argument(s) must be on the stack.
350 *
351 * @param ret May be null if method returns void.
352 * @param params May be null if method takes no parameters.
353 */
354 public void invokeStatic(String methodName,
355 TypeDescriptor ret,
356 TypeDescriptor[] params);
357
358 /**
359 * Generates code to invoke a static method in any class. The method's
360 * argument(s) must be on the stack.
361 *
362 * @param ret May be null if method returns void.
363 * @param params May be null if method takes no parameters.
364 */
365 public void invokeStatic(String className,
366 String methodName,
367 TypeDescriptor ret,
368 TypeDescriptor[] params);
369
370 /**
371 * Generates code to invoke an interface method in any class. The object
372 * reference and the method's argument(s) must be on the stack.
373 *
374 * @param ret May be null if method returns void.
375 * @param params May be null if method takes no parameters.
376 */
377 public void invokeInterface(String className,
378 String methodName,
379 TypeDescriptor ret,
380 TypeDescriptor[] params);
381
382 /**
383 * Generates code to invoke a private method in this class.
384 * The object reference and the method's argument(s) must be on the stack.
385 *
386 * @param ret May be null if method returns void.
387 * @param params May be null if method takes no parameters.
388 */
389 public void invokePrivate(String methodName,
390 TypeDescriptor ret,
391 TypeDescriptor[] params);
392
393 /**
394 * Generates code to invoke a method in the super class.
395 * The object reference and the method's argument(s) must be on the stack.
396 *
397 * @param ret May be null if method returns void.
398 * @param params May be null if method takes no parameters.
399 */
400 public void invokeSuper(String superClassName,
401 String methodName,
402 TypeDescriptor ret,
403 TypeDescriptor[] params);
404
405 /**
406 * Generates code to invoke a class constructor in this class. The object
407 * reference and the constructor's argument(s) must be on the stack.
408 *
409 * @param params May be null if constructor takes no parameters.
410 */
411 public void invokeConstructor(TypeDescriptor[] params);
412
413 /**
414 * Generates code to invoke a class constructor in any class. The object
415 * reference and the constructor's argument(s) must be on the stack.
416 *
417 * @param params May be null if constructor takes no parameters.
418 */
419 public void invokeConstructor(String className, TypeDescriptor[] params);
420
421 /**
422 * Generates code to invoke a super class constructor. The object
423 * reference and the constructor's argument(s) must be on the stack.
424 *
425 * @param params May be null if constructor takes no parameters.
426 */
427 public void invokeSuperConstructor(TypeDescriptor[] params);
428
429 // creation style instructions
430
431 /**
432 * Generates code to create a new object. Unless the new object is an
433 * array, it is invalid until a constructor method is invoked on it.
434 * When creating arrays, the size for each dimension must be on the
435 * operand stack.
436 *
437 * @see #invokeConstructor
438 */
439 public void newObject(TypeDescriptor type);
440
441 // stack operation style instructions
442
443 /**
444 * Generates code for the dup instruction.
445 */
446 public void dup();
447
448 /**
449 * Generates code for the dup_x1 instruction.
450 */
451 public void dupX1();
452
453 /**
454 * Generates code for the dup_x2 instruction.
455 */
456 public void dupX2();
457
458 /**
459 * Generates code for the dup2 instruction.
460 */
461 public void dup2();
462
463 /**
464 * Generates code for the dup2_x1 instruction.
465 */
466 public void dup2X1();
467
468 /**
469 * Generates code for the dup2_x2 instruction.
470 */
471 public void dup2X2();
472
473 /**
474 * Generates code for the pop instruction.
475 */
476 public void pop();
477
478 /**
479 * Generates code for the pop2 instruction.
480 */
481 public void pop2();
482
483 /**
484 * Generates code for the swap instruction.
485 */
486 public void swap();
487
488 /**
489 * Generates code for a swap2 instruction.
490 */
491 public void swap2();
492
493 // flow control instructions
494
495 /**
496 * Generates code that performs an unconditional branch to the specified
497 * location.
498 *
499 * @param location The location to branch to
500 */
501 public void branch(Location location);
502
503 /**
504 * Generates code that performs a conditional branch based on the
505 * value of an object on the stack. A branch is performed based on whether
506 * the object reference on the stack is null or not.
507 *
508 * @param location The location to branch to
509 * @param choice If true, do branch when null, else branch when not null
510 */
511 public void ifNullBranch(Location location, boolean choice);
512
513 /**
514 * Generates code that performs a conditional branch based on the value of
515 * two object references on the stack. A branch is performed based on
516 * whether the two objects are equal.
517 *
518 * @param location The location to branch to
519 * @param choice If true, branch when equal, else branch when not equal
520 */
521 public void ifEqualBranch(Location location, boolean choice);
522
523 /**
524 * Generates code the performs a conditional branch based on a comparison
525 * between an int value on the stack and zero. The int value on the
526 * stack is on the left side of the comparison expression.
527 *
528 * @param location The location to branch to
529 * @param choice One of "==", "!=", "<", ">=", ">" or "<="
530 * @exception IllegalArgumentException When the choice is not valid
531 */
532 public void ifZeroComparisonBranch(Location location, String choice)
533 throws IllegalArgumentException;
534
535 /**
536 * Generates code the performs a conditional branch based on a comparison
537 * between two int values on the stack. The first int value on the stack
538 * is on the left side of the comparison expression.
539 *
540 * @param location The location to branch to
541 * @param choice One of "==", "!=", "<", ">=", ">" or "<="
542 * @exception IllegalArgumentException When the choice is not valid
543 */
544 public void ifComparisonBranch(Location location, String choice)
545 throws IllegalArgumentException;
546
547 /**
548 * Generates code for a switch statement. The generated code is either a
549 * lookupswitch or tableswitch. The choice of which switch type to generate
550 * is made based on the amount of bytes to be generated. A tableswitch
551 * is usually smaller, unless the cases are sparse.
552 *
553 * <p>The key value to switch on must already be on the stack when this
554 * instruction executes.
555 *
556 * @param cases The values to match on. The array length must be the same
557 * as for locations.
558 * @param locations The locations to branch to for each case.
559 * The array length must be the same as for cases.
560 * @param defaultLocation The location to branch to if the key on
561 * the stack was not matched.
562 */
563 public void switchBranch(int[] cases,
564 Location[] locations, Location defaultLocation);
565
566 /**
567 * Generates code that performs a subroutine branch to the specified
568 * location. The instruction generated is either jsr or jsr_w. It is most
569 * often used for implementing a finally block.
570 *
571 * @param Location The location to branch to
572 */
573 public void jsr(Location location);
574
575 /**
576 * Generates code that returns from a subroutine invoked by jsr.
577 *
578 * @param local The local variable reference that contains the return
579 * address. The local variable must be of an object type.
580 */
581 public void ret(LocalVariable local);
582
583 // math instructions
584
585 /**
586 * Generates code for either a unary or binary math operation on one
587 * or two values pushed on the stack.
588 *
589 * <p>Pass in an opcode from the the Opcode class. The only valid math
590 * opcodes are:
591 *
592 * <pre>
593 * IADD, ISUB, IMUL, IDIV, IREM, INEG, IAND, IOR, IXOR, ISHL, ISHR, IUSHR
594 * LADD, LSUB, LMUL, LDIV, LREM, LNEG, LAND, LOR, LXOR, LSHL, LSHR, LUSHR
595 * FADD, FSUB, FMUL, FDIV, FREM, FNEG
596 * DADD, DSUB, DMUL, DDIV, DREM, DNEG
597 *
598 * LCMP
599 * FCMPG, FCMPL
600 * DCMPG, DCMPL
601 * </pre>
602 *
603 * A not operation (~) is performed by doing a loadConstant with either
604 * -1 or -1L followed by math(Opcode.IXOR) or math(Opcode.LXOR).
605 *
606 * @param opcode An opcode from the Opcode class.
607 * @exception IllegalArgumentException When the opcode selected is not
608 * a math operation.
609 * @see Opcode
610 */
611 public void math(byte opcode);
612
613 // miscellaneous instructions
614
615 /**
616 * Generates code for an arraylength instruction. The object to get the
617 * length from must already be on the stack.
618 */
619 public void arrayLength();
620
621 /**
622 * Generates code that throws an exception. The object to throw must
623 * already be on the stack.
624 */
625 public void throwObject();
626
627 /**
628 * Generates code that performs an object cast operation. The object
629 * to check must already be on the stack.
630 */
631 public void checkCast(TypeDescriptor type);
632
633 /**
634 * Generates code that performs an instanceof operation. The object to
635 * check must already be on the stack.
636 */
637 public void instanceOf(TypeDescriptor type);
638
639 /**
640 * Generates code that increments a local integer variable by a signed
641 * constant amount.
642 */
643 public void integerIncrement(LocalVariable local, int amount);
644
645 /**
646 * Generates code to enter the monitor on an object loaded on the stack.
647 */
648 public void monitorEnter();
649
650 /**
651 * Generates code to exit the monitor on an object loaded on the stack.
652 */
653 public void monitorExit();
654
655 /**
656 * Generates an instruction that does nothing. (No-OPeration)
657 */
658 public void nop();
659
660 /**
661 * Generates a breakpoint instruction for use in a debugging environment.
662 */
663 public void breakpoint();
664 }