1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 package org.javagen.agile.core.model;
17
18 import java.util.List;
19
20 import org.javagen.agile.core.context.ContextHolder;
21
22 /***
23 * A Model is the basic unit of metadata used to drive code generation in JavaGen light.
24 * This interface was designed to be as simple as possible to model the structural
25 * aspects of code or data. It is also 'light' in the sense that no attempt was made to
26 * model behavior.
27 * <p>
28 * All models have <code>name</code>, <code>id</code> and <code>ModelType</code> properties.
29 * Each model also has a map of key-value pairs (aka context) allowing arbitrary
30 * values to be associated with a given model instance. Contexts are combined with parent contexts
31 * in such a way that child values override parent values providing a customization mechanism (for
32 * naming patterns for example).
33 * <p>Super classes should be designed as specific as possible to the particular domain they target.
34 * When a model from one domain is related or generated from another model instance in another domain
35 * use context references to link the two rather than properties that hard-code the two domains together.
36 * This keeps the two domains pure and more reusable in other code generation applications.
37 * <p>Models play a second role as templates for customization in conjunction with XML serialization.
38 * This only works if properties can be nullable (ie are non-primitive types) and sub classes should stick
39 * to this convention.
40 *
41 * @author Richrd Easterling
42 */
43 public interface Model extends ContextHolder {
44
45 /***
46 * Default modelType value for generic model instances.
47 */
48 public static final String DEFAULT_MODEL_TYPE = "MODEL";
49
50 /***
51 * A name that describes what is being modeled and forms the basis of the generated artifact names.
52 * A name should be unique among its siblings to allow <code>lookupChildByName</code> to work effectively.
53 */
54 String getName();
55 void setName(String name);
56
57 /***
58 * Ids are used to serialize Model references and allow fast lookups of unique Model instances.
59 * An id should be unique across the entire model tree. Visitors are provided to generate and index Ids.
60 */
61 String getId();
62 void setId(String id);
63
64 /***
65 * A modelType is just that, the type of thing being modeled. Examples are: 'entity', 'primaryKey', 'table', 'class'.
66 * ModelTypes are used to bind emitters (ie templates) to model instances. Sets of modelTypes are also used to form
67 * itineraries that control which nodes are visited during model tree traversal.
68 */
69 String getModelType();
70 void setModelType(String modelType);
71
72 /***
73 * A parent is usually the owner or source of the child node. For example
74 * a Table would be the parent of a Column in the database realm and a Class
75 * would be the parent of a Property in the object oriented realm.
76 * Non-artifact producing parent nodes may also be used to provide global context values or
77 * contain groups of related model instances.
78 * A given model instance can only have one parent.
79 * @return the parent model or null if this is the root node of the tree.
80 */
81 Model getParentModel();
82 void setParentModel(Model parent);
83
84 /***
85 * @return a list of child models or an empty list.
86 */
87 List<Model> getChildModels();
88 void setChildModels(List<Model> childModels);
89 void addChildModel(Model child);
90 Model lookupChildByName(String name);
91 /***
92 * This method is used by the visitor patterns to navigate the model tree hierarchy.
93 * It is provided to handle exceptional cases were the child instances are held in 2
94 * or more collections (ie not all in childModels List) in which case it returns the
95 * union of the child collections. Most of the time it just calls <code>getChildModles</code>.
96 * @return union of the child models.
97 */
98 List<Model> allOwnedModels();
99
100 /***
101 * Convienience method to access the local context of key-value pairs.
102 * Context is used to hold arbitrary key-value pairs. Common uses are to
103 * hold value-replacement templates used in customizing artifact names or
104 * to store references to other model instances needed for model
105 * or template processing.
106 * @param key a unique string value.
107 * @return value given a unique key
108 */
109 Object get(String key);
110 void put(String key, Object value);
111
112 /***
113 * Copy non-null properties into target model instance. Child values are generally not copied.
114 * Used in conjunction with XML serialization to allow individual model instances to be
115 * custimized.
116 * @param target model to set properties on
117 */
118 void copyTo(Model target);
119 }