View Javadoc

1   /**
2   The contents of this file are subject to the Mozilla Public License Version 1.1 
3   (the "License"); you may not use this file except in compliance with the License. 
4   You may obtain a copy of the License at http://www.mozilla.org/MPL/ 
5   Software distributed under the License is distributed on an "AS IS" basis, 
6   WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the 
7   specific language governing rights and limitations under the License. 
8   
9   The Original Code is "DBTableRepository.java".  Description: 
10  "Implements TableRepository by looking up values from the default HL7
11    normative database" 
12  
13  The Initial Developer of the Original Code is University Health Network. Copyright (C) 
14  2001.  All Rights Reserved. 
15  
16  Contributor(s): James Agnew
17  				Paul Brohman
18  				Mitch Delachevrotiere
19  				Shawn Dyck
20  				Cory Metcalf
21    				
22  Alternatively, the contents of this file may be used under the terms of the 
23  GNU General Public License (the  ?GPL?), in which case the provisions of the GPL are 
24  applicable instead of those above.  If you wish to allow use of your version of this 
25  file only under the terms of the GPL and not to allow others to use your version 
26  of this file under the MPL, indicate your decision by deleting  the provisions above 
27  and replace  them with the notice and other provisions required by the GPL License.  
28  If you do not delete the provisions above, a recipient may use your version of 
29  this file under either the MPL or the GPL. 
30  
31  */
32  package ca.uhn.hl7v2.conf.classes.generator.builders;
33  
34  import java.util.regex.Pattern;
35  
36  import ca.uhn.hl7v2.conf.spec.message.*;
37  import ca.uhn.hl7v2.conf.classes.generator.genclasses.*;
38  import ca.uhn.hl7v2.conf.spec.*;
39  
40  /** This Class contains some of the Documentation for the Class to be generated
41   * @author <table><tr>James Agnew</tr>
42   *                 <tr>Paul Brohman</tr>
43   *                 <tr>Mitch Delachevrotiere</tr>
44   *                 <tr>Shawn Dyck</tr>
45   * 				   <tr>Cory Metcalf</tr></table>
46   */
47  public final class DocumentationBuilder {
48  
49  	private static DocumentationBuilder documentationBuilder;
50  
51  	/** Returns the singleton instance of the DocumentationBuilder
52  	 * @return the singleton instance of the DocumentationBuilder
53  	 */
54  	public static DocumentationBuilder getDocumentationBuilder() {
55  		if (documentationBuilder == null)
56  			documentationBuilder = new DocumentationBuilder();
57  
58  		return documentationBuilder;
59  	}
60  
61  	/** Default Constructor */
62  	private DocumentationBuilder() {
63  	}
64  
65  	/** Adds a label and it data value to GeneratedClass Comments in a table format
66  	 * @param genClass a GeneratedConformanceContainer
67  	 * @param label optional comment label to add to the class header document table
68  	 * @param data the data value to add to the class header document table
69  	 */
70  	private void addOptionalComment(
71  		GeneratedConformanceContainer genClass,
72  		String label,
73  		String data) {
74  		if (data != null && data != "")
75  			genClass.addClassComment(
76  				"   <tr><td>" + label + "</td><td>" + data + "</td></tr>");
77  	}
78  
79  	/** Adds a label and it data value to Primitive GeneratedClass Comments in a table format
80  	 * @param genClass a GeneratedPrimitive
81  	 * @param label optional comment label to add to the class header document table
82  	 * @param data the data value to add to the class header document table
83  	 */
84  	private void addOptionalComment(
85  		GeneratedPrimitive genClass,
86  		String label,
87  		String data) {
88  		if (data != null && data != "")
89  			genClass.addClassComment(
90  				"   <tr><td>" + label + "</td><td>" + data + "</td></tr>");
91  	}
92  
93  	/** Adds a table of comments to a Generated Component Class
94  	 * @param genClass a GeneratedConformanceContainer
95  	 * @param comp the component for which the comments are being added to
96  	 */
97  	public void decorateComponent(
98  		GeneratedConformanceContainer genClass,
99  		Component comp) {
100 		genClass.addClassComment(
101 			"This class contains and provides access to all SubComponents");
102 		genClass.addClassComment("<table>");
103 		addOptionalComment(genClass, "Name", comp.getName());
104 		addOptionalComment(genClass, "Usage", comp.getUsage());
105 		addOptionalComment(genClass, "Data Type", comp.getDatatype());
106 		addOptionalComment(genClass, "Constant Value", comp.getConstantValue());
107 		addOptionalComment(genClass, "Description", comp.getDescription());
108 		addOptionalComment(genClass, "Implementation Note", comp.getImpNote());
109 		addOptionalComment(genClass, "Predicate", comp.getPredicate());
110 		addOptionalComment(genClass, "Reference", comp.getReference());
111 		addOptionalComment(genClass, "Length", comp.getLength() + "");
112 		if (comp.getLength() != 0)
113 			addOptionalComment(genClass, "Table", comp.getTable() + "");
114 		genClass.addClassComment("</table>");
115 	}
116 
117 	/** Adds a table of comments to a Conformance Message Class
118 	 * @param genClass a GeneratedConformanceMessage
119 	 * @param runtimeProfile the runtimeProfile for which the comments are being added to
120 	 */
121 	public void decorateConformanceMessage(
122 		GeneratedConformanceMessage genClass,
123 		RuntimeProfile runtimeProfile) {
124 		genClass.addToClassComments(
125 			"This class is the primary access class for the HL7 "
126 				+ runtimeProfile.getHL7Version()
127 				+ " "
128 				+ runtimeProfile.getMessage().getMsgType()
129 				+ " Conformance");
130 		genClass.addToClassComments(
131 			"Class Set. This message has the following attributes:<br>");
132 		genClass.addToClassComments("<table>");
133 		genClass.addToClassComments(
134 			"<tr><td>Message Type</td><td>"
135 				+ runtimeProfile.getMessage().getMsgType()
136 				+ "</td></tr>");
137 		genClass.addToClassComments(
138 			"<tr><td>Event Type</td><td>"
139 				+ runtimeProfile.getMessage().getEventType()
140 				+ "</td></tr>");
141 		genClass.addToClassComments(
142 			"<tr><td>HL7 Version</td><td>"
143 				+ runtimeProfile.getHL7Version()
144 				+ "</td></tr>");
145 		genClass.addToClassComments("</table><br><br>");
146 		genClass.addToClassComments("<b>Purpose</b><br>");
147 		genClass.addToClassComments(runtimeProfile.getMessage().getEventDesc());
148 	}
149 
150 	/** Adds Class Comments to a getMaxLength method
151 	 * @param genMethod the Generated Method to add the constant value comments to
152 	 */
153 	public void decorateConstantValue(GeneratedMethod genMethod) {
154 		genMethod.addToDescription(
155 			"Returns the constant value associated with this Data Type");
156 		genMethod.addToComments(
157 			"@return the constant value associated with this Data Type, or <code>null</code> if there is none");
158 
159 	}
160 
161 	/** Adds comments to a generated constructor
162 	 * @param constructor a constructor to add comments to
163 	 * @param msg the message
164 	 */
165 	public void decorateConstructor(GeneratedMethod constructor, String className) {
166 		constructor.addToDescription("Default constructor for Conformance_HL7_" + className + ". Has the");
167 		constructor.addToDescription("following functions:");
168 		constructor.addToDescription("<ul><li>Instantiating all required Conformance Classes in the structure");
169 		constructor.addToDescription("    <li>Instantiating the underlying HAPI Message object");
170 		constructor.addToDescription("    <li>Populating any constant values");
171 		constructor.addToDescription("</ul>");
172 
173 	}
174 
175 	/** Adds Class Comments to a Generated Field Class
176 	 * @param genClass a GeneratedConformanceContainer
177 	 * @param field the field for which the comments are being added to
178 	 */
179 	public void decorateField(
180 		GeneratedConformanceContainer genClass,
181 		Field field) {
182 		genClass.addClassComment(
183 			"This represents a constrained "
184 				+ field.getName()
185 				+ " field, with the following proerties:");
186 		genClass.addClassComment("<table>");
187 		addOptionalComment(genClass, "Name", field.getName());
188 		addOptionalComment(genClass, "Usage", field.getUsage());
189 		addOptionalComment(genClass, "Description", field.getDescription());
190 		addOptionalComment(genClass, "Implementation Note", field.getImpNote());
191 		addOptionalComment(genClass, "Predicate", field.getPredicate());
192 		addOptionalComment(genClass, "Reference", field.getReference());
193 		addOptionalComment(
194 			genClass,
195 			"Minimum Repetitions ",
196 			field.getMin() + "");
197 		addOptionalComment(
198 			genClass,
199 			"Maximum Repetitions ",
200 			field.getMax() + "");
201 		genClass.addClassComment("</table>");
202 	}
203 
204 	/** Adds Class Comments to a getMaxLength method
205 	 * @param genMethod a GeneratedMethod
206 	 */
207 	public void decorateMaxLength(GeneratedMethod genMethod) {
208 		genMethod.addToDescription(
209 			"Returns the Maximum allowable length for the Data Type");
210 		genMethod.addToComments(
211 			"@return the maximum allowable length of the Data Type");
212 
213 	}
214 
215 	/** Adds Class Comments to a Maximum Repition Method
216 	 * @param genClass a GeneratedConformanceContainer
217 	 * @param genMethod the GeneratedMethod for which the comments are being added to
218 	 */
219 	public void decorateMaxReps(GeneratedMethod genMethod) {
220 
221 		genMethod.addToDescription("This method returns the maximum allowable");
222 		genMethod.addToComments("repetitions of this object.");
223 		genMethod.addToComments("@return maximum allowable repetitions");
224 
225 	}
226 
227 	/** Adds Class Comments to a Minimum Repition Method
228 	 * @param genClass a GeneratedConformanceContainer
229 	 * @param genMethod the GeneratedMethod for which the comments are being added to
230 	 */
231 	public void decorateMinReps(GeneratedMethod genMethod) {
232 
233 		genMethod.addToDescription("This method returns the minimum allowable");
234 		genMethod.addToComments("repetitions of this object.");
235 		genMethod.addToComments("@return minimum allowable repetitions");
236 
237 	}
238 
239 	/** Adds Class Comments to a Generated Primitive Class
240 	 * @param genClass a GeneratedConformanceContainer
241 	 * @param ac the AbstractComponent for which the comments are being added to
242 	 */
243 	public void decoratePrimitive(
244 		GeneratedPrimitive genClass,
245 		AbstractComponent ac) {
246 		genClass.addClassComment(
247 			"This represents a constrained "
248 				+ ac.getName()
249 				+ " field, with the following properties:");
250 		genClass.addClassComment("<table>");
251 		addOptionalComment(genClass, "Name", ac.getName());
252 		addOptionalComment(genClass, "Usage", ac.getUsage());
253 		addOptionalComment(genClass, "Data Type", ac.getDatatype());
254 		addOptionalComment(genClass, "Constant Value", ac.getConstantValue());
255 		addOptionalComment(genClass, "Description", ac.getDescription());
256 		addOptionalComment(genClass, "Implementation Note", ac.getImpNote());
257 		addOptionalComment(genClass, "Predicate", ac.getPredicate());
258 		addOptionalComment(genClass, "Reference", ac.getReference());
259 		addOptionalComment(genClass, "Length", ac.getLength() + "");
260 		if (ac.getTable() != null && Pattern.matches("[^0]", ac.getTable()))
261 			addOptionalComment(genClass, "Table", ac.getTable() + "");
262 		genClass.addClassComment("</table>");
263 	}
264 
265 	/** Adds Class Comments to a Generated Class
266 	 * @param genClass a GeneratedConformanceContainer
267 	 * @param ps the Profile Structure for which the comments are being added to
268 	 */
269 	public void decorateProfileStructure(
270 		GeneratedConformanceContainer genClass,
271 		ProfileStructure ps) {
272 		genClass.addClassComment(
273 			"This represents a constrained "
274 				+ ps.getName()
275 				+ " segment, with the following properties:");
276 		genClass.addClassComment("<table>");
277 		addOptionalComment(genClass, "Name", ps.getName());
278 		addOptionalComment(genClass, "Usage", ps.getUsage());
279 		addOptionalComment(genClass, "Description", ps.getDescription());
280 		addOptionalComment(genClass, "Implementation Note", ps.getImpNote());
281 		addOptionalComment(genClass, "Predicate", ps.getPredicate());
282 		addOptionalComment(genClass, "Reference", ps.getReference());
283 		addOptionalComment(genClass, "Minimum Repetitions ", ps.getMin() + "");
284 		addOptionalComment(genClass, "Maximum Repetitions ", ps.getMax() + "");
285 		genClass.addClassComment("</table>");
286 	}
287 
288 	/** Adds Class Comments to a Generated Method
289 	 * @param genMethod a GeneratedRepGetter
290 	 * @param field the field for which the comments are being added to
291 	 * @param repType the repetition Type
292 	 */
293 	public void decorateRepGetter(
294 		GeneratedRepGetter genMethod,
295 		Field field,
296 		String repType) {
297 
298 		genMethod.addToDescription(
299 			"This method returns a reference to the "
300 				+ field.getName()
301 				+ " field belonging to this segment.");
302 		genMethod.addToComments("Min Repetitions " + field.getMin());
303 		genMethod.addToComments("Max Repetitions " + field.getMax());
304 		if (field.getMax() == -1)
305 			genMethod.addToComments("@param rep The desired repetition number");
306 		genMethod.addToComments(
307 			"@return the child object reference. <b>rep must fall between "
308 				+ field.getMin()
309 				+ " and "
310 				+ field.getMax()
311 				+ "</b>");
312 		genMethod.addToComments(
313 			"@throws ca.uhn.hl7v2.conf.classes.exceptions.ConfRepException");
314 
315 	}
316 
317 	/** Adds Class Comments to a Generated Method
318 	 * @param genMethod a GeneratedRepGetter
319 	 * @param profileStructure the Profile Structure for which the comments are being added to
320 	 * @param repType the repetition Type
321 	 */
322 	public void decorateRepGetter(
323 		GeneratedRepGetter genMethod,
324 		ProfileStructure profileStructure,
325 		String repType) {
326 
327 		genMethod.addToDescription(
328 			"This method returns a reference to the "
329 				+ profileStructure.getName()
330 				+ " child.");
331 		genMethod.addToComments("Min Repetitions" + profileStructure.getMin());
332 		genMethod.addToComments("Max Repetitions" + profileStructure.getMax());
333 		if (profileStructure.getMax() == -1)
334 			genMethod.addToComments("@param rep The desired repetition number");
335 		genMethod.addToComments(
336 			"@return the child object reference. <b>rep must fall between "
337 				+ profileStructure.getMin()
338 				+ " and "
339 				+ profileStructure.getMax()
340 				+ "</b>");
341 		genMethod.addToComments(
342 			"@throws ca.uhn.hl7v2.conf.classes.exceptions.ConfRepException");
343 
344 	}
345 
346 	/** Adds Class Comments to a Generated SegGroup Class
347 	 * @param genClass a GeneratedConformanceContainer
348 	 * @param segGroup the SegGroup for which the comments are being added to
349 	 */
350 	public void decorateSegGroup(
351 		GeneratedConformanceContainer genClass,
352 		SegGroup segGroup) {
353 		this.decorateProfileStructure(genClass, segGroup);
354 	}
355 
356 	/** Adds Class Comments to a Generated Segment Class
357 	 * @param genClass a GeneratedConformanceContainer
358 	 * @param seg the Segment for which the comments are being added to
359 	 */
360 	public void decorateSegment(
361 		GeneratedConformanceContainer genClass,
362 		Seg seg) {
363 		this.decorateProfileStructure(genClass, seg);
364 	}
365 
366 	public void decorateSetValue(GeneratedMethod genMethod, long maxLength) {
367 		genMethod.addToDescription(
368 			"This method validates the <code>String</code> value passed in to be no greater then the");
369 		genMethod.addToDescription(
370 			"maximum allowable length for the extending class.  If the <code>String</code> value is valid, this");
371 		genMethod.addToDescription(
372 			"method will set the underlying HAPI class's value. If the data passed in is invalid for the given");
373 		genMethod.addToDescription(
374 			"data type, a ConformanceException is thrown.");
375 		genMethod.addToDescription(
376 			"@throws ConfDataException if the data is invalid for the given datatype");
377 		//TODO: this probably isn't the right exception type
378 		genMethod.addToDescription("@param value The value to be set.");
379 		if (maxLength > 0)
380 			genMethod.addToDescription(
381 				"Note: The value has a maximum length of " + maxLength);
382 	}
383 
384 	/** Contains the License agreement for the Generated Classes
385 	 * @return Generated Class Lincense agreement
386 	 */
387 	public String getGeneratedClassHeader() {
388 		return (
389 			"/**\n"
390 				+ "The following code was automatically genearated by the Conformance Class Generation System\n"
391 				+ "Contributor(s):The Conformance Class Generation System was developed by\n"
392 				+ "                --------------.:JH6 Solutions:.--------------\n"
393 				+ "                James Agnew - jait214@yahoo.ca\n"
394 				+ "                Paul Brohman - pbrohman@rogers.com\n"
395 				+ "                Mitch Delachevrotiere - hapimgd@hotmail.com\n"
396 				+ "                Shawn Dyck - sdyck613@yahoo.ca\n"
397 				+ "                Cory Metcalf - cory_metcalf@hotmail.com\n"
398 				+ "\n"
399 				+ "*/");
400 	}
401 
402 }