1 /* 2 * Copyright (c) 1997, 2012, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 /** 27 * <h1>Library for generating Java source code</h1>. 28 * 29 * <p> 30 * CodeModel is a library that allows you to generate Java source 31 * code in a type-safe fashion. 32 * 33 * <p> 34 * With CodeModel, you build the java source code by first building AST, 35 * then writing it out as text files that is Java source files. 36 * The AST looks like this: 37 * 38 * {@DotDiagram 39 digraph G { 40 cls1 [label="JDefinedClass"]; 41 cls2 [label="JDefinedClass"]; 42 JCodeModel -> cls1 [label="generated class"]; 43 JCodeModel -> cls2 [label="generated class"]; 44 45 m1 [label="JMethod"]; 46 m2 [label="JMethod"]; 47 48 cls1 -> m1; 49 cls1 -> m2; 50 cls1 -> JField; 51 52 m1 -> JVar [label="method parameter"]; 53 m1 -> JBlock [label="code"]; 54 } 55 * } 56 * 57 * <p> 58 * You bulid this tree mostly from top-down. So, you first create 59 * a new {@link JDefinedClass} from {@link JCodeModel}, then you 60 * create a {@link JMethod} from {@link JDefinedClass}, and so on. 61 * 62 * <p> 63 * This design brings the following beneefits: 64 * 65 * <ul> 66 * <li>source code can be written in random order 67 * <li>generated source code nicely imports other classes 68 * <li>generated source code is lexically always correct 69 * (no unbalanced parenthesis, etc.) 70 * <li>code generation becomes relatively type-safe 71 * </ul> 72 * 73 * The price you pay for that is 74 * increased memory footprint and the generation speed. 75 * See <a href="#performance">performance section</a> for 76 * more discussions about the performance and possible improvements. 77 * 78 * 79 * <h2>Using CodeModel</h2> 80 * <p> 81 * {@link com.sun.codemodel.internal.JCodeModel} is the entry point to 82 * the library. See its javadoc for more details about how to use 83 * CodeModel. 84 * 85 * 86 * 87 * <h2>Performance</h2> 88 * <p> 89 * Generally speaking, CodeModel is expected to be used in 90 * an environment where the resource constraint is not severe. 91 * Therefore, we haven't spent much effort in trying to make 92 * this library lean and mean. 93 * 94 * <p> 95 * That said, we did some benchmark and performance analysis. 96 * In case anyone is interested in making this library 97 * better performance wise, here's the findings. 98 * 99 * <p> 100 * {@link List}s {@link Map}s, and other collections take up 101 * a lot of space. Allocating those things lazily is generally 102 * a good idea. 103 * 104 * <p> 105 * Compared to template-based code generator, the writing operation 106 * is slow, as it needs to traverse each AST node. Consider 107 * pre-encoding tokens (like 'public') to the target encoding, 108 * and consider exploting the subtree equivalence. 109 * 110 * @ArchitectureDocument 111 */ 112 package com.sun.codemodel.internal; 113 114 import java.util.List; 115 import java.util.Map;