1 /*

     2  * Copyright 2006 Sun Microsystems, Inc.  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.  Sun designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any 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;