1 /* 2 * Copyright (c) 1997, 2015, 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 * <p> 39 * You bulid this tree mostly from top-down. So, you first create 40 * a new {@link JDefinedClass} from {@link JCodeModel}, then you 41 * create a {@link JMethod} from {@link JDefinedClass}, and so on. 42 * 43 * <p> 44 * This design brings the following beneefits: 45 * 46 * <ul> 47 * <li>source code can be written in random order 48 * <li>generated source code nicely imports other classes 49 * <li>generated source code is lexically always correct 50 * (no unbalanced parenthesis, etc.) 51 * <li>code generation becomes relatively type-safe 52 * </ul> 53 * 54 * The price you pay for that is 55 * increased memory footprint and the generation speed. 56 * See <a href="#performance">performance section</a> for 57 * more discussions about the performance and possible improvements. 58 * 59 * 60 * <h2>Using CodeModel</h2> 61 * <p> 62 * {@link com.sun.codemodel.internal.JCodeModel} is the entry point to 63 * the library. See its javadoc for more details about how to use 64 * CodeModel. 65 * 66 * 67 * 68 * <h2>Performance</h2> 69 * <p> 70 * Generally speaking, CodeModel is expected to be used in 71 * an environment where the resource constraint is not severe. 72 * Therefore, we haven't spent much effort in trying to make 73 * this library lean and mean. 74 * 75 * <p> 76 * That said, we did some benchmark and performance analysis. 77 * In case anyone is interested in making this library 78 * better performance wise, here's the findings. 79 * 80 * <p> 81 * {@link List}s {@link Map}s, and other collections take up 82 * a lot of space. Allocating those things lazily is generally 83 * a good idea. 84 * 85 * <p> 86 * Compared to template-based code generator, the writing operation 87 * is slow, as it needs to traverse each AST node. Consider 88 * pre-encoding tokens (like 'public') to the target encoding, 89 * and consider exploting the subtree equivalence. 90 * 91 */ 92 package com.sun.codemodel.internal; 93 94 import java.util.List; 95 import java.util.Map;