third_codes/mapstruct
1
0
Fork 0
mirror of https://github.com/mapstruct/mapstruct.git synced 2025-07-12 00:00:08 +08:00
Code Issues Packages Projects Releases Wiki Activity

#29 Adding package-level JavaDocs, adding some overal architecture documentation to MappingProcessor

Browse Source
This commit is contained in:
Gunnar Morling 2013-08-16 00:57:38 +02:00
parent be3018b614
commit c093e09c82
10 changed files with 186 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
processor/src/main/java/org/mapstruct/ap/MappingProcessor.java
View File

@ -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}.
* </p>
* A JSR 269 annotation {@link Processor} which generates the implementations for mapper interfaces (interfaces
* annotated with {@code @Mapper}.
* <p>
* Implementation notes:
* </p>
* 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.
* </p>
* The model instantiation and processing happens in several phases/passes by applying
* a sequence of {@link ModelElementProcessor}s.
* </p>
* <p>
* 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.
* <p>
* 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:
* <ul>
* <li>retrieve mapping methods</li>
* <li>create the {@code Mapper} model</li>
* <li>perform enrichments and modifications (e.g. add annotations for dependency injection)</li>
* <li>if no error ocurred, write out the model into Java source files</li>
* </ul>
* <p>
* For reading annotation attributes, prisms as generated with help of the <a
* href="https://java.net/projects/hickory">Hickory</a> 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</a> tool are used. These prisms allow a comfortable access to
* annotations and their attributes without depending on their class objects.
* <p>
* The creation of Java source files is done using the <a href="http://freemarker.org/"> FreeMarker</a> 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
*/

26
processor/src/main/java/org/mapstruct/ap/conversion/package-info.java Normal file
View File

@ -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.
*/
/**
* <p>
* 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.
* </p>
*/
package org.mapstruct.ap.conversion;

8
processor/src/main/java/org/mapstruct/ap/model/Type.java
View File

@ -127,6 +127,14 @@ public class Type extends AbstractModelElement implements Comparable<Type> {
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<String>}, the
* implementation type is {@code HashSet<String>}.
*
* @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;
}

25
processor/src/main/java/org/mapstruct/ap/model/package-info.java Normal file
View File

@ -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.
*/
/**
* <p>
* Meta-model of mapper types, their methods, mappings between properties etc. Model elements can serialize themselves
* using FreeMarker templates.
* </p>
*/
package org.mapstruct.ap.model;

25
processor/src/main/java/org/mapstruct/ap/model/source/package-info.java Normal file
View File

@ -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.
*/
/**
* <p>
* Intermediary representation of mapping methods as retrieved from via the annotation processing API. The intermediary
* representation is then processed into the mapper model representation.
* </p>
*/
package org.mapstruct.ap.model.source;

3
processor/src/main/java/org/mapstruct/ap/package-info.java
View File

@ -19,7 +19,8 @@
/**
* <p>
* 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.
* </p>
*/
package org.mapstruct.ap;

25
processor/src/main/java/org/mapstruct/ap/processor/package-info.java Normal file
View File

@ -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.
*/
/**
* <p>
* 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.
* </p>
*/
package org.mapstruct.ap.processor;

4
processor/src/main/java/org/mapstruct/ap/util/TypeFactory.java
View File

@ -133,7 +133,7 @@ public class TypeFactory {
}
DeclaredType declaredType = (DeclaredType) mirror;
ArrayList<Type> typeParameters = new ArrayList<Type>( declaredType.getTypeArguments().size() );
List<Type> typeParameters = new ArrayList<Type>( 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) {

24
processor/src/main/java/org/mapstruct/ap/util/package-info.java Normal file
View File

@ -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.
*/
/**
* <p>
* Several helper types dealing with collection types, option management etc.
* </p>
*/
package org.mapstruct.ap.util;

24
processor/src/main/java/org/mapstruct/ap/writer/package-info.java Normal file
View File

@ -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.
*/
/**
* <p>
* Infrastructure for dealing with the FreeMarker template engine.
* </p>
*/
package org.mapstruct.ap.writer;