From 40ed18af0b00978e3c978ab7fd34cce557b56a24 Mon Sep 17 00:00:00 2001 From: Gunnar Morling Date: Wed, 26 Feb 2014 22:05:17 +0100 Subject: [PATCH] #135 Adding some JavaDocs; Removing unused method --- .../ap/model/source/builtin/package-info.java | 27 +++++++++++++ .../source/selector/InheritanceSelector.java | 6 +-- .../model/source/selector/MethodSelector.java | 18 ++++----- .../source/selector/MethodSelectors.java | 32 +++++++-------- ...InitialSelector.java => TypeSelector.java} | 20 ++++------ .../selector/XmlElementDeclSelector.java | 40 +++++++++---------- .../model/source/selector/package-info.java | 25 ++++++++++++ .../ap/processor/MapperCreationProcessor.java | 22 ++-------- .../JaxbFactoryMethodSelectionTest.java | 13 ++++-- .../ap/test/jaxb/selection/OrderDto.java | 2 - ...urceTargetMapper.java => OrderMapper.java} | 4 +- .../selection/OrderShippingDetailsDto.java | 2 - 12 files changed, 120 insertions(+), 91 deletions(-) create mode 100644 processor/src/main/java/org/mapstruct/ap/model/source/builtin/package-info.java rename processor/src/main/java/org/mapstruct/ap/model/source/selector/{InitialSelector.java => TypeSelector.java} (72%) create mode 100644 processor/src/main/java/org/mapstruct/ap/model/source/selector/package-info.java rename processor/src/test/java/org/mapstruct/ap/test/jaxb/selection/{SourceTargetMapper.java => OrderMapper.java} (92%) diff --git a/processor/src/main/java/org/mapstruct/ap/model/source/builtin/package-info.java b/processor/src/main/java/org/mapstruct/ap/model/source/builtin/package-info.java new file mode 100644 index 000000000..6ea591924 --- /dev/null +++ b/processor/src/main/java/org/mapstruct/ap/model/source/builtin/package-info.java @@ -0,0 +1,27 @@ +/** + * Copyright 2012-2014 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 "built-in methods" which may be added as private methods to a generated mapper. Built-in methods are an + * alternative to primitive conversions in cases where those don't suffice, e.g. if several lines of code are required + * for a conversion or an exception needs to be handled. Each built-in method has a corresponding template which + * contains the source code of the method. + *

