Author: fdesbois Date: 2009-11-03 17:20:33 +0100 (Tue, 03 Nov 2009) New Revision: 689 Modified: branches/eugene-2.0/eugene/src/main/java/org/nuiton/eugene/java/JavaBuilder.java branches/eugene-2.0/eugene/src/main/java/org/nuiton/eugene/models/object/xml/ObjectModelBuilder.java Log: Add javadoc for builders Modified: branches/eugene-2.0/eugene/src/main/java/org/nuiton/eugene/java/JavaBuilder.java =================================================================== --- branches/eugene-2.0/eugene/src/main/java/org/nuiton/eugene/java/JavaBuilder.java 2009-11-03 15:26:27 UTC (rev 688) +++ branches/eugene-2.0/eugene/src/main/java/org/nuiton/eugene/java/JavaBuilder.java 2009-11-03 16:20:33 UTC (rev 689) @@ -18,6 +18,10 @@ * @author fdesbois * @version $Revision$ * + * Builder to fill an empty ObjectModel with java specificities (imports, only one inheritance, constructor, ...). + * JavaBuilder uses ImportsManagerExtension to manage imports in the model. + * JavaBuilder is also based on ObjectModelBuilder for the simple filling of the model. + * * Mise a jour: $Date$ * par : $Author$ */ @@ -25,8 +29,14 @@ private static final Log log = LogFactory.getLog(JavaBuilder.class); + /** + * Builder where the filling is based on + */ protected ObjectModelBuilder modelBuilder; + /** + * ObjectModel extension to manage imports : one ImportsManager by classifier + */ protected ImportsManagerExtension managers; @SuppressWarnings("unchecked") @@ -37,11 +47,32 @@ ImportsManagerExtension.OBJECTMODEL_EXTENSION, ImportsManagerExtension.class); } + /** + * Get the model which is built + * @return an ObjectModel + */ public ObjectModel getModel() { return this.modelBuilder.getModel(); } + /** + * Add an import to a classifier. Imports are automatic for lots of JavaBuilder's methods except body + * code of operations. + * <pre> + * You can have some complex imports like : + * - new java.util.List<org.chorem.bonzoms.Role>() + * --> two imports 'java.util.List' and 'org.chorem.bonzoms.Role' + * - java.util.Collection<T extends org.nuiton.topia.TopiaEntity> + * --> two imports 'java.util.Collection' and 'org.nuiton.topia.TopiaEntity' + * </pre> + * @param classifier where the imports will be added. + * @param imports to add + * @see org.nuiton.eugene.GeneratorUtil#getTypesList(java.lang.String) + */ public void addImport(ObjectModelClassifier classifier, String imports) { + if (imports == null) { + return; + } ImportsManager manager = managers.getManager(classifier); for (String oneType : GeneratorUtil.getTypesList(imports)) { manager.addImport(oneType); @@ -51,14 +82,37 @@ } } + /** + * Create a new class in the model. + * @param name + * @param packageName + * @return a new ObjectModelClass + * @see org.nuiton.eugene.models.object.xml.ObjectModelBuilder#createClass(java.lang.String, java.lang.String) + */ public ObjectModelClass createClass(String name, String packageName) { return modelBuilder.createClass(name, packageName); } + /** + * Create a new abstract class in the model. + * @param name + * @param packageName + * @return a new ObjectModelClass + * @see org.nuiton.eugene.models.object.xml.ObjectModelBuilder#createClass(java.lang.String, + * java.lang.String, org.nuiton.eugene.models.object.ObjectModelModifier[]) + */ public ObjectModelClass createAbstractClass(String name, String packageName) { return modelBuilder.createClass(name, packageName, ObjectModelModifier.ABSTRACT); } + /** + * Set the superclass of an other class. Only one superclass can be set to the class. + * IMPORTS superclassQualifiedName. + * @param classifier + * @param superclassQualifiedName + * @see org.nuiton.eugene.models.object.xml.ObjectModelBuilder#addInterface( + * org.nuiton.eugene.models.object.ObjectModelClassifier, java.lang.String) + */ public void setSuperClass(ObjectModelClass classifier, String superclassQualifiedName) { ObjectModelClassImpl impl = (ObjectModelClassImpl) classifier; impl.getSuperclasses().clear(); // suppress all existing superclass: only one can be set for java @@ -66,11 +120,50 @@ this.addImport(classifier, superclassQualifiedName); } + /** + * Add an interface to a classifier (interface, class, enum). + * IMPORTS interfaceQualifiedName. + * @param classifier + * @param interfaceQualifiedName + * @see org.nuiton.eugene.models.object.xml.ObjectModelBuilder#addInterface( + * org.nuiton.eugene.models.object.ObjectModelClassifier, java.lang.String) + */ public void addInterface(ObjectModelClassifier classifier, String interfaceQualifiedName) { modelBuilder.addInterface(classifier, interfaceQualifiedName); this.addImport(classifier, interfaceQualifiedName); } + /** + * Add a new attribute to a classifier. + * IMPORTS type, value. + * @param classifier + * @param name + * @param type + * @param value + * @param modifiers + * @return a new ObjectModelAttribute + * @see org.nuiton.eugene.models.object.xml.ObjectModelBuilder#addAttribute( + * org.nuiton.eugene.models.object.ObjectModelClassifier, java.lang.String, + * java.lang.String, java.lang.String, org.nuiton.eugene.models.object.ObjectModelModifier[]) + */ + public ObjectModelAttribute addAttribute(ObjectModelClassifier classifier, String name, String type, String value, + ObjectModelModifier... modifiers) { + this.addImport(classifier, type); + this.addImport(classifier, value); + return modelBuilder.addAttribute(classifier, name, type, value, modifiers); + } + + /** + * Add a new constant to a classifier. A constant is static and final and have a value. + * IMPORTS type, value. + * @param classifier + * @param name + * @param type + * @param value + * @param visibility modifier allowed : PUBLIC, PRIVATE, PROTECTED, PACKAGE + * @return a new ObjectModelAttribute + * @throws IllegalArgumentException if the modifier is not a visibility + */ public ObjectModelAttribute addConstant(ObjectModelClassifier classifier, String name, String type, String value, ObjectModelModifier visibility) throws IllegalArgumentException { if (!visibility.isVisibility()) { @@ -78,21 +171,30 @@ " for " + classifier.getQualifiedName()); } - return modelBuilder.addAttribute(classifier, name, type, value, visibility, + return addAttribute(classifier, name, type, value, visibility, ObjectModelModifier.STATIC, ObjectModelModifier.FINAL); } + /** + * Add a new attribute to a classifier with no default value. Default visibility is set to PROTECTED. + * IMPORTS type. + * @param classifier + * @param name + * @param type + * @return a new ObjectModelAttribute + */ public ObjectModelAttribute addAttribute(ObjectModelClassifier classifier, String name, String type) { - return modelBuilder.addAttribute(classifier, name, type); + return addAttribute(classifier, name, type, "", ObjectModelModifier.PROTECTED); } - public ObjectModelAttribute addAttribute(ObjectModelClassifier classifier, String name, String type, String value, - ObjectModelModifier... modifiers) { - return modelBuilder.addAttribute(classifier, name, type, value, modifiers); - } - + /** + * Add a new attribute to a classifier from an existing attribute. + * IMPORTS attribute.getType() and attribute.getDefaultValue(). + * @param classifier + * @param attribute + * @return a new ObjectModelAttribute + */ public ObjectModelAttribute addAttribute(ObjectModelClassifier classifier, ObjectModelAttribute attribute) { - this.addImport(classifier, attribute.getType()); Set<ObjectModelModifier> modifiers = new HashSet<ObjectModelModifier>(); @@ -112,10 +214,34 @@ modifiers.add(ObjectModelModifier.PACKAGE); } - return modelBuilder.addAttribute(classifier, attribute.getName(), attribute.getType(), + return addAttribute(classifier, attribute.getName(), attribute.getType(), attribute.getDefaultValue(), modifiers.toArray(new ObjectModelModifier[modifiers.size()])); } + /** + * Add a new operation to a classifier. + * @param classifier + * @param name + * @param type + * @param modifiers + * @return a new ObjectModelOperation + * @see org.nuiton.eugene.models.object.xml.ObjectModelBuilder#addOperation( + * org.nuiton.eugene.models.object.ObjectModelClassifier, java.lang.String, + * java.lang.String, org.nuiton.eugene.models.object.ObjectModelModifier[]) + */ + public ObjectModelOperation addOperation(ObjectModelClassifier classifier, String name, String type, + ObjectModelModifier... modifiers) { + this.addImport(classifier, type); + return modelBuilder.addOperation(classifier, name, type, modifiers); + } + + /** + * Add a constructor to a class. + * @param clazz + * @param visibility + * @return a new ObjectModelOperation + * @throws IllegalArgumentException if the modifier is not a visibility + */ public ObjectModelOperation addConstructor(ObjectModelClass clazz, ObjectModelModifier visibility) throws IllegalArgumentException { if (!visibility.isVisibility()) { @@ -123,26 +249,43 @@ " for " + clazz.getQualifiedName()); } - return modelBuilder.addOperation(clazz, clazz.getName(), null, visibility); + return addOperation(clazz, clazz.getName(), null, visibility); } - public ObjectModelOperation addOperation(ObjectModelClassifier classifier, String name, String type, - ObjectModelModifier... modifiers) { - - return modelBuilder.addOperation(classifier, name, type, modifiers); - } - + /** + * Add a new parameter to an existing operation. + * @param operation + * @param type + * @param name + * @return a new ObjectModelParameter + * @see org.nuiton.eugene.models.object.xml.ObjectModelBuilder#addParameter( + * org.nuiton.eugene.models.object.ObjectModelOperation, java.lang.String, java.lang.String) + */ public ObjectModelParameter addParameter(ObjectModelOperation operation, String type, String name) { - ObjectModelParameter param = modelBuilder.addParameter(operation, type, name); this.addImport((ObjectModelClassifier) operation.getDeclaringElement(), type); - return param; + return modelBuilder.addParameter(operation, type, name); } + /** + * Add an exception to an operation. + * @param operation + * @param exception + * @see org.nuiton.eugene.models.object.xml.ObjectModelBuilder#addException( + * org.nuiton.eugene.models.object.ObjectModelOperation, java.lang.String) + */ public void addException(ObjectModelOperation operation, String exception) { + this.addImport((ObjectModelClassifier) operation.getDeclaringElement(), exception); modelBuilder.addException(operation, exception); - this.addImport((ObjectModelClassifier) operation.getDeclaringElement(), exception); } + /** + * Set the operation body code. + * @param operation + * @param body + * @throws IllegalArgumentException if operation is abstract + * @see org.nuiton.eugene.models.object.xml.ObjectModelBuilder#setOperationBody( + * org.nuiton.eugene.models.object.ObjectModelOperation, java.lang.String) + */ public void setOperationBody(ObjectModelOperation operation, String body) throws IllegalArgumentException { if (operation.isAbstract()) { Modified: branches/eugene-2.0/eugene/src/main/java/org/nuiton/eugene/models/object/xml/ObjectModelBuilder.java =================================================================== --- branches/eugene-2.0/eugene/src/main/java/org/nuiton/eugene/models/object/xml/ObjectModelBuilder.java 2009-11-03 15:26:27 UTC (rev 688) +++ branches/eugene-2.0/eugene/src/main/java/org/nuiton/eugene/models/object/xml/ObjectModelBuilder.java 2009-11-03 16:20:33 UTC (rev 689) @@ -19,6 +19,9 @@ * @author fdesbois * @version $Revision$ * + * Builder to fill an empty ObjectModel. The object model name is important if you want to use the model + * in generators. + * * Mise a jour: $Date$ * par : $Author$ */ @@ -26,15 +29,31 @@ protected ObjectModelImpl model; + /** + * Constructor. Must have a name for the new model created. + * @param name model name + */ public ObjectModelBuilder(String name) { this.model = new ObjectModelImpl(); this.model.setName(name); } + /** + * Get the building model + * @return the ObjectModel which is currently built + */ public ObjectModel getModel() { return this.model; } + /** + * Create a new class in the model. + * Modifiers allowed : ABSTRACT, STATIC. + * @param name class name + * @param packageName class package + * @param modifiers class modifiers + * @return the new ObjectModelClass added to the model + */ public ObjectModelClass createClass(String name, String packageName, ObjectModelModifier... modifiers) { ObjectModelClassImpl result = new ObjectModelClassImpl(); result.setName(name); @@ -49,17 +68,44 @@ return result; } + /** + * Create a new interface in the model. + * @param name interface name + * @param packageName interface package + * @return the new ObjectModelInterface added to the model + */ public ObjectModelInterface createInterface(String name, String packageName) { ObjectModelInterfaceImpl result = new ObjectModelInterfaceImpl(); result.setName(name); result.setPackage(packageName); + model.addInterface(result); return result; } + /** + * Add an attribute to a classifier (interface, class, enum) without default value. + * Default visibility is set to PUBLIC. + * @param classifier where the attribute will be added + * @param name attribute name + * @param type attribute type (full qualified name) + * @return the new ObjectModelAttribute added + */ public ObjectModelAttribute addAttribute(ObjectModelClassifier classifier, String name, String type) { return addAttribute(classifier, name, type, ""); } + /** + * Add an attribute to a classifier (interface, class, enum). + * Modifiers allowed : STATIC, FINAL, PUBLIC, PRIVATE, PROTECTED, PACKAGE. + * The last visibility set will be keeped. + * @param classifier where the attribute will be added + * @param name attribute name + * @param type attribute type (full qualified name) + * @param value default value for the attribute + * @param modifiers attribute modifiers + * @return the new ObjectModelAttribute added + * @see org.nuiton.eugene.models.object.ObjectModelModifier#isVisibility() + */ public ObjectModelAttribute addAttribute(ObjectModelClassifier classifier, String name, String type, String value, ObjectModelModifier... modifiers) { ObjectModelAttributeImpl attribute = new ObjectModelAttributeImpl(); @@ -83,7 +129,17 @@ return attribute; } - public ObjectModelOperation addOperation(ObjectModelClassifier clazz, + /** + * Add an operation to a classifier. + * Modifiers allowed : STATIC, ABSTRACT, PUBLIC, PRIVATE, PROTECTED, PACKAGE. + * The last visibility set will be keeped. + * @param classifier where the operation will be added + * @param name operation name + * @param returnType operation type (full qualified name) + * @param modifiers operation modifiers + * @return the new ObjectModelOperation added + */ + public ObjectModelOperation addOperation(ObjectModelClassifier classifier, String name, String returnType, ObjectModelModifier... modifiers) { ObjectModelOperationImpl result = new ObjectModelOperationImpl(); result.setName(name); @@ -105,15 +161,25 @@ } } - ((ObjectModelClassifierImpl)clazz).addOperation(result); + ((ObjectModelClassifierImpl)classifier).addOperation(result); return result; } + /** + * Set the body code for an Operation. + * @param operation where the code will be added + * @param body code to add to the operation + */ public void setOperationBody(ObjectModelOperation operation, String body) { ObjectModelOperationImpl operationImpl = (ObjectModelOperationImpl) operation; operationImpl.setBodyCode(body); } + /** + * Add an interface to a classifier. The interface may not exist in model. + * @param classifier where the interface will be added + * @param interfaceQualifiedName interface qualified name + */ public void addInterface(ObjectModelClassifier classifier, String interfaceQualifiedName) { ObjectModelClassifierImpl impl = (ObjectModelClassifierImpl) classifier; @@ -123,6 +189,11 @@ impl.addInterface(interfacez); } + /** + * Add a superclass to an other class. The superclass may not exist in model. + * @param clazz where the superclass will be added + * @param superclassQualifiedName superclass qualified name + */ public void addSuperclass(ObjectModelClass clazz, String superclassQualifiedName) { ObjectModelClassImpl impl = (ObjectModelClassImpl) clazz; @@ -132,6 +203,13 @@ impl.addSuperclass(superclass); } + /** + * Add a parameter to an operation. + * @param operation where the parameter will be added + * @param type paremeter type (full qualified name) + * @param name parameter name + * @return the new ObjectModelParameter added + */ public ObjectModelParameter addParameter(ObjectModelOperation operation, String type, String name) { ObjectModelOperationImpl impl = (ObjectModelOperationImpl) operation; ObjectModelParameterImpl param = new ObjectModelParameterImpl(); @@ -141,6 +219,11 @@ return param; } + /** + * Add an exception to an operation. + * @param operation where the exception will be added + * @param exception name of the exception (full qualified name) + */ public void addException(ObjectModelOperation operation, String exception) { ObjectModelOperationImpl impl = (ObjectModelOperationImpl) operation; ObjectModelParameterImpl param = new ObjectModelParameterImpl(); @@ -148,6 +231,11 @@ impl.addExceptionParameter(param); } + /** + * Set the documentation of an element in the model. + * @param element where the documentation will be setted + * @param documentation String documentation for the element + */ public void setDocumentation(ObjectModelElement element, String documentation) { ObjectModelElementImpl impl = (ObjectModelElementImpl)element; impl.setDocumentation(documentation);