View Javadoc

1   /*
2    * Copyright 2006 Outsource Cafe, Inc.
3    *
4    * Licensed under the Apache License, Version 2.0 (the 'License')
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *    http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an 'AS IS' BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.javagen.agile.core.emitter;
17  
18  import java.io.File;
19  
20  import org.javagen.agile.core.context.Context;
21  
22  /***
23   * An artifact is any type of file emitted by the code generator.  Artifacts have an output directory
24   * and file name which are combined to form the final output location.  
25   * <p>
26   * One of the main purposes of an
27   * artifact is to obtain the output file name and path using the same context properties that templates
28   * use.  This allows consistent, centralized naming patterns.
29   * <p>
30   * The <code>DefaultArtifact</code> uses two keys by default to obtain the <code>outputDirectory</code>
31   * and <code>outputFileName</code>, <code>Keys.OUTPUT_DIRECTORY_TEMPLATE("outputDirectoryTemplate")</code> and 
32   * <code>Keys.FILE_NAME_TEMPLATE("fileNameTemplate")</code> respectively.  These names are built by recursively
33   * applying values to replacement holders until a pure string is obtained.  
34   * <p>
35   * Because the replacement
36   * holders are scattered around the context tree, it can be confusing how a name is derived.  Here
37   * are two concrete examples of name derivation for the <code>Address</code> model instance applied to
38   * the <code>DAO</code> template:
39   * <pre>
40   * targetDirectory=/dev/myRevGen
41   * srcDirectory=${targetDirectory}/src/main/java
42   * outputDirectoryTemplate=${srcDirectory}
43   * </pre>
44   * These values result in the base source directory for Java output:<br/> 
45   * <code>outputDirectoryTemplate=/dev/myRevGen/src/main/java</code>.
46   * 
47   * <pre>
48   * basePackageName=org/revgen/example
49   * relativePackageName=/sales
50   * daoPackageNameTemplate=#{basePackageName}/dao#{relativePackageName}
51   * daoNameTemplate=#{entityName}DAO"/>
52   * fileNameTemplate=#{packageNameTemplate}/#{classNameTemplate}.java
53   * </pre>
54   * 
55   * These values result in the relative path and Java file name output:<br/> 
56   * <code>fileNameTemplate=org/revgen/example/sales/AddressDAO.java</code>.
57   * <p>
58   * If you're paying attention you will have noticed
59   * three missing properties.  <code>entityName</code> is added to the context dynamiclly by calling
60   * <code>context.put("entityName", model.getName())</code>.  The remaining two values are set in the 
61   * <code>DAO</code> emitter context configuration because there are unique to the <code>DAO</code> template:
62   * 
63   * <pre>
64   *  classNameTemplate=#{daoNameTemplate}
65   *  packageNameTemplate=#{daoPackageNameTemplate}
66   * </pre>
67   * 
68   * @author Richard Easterling
69   */
70  public interface Artifact {
71  
72      /***
73       * Given a context determine the base output directory for this artifact.  Common template key examples are:
74       * <code>outputDirectoryTemplate</code>, <code>outputTestDirectoryTemplate</code>
75       * and <code>outputResourceDirectoryTemplate</code>.
76       * 
77       * @param context typically a composite of leaf, parent and emitter contexts.
78       * @return output directory.
79       */
80  	File outputDirectory(Context context);
81  	
82      /***
83      * Given a context determine the file name for this artifact.
84       * @param context typically a composite of leaf, parent and emitter contexts.
85       * @return concatination of file name and file extension if it exists
86       */
87  	File outputFileName(Context context);
88  	
89  }