Skip to Content

Wiki source code of EOF-Using EOF-EOGenerator

Version 11.1 by David Avendasora on 2011/05/24 12:57
Show last authors
1 |= Contents
2 | {{toc style="disc" minLevel="2"}}{{/toc}}
3
4 == Overview ==
5
6 If you've ever used EOModeler's Java source code generator, you know how much of a pain it can be when you make changes to your model objects and have to merge changes in later. One solution for this is to use [[EOGenerator>>http://www.rubicode.com/Software/EOGenerator/]], an application developed by Rubicode Software, which uses the Generation Gap pattern to create your Java files from your EOModels. EOGenerator produces TWO java files for each Entity rather than one. Take the example of a Person entity. The first java file is Person.java, which contains all of the autogenerated methods. The second java file is Person.java, and Person extends Person. The second file is where you place all of your customizations. Any time your model changes, only your Xxx.java files are updated, and your customizations are left untouched. Additionally, EOGenerator allows for the creation of extensive custom templates for your files, which provides the ability to place convenience methods in your Xxx.java files.
7
8 {{warning}}
9
10 EOGenerator doesn't work on Mac OS X 10.5. You have to use [JavaEOGenerator|http://developer.apple.com/samplecode/JavaEOGenerator/] or [Velocity EOGenerator|WOL:Velocity EOGenerator (Veogen)].
11
12 {{/warning}}
13
14 == Advantages ==
15
16 There are several advantages to using EOGenerator over EOModeler's default Java file generation and merging with FileMerge.
17
18 * EOGenerator uses the Generation Gap pattern, which provides a much cleaner separation of autogenerated vs customized code with no need to deal with merging at all. There are border cases with FileMerge that can cause you to deal with annoying conflicts.
19 * EOGenerator uses the MiscMerge language for its templates. This allows you to extend the core templates with extensive customizations (see the EOGenerator Mods section below), better supporting your own custom development process and workflow.
20 * As David LaBer put it, "all the cool kids use it - and we all know looking cool is the **most** important criteria".
21
22 == How To Use It ==
23
24 Kieran Kelleher has writtten an [[Introduction to EOGenerator>>http://homepage.mac.com/kelleherk/iblog/C1837526061/E1908382110/index.html]] on his blog.
25
26 It's actually very simple to use. The quick start is:
27
28 * Download and untar EOGenerator from the Rubicode site
29 * Run the following command:
30
31 {{panel}}
32
33 eogenerator \-model /path/to/model/YourModel.eomodeld \-destination /path/to/source/folder
34 \-subclassDestination /path/to/source/folder \-templatedir /path/to/EOGenerator/templates \-java \-packagedirs
35
36 {{/panel}}
37
38 Voila. EOGenerator will spit out your Java files for you. Let's break down the commands you can pass in:
39
40 * define-EOGenericRecord <class>, allows you to specify the Person class's superclass. For instance, if you use Project Wonder, you would specify define-EOGenericRecord er.extensions.ERXGenericRecord
41 * destination <path>, the folder that Person.java-style java files will be produced in (the non-editable files)
42 * java, produce java files
43 * javaTemplate <filename>, the name of the Java template to use inside of the template dir (//Person)//
44 * model <path>, Passes in the path of a .eomodeld you would like to generate Java files for. You can actually include multiple model commands on the commandline
45 * packagedirs, produce package directory for any package statements defined in your Java files (not necessary if you don't specify package names on your entities. By the way, you should specify packages on your entities :-) )
46 * refmodel <path>, Passes in the path of an .eomodeld that is required for generating Java files, but that won't actually have Java files generated for it. For instance, you should refmodel any prototypes, or any models in other frameworks that you depend on
47 * subclassDestination <path>, the folder that Person.java-style java files will be produced in (the editable files)
48 * subclassJavaTemplate <filename>, the name of the Java subclass template to use inside of the template dir (Person)
49 * templatedir <path>, the path to the folder that contains EOGenerator templates
50 * verbose, turn on verbose output
51
52 == Custom EOGenerator Mods ==
53
54 === Zak Burke ===
55
56 Allow setting nulls on a to-one relationship (and turn it into a remove). Note, this is also included in Jonathan Rentzsch's templates.
57
58 {{code}}
59
60 public void save<$ToOneRelationship.name.initialCapitalString$>(<$ToOneRelationship.destinationEntity.referenceJavaClassName$> value)
61 {
62 if (value == null)
63 {
64 <$ToOneRelationship.destinationEntity.referenceJavaClassName$> object = <$ToOneRelationship.name$>();
65 if (object != null)
66 removeObjectFromBothSidesOfRelationshipWithKey(object, "<$ToOneRelationship.name$>");
67 }
68 else
69 {
70 addObjectToBothSidesOfRelationshipWithKey(value, "<$ToOneRelationship.name$>");
71 }
72 }
73
74 {{/code}}
75
76 === Chuck Hill ===
77
78 Return the list of changes between the current EO and the last committed version of the EO:
79
80 {{code}}
81
82 public NSDictionary changedProperties() {
83 NSDictionary commitedValues = editingContext().committedSnapshotForObject(this);
84 return changesFromSnapshot(commitedValues);
85 }
86
87 {{/code}}
88
89 === Jonathan Rentzsch ===
90
91 Jonathan Rentzsch has provided his base EOGenerator templates, which are a must-have:
92
93 [[http://rentzsch.com/share/eogenerator52templates.zip]]
94
95 === Markus Ruggiero ===
96
97 Constants for all attributes and relationships. This allows compile time error checking in situations like
98 addObjecttoBothSidesOfRelationshipWithKey(myObject, Person.TO//MANY//Children)
99
100 {{code}}
101
102 <$foreach attribute classAttributes.@reversedArray do$>
103 public static final String ATTRIBUTE_<$attribute.name$> = "<$attribute.name$>";<$endforeach do$>
104
105 <$foreach ToOneRelationship classToOneRelationships.@reversedArray do$>
106 public static final String TO_ONE_<$ToOneRelationship.name$> = "<$ToOneRelationship.name$>";<$endforeach do$>
107
108 <$foreach ToManyRelationship classToManyRelationships.@reversedArray do$>
109 public static final String TO_MANY_<$ToManyRelationship.name$> = "<$ToManyRelationship.name$>";<$endforeach do$>
110
111 {{/code}}
112
113 We also make heavy use of the user info dictionary on entity and attribute level. Allows to generate customized methods and what not. One example is booleans that are stored in the DB as strings with values "true" and "false".
114
115 {{code}}
116
117 <$if attribute.userInfo.usage h1. booleanFlag $> // boolean accessors
118 public void <$attribute.userInfo.setterName$>(boolean newBoolean) {
119 set<$attribute.name.initialCapitalString$>(newBoolean ? "true" : "false");
120 }
121
122 public boolean <$attribute.userInfo.getterName$>() {
123 return "true".equals(<$attribute.name$>()) ? true : false;
124 }
125
126 // validation
127 public String validate<$attribute.name.initialCapitalString$>(String newValue) {
128 if ( newValue null ) {
129 return "false";
130 } else if ( !newValue.equals("true") && !newValue.equals("false") ) {
131 String errorMessage = MessageHandler.format("INVALID_BOOLEAN_FLAG <$classNameWithoutPackage$>.<$attribute.name$>", null);
132 throw new NSValidation.ValidationException(errorMessage);
133 }
134 return newValue;
135 }
136 <$endif$>
137
138 {{/code}}
139
140 === Mike Schrag ===
141
142 Add a constant that represents the name of the entity so that you can refer to Person.ENTITY//NAME in fetches rather than the String (allows refactoring support in Eclipse)~://
143
144 {{code}}
145
146 public static final String ENTITY_NAME = "<$name$>";
147
148 {{/code}}
149
150 Add a static factory method to your EO's ( Person createPerson(...) ) that shows you what required attributes and relationships are configured for you entity (attempts to provide a replacement "constructor" since EO constructors are empty):
151
152 {{code}}
153
154 public static <$classNameWithoutPackage$> create<$classNameWithoutPackage$>(EOEditingContext _editingContext<$foreach Attribute classAttributes.@sortedNameArray do$><$if !Attribute.allowsNull$>, <$Attribute.javaValueClassName$> _<$Attribute.name$><$endif$><$endforeach do$><$foreach ToOneRelationship classToOneRelationships.@sortedNameArray do$><$if ToOneRelationship.isMandatory$>, <$ToOneRelationship.destinationEntity.referenceJavaClassName$> _<$ToOneRelationship.name$><$endif$><$endforeach do$>) {
155 <$classNameWithoutPackage$> eoObject = (<$classNameWithoutPackage$>)EOUtilities.createAndInsertInstance(_editingContext, <$GEN_PREFIX$><$classNameWithoutPackage$>.ENTITY_NAME);<$foreach Attribute classAttributes.@sortedNameArray do$><$if !Attribute.allowsNull$>
156 eoObject.set<$Attribute.name.initialCapitalString$>(_<$Attribute.name$>);<$endif$><$endforeach do$><$foreach ToOneRelationship classToOneRelationships.@sortedNameArray do$><$if ToOneRelationship.isMandatory$>
157 eoObject.set<$ToOneRelationship.name.initialCapitalString$>Relationship(_<$ToOneRelationship.name$>);<$endif$><$endforeach do$>
158 return eoObject;
159 }
160
161 {{/code}}
162
163 Here's a little bitty fancier (read: nastier) version that also handles superclass mandatory attributes and fields (one level). It skips any attribute that is referenced in the restricting qualifier of your subclass (since you are probably going to set that in your awakeFromInsertion):
164
165 {{code}}
166
167 public static <$classNameWithoutPackage$> create<$classNameWithoutPackage$>(EOEditingContext editingContext<$foreach Attribute classAttributes.@sortedNameArray do$><$if !Attribute.allowsNull$>, <$Attribute.javaValueClassName$> <$Attribute.name$><$endif$><$endforeach do$><$foreach Attribute parentEntity.classAttributes.@sortedNameArray do$><$if !Attribute.allowsNull$><$set RestrictingQualifierKey = false$><$foreach QualifierKey restrictingQualifier.allQualifierKeys do$><$if Attribute.name = QualifierKey$><$set RestrictingQualifierKey = true$><$endif$><$endforeach do$><$if RestrictingQualifierKey = false$>, <$Attribute.javaValueClassName$> <$Attribute.name$><$endif$><$endif$><$endforeach do$><$foreach ToOneRelationship classToOneRelationships.@sortedNameArray do$><$if ToOneRelationship.isMandatory$>, <$ToOneRelationship.destinationEntity.referenceJavaClassName$> <$ToOneRelationship.name$><$endif$><$endforeach do$><$foreach ToOneRelationship parentEntity.classToOneRelationships.@sortedNameArray do$><$if ToOneRelationship.isMandatory$>, <$ToOneRelationship.destinationEntity.referenceJavaClassName$> <$ToOneRelationship.name$><$endif$><$endforeach do$>) {
168 <$classNameWithoutPackage$> eoObject = (<$classNameWithoutPackage$>)EOUtilities.createAndInsertInstance(editingContext, <$GEN_PREFIX$><$classNameWithoutPackage$>.ENTITY_NAME);<$foreach Attribute classAttributes.@sortedNameArray do$><$if !Attribute.allowsNull$>
169 eoObject.set<$Attribute.name.initialCapitalString$>(<$Attribute.name$>);<$endif$><$endforeach do$><$foreach ToOneRelationship classToOneRelationships.@sortedNameArray do$><$if ToOneRelationship.isMandatory$>
170 eoObject.set<$ToOneRelationship.name.initialCapitalString$>Relationship(<$ToOneRelationship.name$>);<$endif$><$endforeach do$><$foreach Attribute parentEntity.classAttributes.@sortedNameArray do$><$if !Attribute.allowsNull$><$set RestrictingQualifierKey = false$><$foreach QualifierKey restrictingQualifier.allQualifierKeys do$><$if Attribute.name = QualifierKey$><$set RestrictingQualifierKey = true$><$endif$><$endforeach do$><$if RestrictingQualifierKey = false$>
171 eoObject.set<$Attribute.name.initialCapitalString$>(<$Attribute.name$>);<$endif$><$endif$><$endforeach do$><$foreach ToOneRelationship parentEntity.classToOneRelationships.@sortedNameArray do$><$if ToOneRelationship.isMandatory$>
172 eoObject.set<$ToOneRelationship.name.initialCapitalString$>Relationship(<$ToOneRelationship.name$>);<$endif$><$endforeach do$>
173 return eoObject;
174 }
175
176 {{/code}}
177
178 Add a bunch of convience fetch methods (fetchAllPersons, fetchRequiredPerson, and other variants). It's not smart about pluralization, so it's just going to put an "s" on the end of the entity name:
179
180 {{code}}
181
182 public static NSArray fetchAll<$classNameWithoutPackage$>s(EOEditingContext _editingContext) {
183 return <$GEN_PREFIX$><$classNameWithoutPackage$>.fetchAll<$classNameWithoutPackage$>s(_editingContext, null);
184 }
185
186 {{/code}}
187
188 {{code}}
189
190 public static NSArray fetchAll<$classNameWithoutPackage$>s(EOEditingContext _editingContext, NSArray _sortOrderings) {
191 return <$GEN_PREFIX$><$classNameWithoutPackage$>.fetch<$classNameWithoutPackage$>s(_editingContext, null, _sortOrderings);
192 }
193
194 {{/code}}
195
196 {{code}}
197
198 public static NSArray fetch<$classNameWithoutPackage$>s(EOEditingContext _editingContext, EOQualifier _qualifier, NSArray _sortOrderings) {
199 EOFetchSpecification fetchSpec = new EOFetchSpecification(<$GEN_PREFIX$><$classNameWithoutPackage$>.ENTITY_NAME, _qualifier, _sortOrderings);
200 fetchSpec.setIsDeep(true);
201 NSArray eoObjects = _editingContext.objectsWithFetchSpecification(fetchSpec);
202 return eoObjects;
203 }
204
205 {{/code}}
206
207 {{code}}
208
209 public static <$classNameWithoutPackage$> fetch<$classNameWithoutPackage$>(EOEditingContext _editingContext, String _keyName, Object _value) {
210 return <$GEN_PREFIX$><$classNameWithoutPackage$>.fetch<$classNameWithoutPackage$>(_editingContext, new EOKeyValueQualifier(_keyName, EOQualifier.QualifierOperatorEqual, _value));
211 }
212
213 {{/code}}
214
215 {{code}}
216
217 public static <$classNameWithoutPackage$> fetch<$classNameWithoutPackage$>(EOEditingContext _editingContext, EOQualifier _qualifier) {
218 NSArray eoObjects = <$GEN_PREFIX$><$classNameWithoutPackage$>.fetch<$classNameWithoutPackage$>s(_editingContext, _qualifier, null);
219 <$classNameWithoutPackage$> eoObject;
220 int count = eoObjects.count();
221 if (count == 0) {
222 eoObject = null;
223 }
224 else if (count == 1) {
225 eoObject = (<$classNameWithoutPackage$>)eoObjects.objectAtIndex(0);
226 }
227 else {
228 throw new IllegalStateException("There was more than one <$classNameWithoutPackage$> that matched the qualifier '" + _qualifier + "'.");
229 }
230 return eoObject;
231 }
232
233 {{/code}}
234
235 {{code}}
236
237 public static <$classNameWithoutPackage$> fetchRequired<$classNameWithoutPackage$>(EOEditingContext _editingContext, String _keyName, Object _value) {
238 return <$GEN_PREFIX$><$classNameWithoutPackage$>.fetchRequired<$classNameWithoutPackage$>(_editingContext, new EOKeyValueQualifier(_keyName, EOQualifier.QualifierOperatorEqual, _value));
239 }
240
241 {{/code}}
242
243 {{code}}
244
245 public static <$classNameWithoutPackage$> fetchRequired<$classNameWithoutPackage$>(EOEditingContext _editingContext, EOQualifier _qualifier) {
246 <$classNameWithoutPackage$> eoObject = <$GEN_PREFIX$><$classNameWithoutPackage$>.fetch<$classNameWithoutPackage$>(_editingContext, _qualifier);
247 if (eoObject == null) {
248 throw new NoSuchElementException("There was no <$classNameWithoutPackage$> that matched the qualifier '" + _qualifier + "'.");
249 }
250 return eoObject;
251 }
252
253 {{/code}}
254
255 Add methods for getting local instances of EO's. The static one is handy if you have a reference to an EO that might be null (it does a null check first):
256
257 {{code}}
258
259 public <$classNameWithoutPackage$> localInstanceOf<$classNameWithoutPackage$>(EOEditingContext _editingContext) {
260 return (<$classNameWithoutPackage$>)EOUtilities.localInstanceOfObject(_editingContext, this);
261 }
262
263 {{/code}}
264
265 {{code}}
266
267 public static <$classNameWithoutPackage$> localInstanceOf<$classNameWithoutPackage$>(EOEditingContext _editingContext, <$classNameWithoutPackage$> _eo) {
268 return (_eo == null) ? null : (<$classNameWithoutPackage$>)EOUtilities.localInstanceOfObject(_editingContext, _eo);
269 }
270
271 {{/code}}
272
273 If you've ever wanted to be able to qualify a toMany relationship on your EO's, but sometimes you want to fetch them w/ a fetch spec, and sometimes you want to filter in-memory, you can use the following:
274
275 {{code}}
276
277 <$if !ToManyRelationship.inverseRelationship$>
278 public NSArray <$ToManyRelationship.name$>(EOQualifier qualifier) {
279 return <$ToManyRelationship.name$>(qualifier, null);
280 }
281 <$endif$>
282 <$if ToManyRelationship.inverseRelationship$>
283 public NSArray <$ToManyRelationship.name$>(EOQualifier qualifier) {
284 return <$ToManyRelationship.name$>(qualifier, null, false);
285 }
286
287 public NSArray <$ToManyRelationship.name$>(EOQualifier qualifier, boolean fetch) {
288 return <$ToManyRelationship.name$>(qualifier, null, fetch);
289 }
290 <$endif$>
291
292 public NSArray <$ToManyRelationship.name$>(EOQualifier qualifier, NSArray sortOrderings<$if ToManyRelationship.inverseRelationship$>, boolean fetch<$endif$>) {
293 NSArray results;
294 <$if ToManyRelationship.inverseRelationship$>
295 if (fetch) {
296 EOQualifier fullQualifier;
297 EOQualifier inverseQualifier = new EOKeyValueQualifier(<$ToManyRelationship.destination.className$>.
298 <$ToManyRelationship.inverseRelationship.name.uppercaseUnderbarString$>_KEY, EOQualifier.QualifierOperatorEqual, this);
299 if (qualifier == null) {
300 fullQualifier = inverseQualifier;
301 }
302 else {
303 NSMutableArray qualifiers = new NSMutableArray();
304 qualifiers.addObject(qualifier);
305 qualifiers.addObject(inverseQualifier);
306 fullQualifier = new EOAndQualifier(qualifiers);
307 }
308 results = <$ToManyRelationship.destination.className$>.fetch<$ToManyRelationship.destination.name$>s(editingContext(), fullQualifier, sortOrderings);
309 }
310 else {
311 <$endif$>
312 results = <$ToManyRelationship.name$>();
313 if (qualifier != null) {
314 results = EOQualifier.filteredArrayWithQualifier(results, qualifier);
315 }
316 if (sortOrderings != null) {
317 results = EOSortOrdering.sortedArrayUsingKeyOrderArray(results, sortOrderings);
318 }
319 <$if ToManyRelationship.inverseRelationship$>
320 }
321 <$endif$>
322 return results;
323 }
324
325 {{/code}}
326
327 === John Huss ===
328
329 I wanted to share a wonderful bit of knowledge I learned today. If you're using Java 1.5 you can add @SuppressWarnings("all") to the template for your EO base classes and eliminate annoying compiler messages (usually uneeded import statements).
330
331 {{code}}
332
333 @SuppressWarnings("all")
334 public class _Invoice extends ERXGenericRecord {
335 }
336
337 {{/code}}
338
339 === Guido Neitzer ===
340
341 Create awakeFromInsertion() and awakeFromFetch() in your EOGenerator template as a method stub that only calls super() and has a comment for "initialize your object here ...". You only have to put in the code at that place and can't possibly forget to call super(). Here is an example:
342
343 {{code}}
344
345 /**
346 * Initialization of the instance while inserting it into an editing context
347 */
348 public void awakeFromInsertion (EOEditingContext editingContext) {
349 super.awakeFromInsertion (editingContext);
350 // initialize your object here
351 }
352
353 {{/code}}
354
355 This is from my JavaSubclassSourceTemplate.eotemplate