Thu, 12 Oct 2017 19:44:07 +0800
merge
1 /*
2 * Copyright (c) 1997, 2010, 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 */
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"];
45 m1 [label="JMethod"];
46 m2 [label="JMethod"];
48 cls1 -> m1;
49 cls1 -> m2;
50 cls1 -> JField;
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;
114 import java.util.List;
115 import java.util.Map;