diff --git a/processor/src/main/java/org/mapstruct/ap/MappingProcessor.java b/processor/src/main/java/org/mapstruct/ap/MappingProcessor.java index 32cb30b58..384e3e614 100644 --- a/processor/src/main/java/org/mapstruct/ap/MappingProcessor.java +++ b/processor/src/main/java/org/mapstruct/ap/MappingProcessor.java @@ -53,22 +53,33 @@ import org.mapstruct.ap.processor.ModelElementProcessor; import org.mapstruct.ap.processor.ModelElementProcessor.ProcessorContext; /** - * A {@link Processor} which generates the implementations for mapper interfaces - * (interfaces annotated with {@code @Mapper}. - *

+ * A JSR 269 annotation {@link Processor} which generates the implementations for mapper interfaces (interfaces + * annotated with {@code @Mapper}. + *

* Implementation notes: - *

- * The generation happens by incrementally building up a model representation of - * each mapper to be generated (a {@link Mapper} object), which is then written - * into the resulting Java source file using the FreeMarker template engine. - *

- * The model instantiation and processing happens in several phases/passes by applying - * a sequence of {@link ModelElementProcessor}s. - *

+ *

+ * The generation happens by incrementally building up a model representation of each mapper to be generated (a + * {@link Mapper} object), which is then written into the resulting Java source file. + *

+ * The model instantiation and processing happens in several phases/passes by applying a sequence of + * {@link ModelElementProcessor}s. The processors to apply are retrieved using the Java service loader mechanism and are + * processed in order of their priority. The general processing flow is this: + *

+ *

* For reading annotation attributes, prisms as generated with help of the Hickory tool are used. These - * prisms allow a comfortable access to annotations and their attributes without - * depending on their class objects. + * href="https://java.net/projects/hickory">Hickory tool are used. These prisms allow a comfortable access to + * annotations and their attributes without depending on their class objects. + *

+ * The creation of Java source files is done using the FreeMarker template engine. + * Each node of the mapper model has a corresponding FreeMarker template file which provides the Java representation of + * that element and can include sub-elements via a custom FreeMarker directive. That way writing out a root node of the + * model ({@code Mapper}) will recursively include all contained sub-elements (such as its methods, their property + * mappings etc.). * * @author Gunnar Morling */ diff --git a/processor/src/main/java/org/mapstruct/ap/conversion/package-info.java b/processor/src/main/java/org/mapstruct/ap/conversion/package-info.java new file mode 100644 index 000000000..c9be2cad8 --- /dev/null +++ b/processor/src/main/java/org/mapstruct/ap/conversion/package-info.java @@ -0,0 +1,26 @@ +/** + * Copyright 2012-2013 Gunnar Morling (http://www.gunnarmorling.de/) + * and/or other contributors as indicated by the @authors tag. See the + * copyright.txt file in the distribution for a full listing of all + * contributors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +/** + *

+ * Provides built-in conversions between primitive and wrapper types, strings, dates etc. Conversions are effectively + * short String snippets such as {@code (int)} or {@code .toString()} which are added inline to the generated mapping + * code. + *

+ */ +package org.mapstruct.ap.conversion; diff --git a/processor/src/main/java/org/mapstruct/ap/model/Type.java b/processor/src/main/java/org/mapstruct/ap/model/Type.java index 6f9d6fc22..6749eab92 100644 --- a/processor/src/main/java/org/mapstruct/ap/model/Type.java +++ b/processor/src/main/java/org/mapstruct/ap/model/Type.java @@ -127,6 +127,14 @@ public class Type extends AbstractModelElement implements Comparable { return isEnumType; } + /** + * Returns the implementation type to be instantiated in case this type is an interface iterable, collection or map + * type. The type will have the correct type arguments, so if this type e.g. represents {@code Set}, the + * implementation type is {@code HashSet}. + * + * @return The implementation type to be instantiated in case this type is an interface iterable, collection or map + * type, {@code null} otherwise. + */ public Type getImplementationType() { return implementationType; } diff --git a/processor/src/main/java/org/mapstruct/ap/model/package-info.java b/processor/src/main/java/org/mapstruct/ap/model/package-info.java new file mode 100644 index 000000000..1c94dbb90 --- /dev/null +++ b/processor/src/main/java/org/mapstruct/ap/model/package-info.java @@ -0,0 +1,25 @@ +/** + * Copyright 2012-2013 Gunnar Morling (http://www.gunnarmorling.de/) + * and/or other contributors as indicated by the @authors tag. See the + * copyright.txt file in the distribution for a full listing of all + * contributors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +/** + *

+ * Meta-model of mapper types, their methods, mappings between properties etc. Model elements can serialize themselves + * using FreeMarker templates. + *

+ */ +package org.mapstruct.ap.model; diff --git a/processor/src/main/java/org/mapstruct/ap/model/source/package-info.java b/processor/src/main/java/org/mapstruct/ap/model/source/package-info.java new file mode 100644 index 000000000..33401a49c --- /dev/null +++ b/processor/src/main/java/org/mapstruct/ap/model/source/package-info.java @@ -0,0 +1,25 @@ +/** + * Copyright 2012-2013 Gunnar Morling (http://www.gunnarmorling.de/) + * and/or other contributors as indicated by the @authors tag. See the + * copyright.txt file in the distribution for a full listing of all + * contributors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +/** + *

+ * Intermediary representation of mapping methods as retrieved from via the annotation processing API. The intermediary + * representation is then processed into the mapper model representation. + *

+ */ +package org.mapstruct.ap.model.source; diff --git a/processor/src/main/java/org/mapstruct/ap/package-info.java b/processor/src/main/java/org/mapstruct/ap/package-info.java index 5110b2a3a..6f526414d 100644 --- a/processor/src/main/java/org/mapstruct/ap/package-info.java +++ b/processor/src/main/java/org/mapstruct/ap/package-info.java @@ -19,7 +19,8 @@ /** *

* This package and it sub-packages contain the implementation of the MapStruct annotation processor. Application code - * using MapStruct should never work with these types directly. + * using MapStruct should never work with these types directly. Refer to the documentation of + * {@link org.mapstruct.ap.MappingProcessor} to learn more about the internal architecture of the processor. *

*/ package org.mapstruct.ap; diff --git a/processor/src/main/java/org/mapstruct/ap/processor/package-info.java b/processor/src/main/java/org/mapstruct/ap/processor/package-info.java new file mode 100644 index 000000000..fdd04357c --- /dev/null +++ b/processor/src/main/java/org/mapstruct/ap/processor/package-info.java @@ -0,0 +1,25 @@ +/** + * Copyright 2012-2013 Gunnar Morling (http://www.gunnarmorling.de/) + * and/or other contributors as indicated by the @authors tag. See the + * copyright.txt file in the distribution for a full listing of all + * contributors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +/** + *

+ * Contains model processors which perform tasks such as retrieving mapping methods, creating a model representation + * and writing the model into Java source files. Processors are invoked in order as per their priority value. + *

+ */ +package org.mapstruct.ap.processor; diff --git a/processor/src/main/java/org/mapstruct/ap/util/TypeFactory.java b/processor/src/main/java/org/mapstruct/ap/util/TypeFactory.java index 36f0e852a..e7560604c 100644 --- a/processor/src/main/java/org/mapstruct/ap/util/TypeFactory.java +++ b/processor/src/main/java/org/mapstruct/ap/util/TypeFactory.java @@ -133,7 +133,7 @@ public class TypeFactory { } DeclaredType declaredType = (DeclaredType) mirror; - ArrayList typeParameters = new ArrayList( declaredType.getTypeArguments().size() ); + List typeParameters = new ArrayList( declaredType.getTypeArguments().size() ); for ( TypeMirror typeParameter : declaredType.getTypeArguments() ) { typeParameters.add( getType( typeParameter ) ); @@ -151,7 +151,7 @@ public class TypeFactory { primitiveType == double.class ? typeUtils.getPrimitiveType( TypeKind.DOUBLE ) : primitiveType == boolean.class ? typeUtils.getPrimitiveType( TypeKind.BOOLEAN ) : primitiveType == char.class ? typeUtils.getPrimitiveType( TypeKind.CHAR ) : - typeUtils.getPrimitiveType( TypeKind.BYTE ); + typeUtils.getPrimitiveType( TypeKind.VOID ); } private Type getImplementationType(TypeMirror mirror) { diff --git a/processor/src/main/java/org/mapstruct/ap/util/package-info.java b/processor/src/main/java/org/mapstruct/ap/util/package-info.java new file mode 100644 index 000000000..c14cedf0e --- /dev/null +++ b/processor/src/main/java/org/mapstruct/ap/util/package-info.java @@ -0,0 +1,24 @@ +/** + * Copyright 2012-2013 Gunnar Morling (http://www.gunnarmorling.de/) + * and/or other contributors as indicated by the @authors tag. See the + * copyright.txt file in the distribution for a full listing of all + * contributors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +/** + *

+ * Several helper types dealing with collection types, option management etc. + *

+ */ +package org.mapstruct.ap.util; diff --git a/processor/src/main/java/org/mapstruct/ap/writer/package-info.java b/processor/src/main/java/org/mapstruct/ap/writer/package-info.java new file mode 100644 index 000000000..a0f150291 --- /dev/null +++ b/processor/src/main/java/org/mapstruct/ap/writer/package-info.java @@ -0,0 +1,24 @@ +/** + * Copyright 2012-2013 Gunnar Morling (http://www.gunnarmorling.de/) + * and/or other contributors as indicated by the @authors tag. See the + * copyright.txt file in the distribution for a full listing of all + * contributors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +/** + *

+ * Infrastructure for dealing with the FreeMarker template engine. + *

+ */ +package org.mapstruct.ap.writer;