+ */ +package org.mapstruct.ap.model.source.builtin; diff --git a/processor/src/main/java/org/mapstruct/ap/model/source/selector/InheritanceSelector.java b/processor/src/main/java/org/mapstruct/ap/model/source/selector/InheritanceSelector.java index da954e460..7c941f3a5 100644 --- a/processor/src/main/java/org/mapstruct/ap/model/source/selector/InheritanceSelector.java +++ b/processor/src/main/java/org/mapstruct/ap/model/source/selector/InheritanceSelector.java @@ -19,6 +19,7 @@ package org.mapstruct.ap.model.source.selector; import java.util.ArrayList; +import java.util.Collection; import java.util.List; import org.mapstruct.ap.model.common.Parameter; @@ -33,13 +34,10 @@ import org.mapstruct.ap.model.source.SourceMethod; */ public class InheritanceSelector implements MethodSelector { - /** - * {@inheritDoc} {@link MethodSelector} - */ @Override public List getMatchingMethods( SourceMethod mappingMethod, - Iterable methods, + Collection methods, Type parameterType, Type returnType, String targetPropertyName diff --git a/processor/src/main/java/org/mapstruct/ap/model/source/selector/MethodSelector.java b/processor/src/main/java/org/mapstruct/ap/model/source/selector/MethodSelector.java index e4d067117..ea502f224 100644 --- a/processor/src/main/java/org/mapstruct/ap/model/source/selector/MethodSelector.java +++ b/processor/src/main/java/org/mapstruct/ap/model/source/selector/MethodSelector.java @@ -18,6 +18,7 @@ */ package org.mapstruct.ap.model.source.selector; +import java.util.Collection; import java.util.List; import org.mapstruct.ap.model.common.Type; @@ -25,27 +26,26 @@ import org.mapstruct.ap.model.source.Method; import org.mapstruct.ap.model.source.SourceMethod; /** + * Implementations select those methods from a given input set which match the given source and target type of a mapping + * and optionally other given criteria. An error will be raised if either no or more than one matching method are left + * over after applying all selectors. + * * @author Sjaak Derksen */ public interface MethodSelector { /** - * Selects a method + * Selects those methods which match the given types and other criteria * * @param either SourceMethod or BuiltInMethod * @param mappingMethod mapping method, defined in Mapper for which this selection is carried out - * @param methods set from available methods + * @param methods set of available methods * @param parameterType parameter type that should be matched * @param returnType return type that should be matched * @param targetPropertyName some information can be derived from the target property * * @return list of methods that passes the matching process */ - List getMatchingMethods( - SourceMethod mappingMethod, - Iterable methods, - Type parameterType, - Type returnType, - String targetPropertyName - ); + List getMatchingMethods(SourceMethod mappingMethod, Collection methods, Type parameterType, + Type returnType, String targetPropertyName); } diff --git a/processor/src/main/java/org/mapstruct/ap/model/source/selector/MethodSelectors.java b/processor/src/main/java/org/mapstruct/ap/model/source/selector/MethodSelectors.java index 918823a98..40bb33197 100644 --- a/processor/src/main/java/org/mapstruct/ap/model/source/selector/MethodSelectors.java +++ b/processor/src/main/java/org/mapstruct/ap/model/source/selector/MethodSelectors.java @@ -19,6 +19,8 @@ package org.mapstruct.ap.model.source.selector; import java.util.ArrayList; +import java.util.Arrays; +import java.util.Collection; import java.util.List; import javax.lang.model.util.Types; @@ -27,32 +29,29 @@ import org.mapstruct.ap.model.source.Method; import org.mapstruct.ap.model.source.SourceMethod; /** + * Applies all known {@link MethodSelector}s in order. + * * @author Sjaak Derksen */ public class MethodSelectors implements MethodSelector { - private final List selectors = new ArrayList(); + private final List selectors; public MethodSelectors(Types typeUtils) { - - selectors.add( new InitialSelector() ); - selectors.add( new InheritanceSelector() ); - selectors.add( new XmlElementDeclSelector( typeUtils ) ); + selectors = + Arrays.asList( + new TypeSelector(), + new InheritanceSelector(), + new XmlElementDeclSelector( typeUtils ) + ); } @Override - public List getMatchingMethods( - SourceMethod mappingMethod, - Iterable methods, - Type parameterType, - Type returnType, - String targetPropertyName - ) { + public List getMatchingMethods(SourceMethod mappingMethod, Collection methods, + Type parameterType, Type returnType, + String targetPropertyName) { - List candidates = new ArrayList(); - for ( T method : methods ) { - candidates.add( method ); - } + List candidates = new ArrayList( methods ); for ( MethodSelector selector : selectors ) { candidates = selector.getMatchingMethods( @@ -65,5 +64,4 @@ public class MethodSelectors implements MethodSelector { } return candidates; } - } diff --git a/processor/src/main/java/org/mapstruct/ap/model/source/selector/InitialSelector.java b/processor/src/main/java/org/mapstruct/ap/model/source/selector/TypeSelector.java similarity index 72% rename from processor/src/main/java/org/mapstruct/ap/model/source/selector/InitialSelector.java rename to processor/src/main/java/org/mapstruct/ap/model/source/selector/TypeSelector.java index c6666e7c5..24a22e3c8 100644 --- a/processor/src/main/java/org/mapstruct/ap/model/source/selector/InitialSelector.java +++ b/processor/src/main/java/org/mapstruct/ap/model/source/selector/TypeSelector.java @@ -19,30 +19,26 @@ package org.mapstruct.ap.model.source.selector; import java.util.ArrayList; +import java.util.Collection; import java.util.List; import org.mapstruct.ap.model.common.Type; import org.mapstruct.ap.model.source.Method; +import org.mapstruct.ap.model.source.MethodMatcher; import org.mapstruct.ap.model.source.SourceMethod; /** - * This class provides the initial set of methods {@link MethodMatcher} + * Selects those methods from the given input set which match the given source and target types (via + * {@link MethodMatcher}). * * @author Sjaak Derksen */ -public class InitialSelector implements MethodSelector { +public class TypeSelector implements MethodSelector { - /** - * {@inheritDoc} {@link MethodSelector} - */ @Override - public List getMatchingMethods( - SourceMethod mappingMethod, - Iterable methods, - Type parameterType, - Type returnType, - String targetPropertyName - ) { + public List getMatchingMethods(SourceMethod mappingMethod, Collection methods, + Type parameterType, Type returnType, + String targetPropertyName) { List result = new ArrayList(); for ( T method : methods ) { diff --git a/processor/src/main/java/org/mapstruct/ap/model/source/selector/XmlElementDeclSelector.java b/processor/src/main/java/org/mapstruct/ap/model/source/selector/XmlElementDeclSelector.java index 0031bea4b..c1a2c2fb2 100644 --- a/processor/src/main/java/org/mapstruct/ap/model/source/selector/XmlElementDeclSelector.java +++ b/processor/src/main/java/org/mapstruct/ap/model/source/selector/XmlElementDeclSelector.java @@ -19,9 +19,12 @@ package org.mapstruct.ap.model.source.selector; import java.util.ArrayList; +import java.util.Collection; import java.util.List; + import javax.lang.model.type.TypeMirror; import javax.lang.model.util.Types; +import javax.xml.bind.annotation.XmlElementDecl; import org.mapstruct.ap.model.common.Type; import org.mapstruct.ap.model.source.Method; @@ -29,13 +32,15 @@ import org.mapstruct.ap.model.source.SourceMethod; import org.mapstruct.ap.prism.XmlElementDeclPrism; /** - * This class matches XmlElmentDecl annotation. Matching happens in the following order. - * 1) Name and Scope matches - * 2) Scope matches - * 3) Name matches - * 4) No match at all. - * - * If there are Name and Scope matches, only those will be returned, otherwise the next in line (scope matches), etc. + * Selects those methods with matching {@code name} and {@code scope} attributes of the {@link XmlElementDecl} + * annotation, if that is present. Matching happens in the following order: + *
    + *
  1. Name and Scope matches
    2. + *
  2. Scope matches
    3. + *
  3. Name matches
    4. + *
+ * If there are name and scope matches, only those will be returned, otherwise the next in line (scope matches), etc. If + * the given method is not annotated with {@code} XmlElementDecl} it will be considered as matching. * * @author Sjaak Derksen */ @@ -47,17 +52,10 @@ public class XmlElementDeclSelector implements MethodSelector { this.typeUtils = typeUtils; } - /** - * {@inheritDoc} {@link MethodSelector} - */ @Override - public List getMatchingMethods( - SourceMethod mappingMethod, - Iterable methods, - Type parameterType, - Type returnType, - String targetPropertyName - ) { + public List getMatchingMethods(SourceMethod mappingMethod, Collection methods, + Type parameterType, Type returnType, + String targetPropertyName) { List noXmlDeclMatch = new ArrayList(); List nameMatch = new ArrayList(); @@ -66,9 +64,9 @@ public class XmlElementDeclSelector implements MethodSelector { for ( T candidate : methods ) { if ( candidate instanceof SourceMethod ) { - SourceMethod candiateMethod = (SourceMethod) candidate; + SourceMethod candidateMethod = (SourceMethod) candidate; XmlElementDeclPrism xmlElememtDecl - = XmlElementDeclPrism.getInstanceOn( candiateMethod.getExecutable() ); + = XmlElementDeclPrism.getInstanceOn( candidateMethod.getExecutable() ); if ( xmlElememtDecl != null ) { String name = xmlElememtDecl.name(); TypeMirror scope = xmlElememtDecl.scope(); @@ -97,12 +95,12 @@ public class XmlElementDeclSelector implements MethodSelector { } } else { - // cannot a verdict on xmldeclannotation, so add + // cannot make a verdict on xmldeclannotation, so add noXmlDeclMatch.add( candidate ); } } else { - // cannot a verdict on xmldeclannotation, so add + // cannot make a verdict on xmldeclannotation, so add noXmlDeclMatch.add( candidate ); } } diff --git a/processor/src/main/java/org/mapstruct/ap/model/source/selector/package-info.java b/processor/src/main/java/org/mapstruct/ap/model/source/selector/package-info.java new file mode 100644 index 000000000..3b3cd4c0c --- /dev/null +++ b/processor/src/main/java/org/mapstruct/ap/model/source/selector/package-info.java @@ -0,0 +1,25 @@ +/** + * Copyright 2012-2014 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 strategies for selecting a matching mapping or factory method when mapping from one attribute to another + * or instantiating the target type of a mapping method, respectively. + *

+ */ +package org.mapstruct.ap.model.source.selector; diff --git a/processor/src/main/java/org/mapstruct/ap/processor/MapperCreationProcessor.java b/processor/src/main/java/org/mapstruct/ap/processor/MapperCreationProcessor.java index 577856ad2..af39120b0 100644 --- a/processor/src/main/java/org/mapstruct/ap/processor/MapperCreationProcessor.java +++ b/processor/src/main/java/org/mapstruct/ap/processor/MapperCreationProcessor.java @@ -20,12 +20,14 @@ package org.mapstruct.ap.processor; import java.text.MessageFormat; import java.util.ArrayList; +import java.util.Collection; import java.util.HashMap; import java.util.HashSet; import java.util.LinkedList; import java.util.List; import java.util.Map; import java.util.Set; + import javax.annotation.processing.Messager; import javax.lang.model.element.Element; import javax.lang.model.element.ExecutableElement; @@ -952,7 +954,7 @@ public class MapperCreationProcessor implements ModelElementProcessor T getBestMatch(SourceMethod mappingMethod, String mappedElement, - Iterable methods, + Collection methods, Type parameterType, Type returnType, String targetPropertyName) { @@ -965,7 +967,7 @@ public class MapperCreationProcessor implements ModelElementProcessor 1 ) { messager.printMessage( @@ -987,22 +989,6 @@ public class MapperCreationProcessor implements ModelElementProcessor int addToCandidateListIfMinimal(List candidatesWithBestMathingType, - int bestMatchingTypeDistance, T method, - int currentTypeDistance) { - if ( currentTypeDistance == bestMatchingTypeDistance ) { - candidatesWithBestMathingType.add( method ); - } - else if ( currentTypeDistance < bestMatchingTypeDistance ) { - bestMatchingTypeDistance = currentTypeDistance; - - candidatesWithBestMathingType.clear(); - candidatesWithBestMathingType.add( method ); - } - return bestMatchingTypeDistance; - } - private MethodReference getMappingMethodReference(SourceMethod method, List mapperReferences) { MapperReference mapperReference = null; for ( MapperReference ref : mapperReferences ) { diff --git a/processor/src/test/java/org/mapstruct/ap/test/jaxb/selection/JaxbFactoryMethodSelectionTest.java b/processor/src/test/java/org/mapstruct/ap/test/jaxb/selection/JaxbFactoryMethodSelectionTest.java index b2f9e8d75..08a4f5411 100644 --- a/processor/src/test/java/org/mapstruct/ap/test/jaxb/selection/JaxbFactoryMethodSelectionTest.java +++ b/processor/src/test/java/org/mapstruct/ap/test/jaxb/selection/JaxbFactoryMethodSelectionTest.java @@ -18,6 +18,10 @@ */ package org.mapstruct.ap.test.jaxb.selection; +import static org.fest.assertions.Assertions.assertThat; + +import javax.xml.bind.annotation.XmlElementDecl; + import org.mapstruct.ap.test.jaxb.selection.test1.OrderType; import org.mapstruct.ap.test.jaxb.selection.test2.ObjectFactory; import org.mapstruct.ap.test.jaxb.selection.test2.OrderShippingDetailsType; @@ -26,22 +30,23 @@ import org.mapstruct.ap.testutil.MapperTestBase; import org.mapstruct.ap.testutil.WithClasses; import org.testng.annotations.Test; -import static org.fest.assertions.Assertions.assertThat; - /** + * Test for the selection of JAXB mapping and factory methods based on the "name" and "scope" attributes + * of the {@link XmlElementDecl} annotation. + * * @author Sjaak Derksen */ @IssueKey("135") @WithClasses({ org.mapstruct.ap.test.jaxb.selection.test1.ObjectFactory.class, ObjectFactory.class, OrderDto.class, OrderShippingDetailsDto.class, OrderType.class, OrderShippingDetailsType.class, - SourceTargetMapper.class + OrderMapper.class }) public class JaxbFactoryMethodSelectionTest extends MapperTestBase { @Test public void shouldMatchOnNameAndOrScope() { - OrderType target = SourceTargetMapper.INSTANCE.targetToSource( createSource() ); + OrderType target = OrderMapper.INSTANCE.targetToSource( createSource() ); // qname and value should match for orderNumbers (distinct 1, 2) assertThat( target.getOrderNumber1().getValue() ).isEqualTo( 15L ); diff --git a/processor/src/test/java/org/mapstruct/ap/test/jaxb/selection/OrderDto.java b/processor/src/test/java/org/mapstruct/ap/test/jaxb/selection/OrderDto.java index 460ef7945..d0291366d 100644 --- a/processor/src/test/java/org/mapstruct/ap/test/jaxb/selection/OrderDto.java +++ b/processor/src/test/java/org/mapstruct/ap/test/jaxb/selection/OrderDto.java @@ -50,6 +50,4 @@ public class OrderDto { public void setShippingDetails(OrderShippingDetailsDto shippingDetails) { this.shippingDetails = shippingDetails; } - - } diff --git a/processor/src/test/java/org/mapstruct/ap/test/jaxb/selection/SourceTargetMapper.java b/processor/src/test/java/org/mapstruct/ap/test/jaxb/selection/OrderMapper.java similarity index 92% rename from processor/src/test/java/org/mapstruct/ap/test/jaxb/selection/SourceTargetMapper.java rename to processor/src/test/java/org/mapstruct/ap/test/jaxb/selection/OrderMapper.java index b65c6f28f..be57920ec 100644 --- a/processor/src/test/java/org/mapstruct/ap/test/jaxb/selection/SourceTargetMapper.java +++ b/processor/src/test/java/org/mapstruct/ap/test/jaxb/selection/OrderMapper.java @@ -34,9 +34,9 @@ import org.mapstruct.factory.Mappers; ObjectFactory.class, org.mapstruct.ap.test.jaxb.selection.test2.ObjectFactory.class }) -public abstract class SourceTargetMapper { +public abstract class OrderMapper { - public static final SourceTargetMapper INSTANCE = Mappers.getMapper( SourceTargetMapper.class ); + public static final OrderMapper INSTANCE = Mappers.getMapper( OrderMapper.class ); // target 2 source methods public abstract OrderType targetToSource(OrderDto target); diff --git a/processor/src/test/java/org/mapstruct/ap/test/jaxb/selection/OrderShippingDetailsDto.java b/processor/src/test/java/org/mapstruct/ap/test/jaxb/selection/OrderShippingDetailsDto.java index aaf38be93..ce7921dac 100644 --- a/processor/src/test/java/org/mapstruct/ap/test/jaxb/selection/OrderShippingDetailsDto.java +++ b/processor/src/test/java/org/mapstruct/ap/test/jaxb/selection/OrderShippingDetailsDto.java @@ -41,6 +41,4 @@ public class OrderShippingDetailsDto { public void setOrderShippedTo(String orderShippedTo) { this.orderShippedTo = orderShippedTo; } - - }