Mercurial > hg > blitz_condensed
comparison src/com/go/trove/classfile/CodeAssembler.java @ 0:3dc0c5604566
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 } |