CodeAssembler


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:--> 13 <!-- $-->, <!--$$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 }
665
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags