From afc286a66ab7f9f094b3a6177167e324618c0a29 Mon Sep 17 00:00:00 2001 From: Artem Bilan Date: Wed, 6 Jan 2016 16:14:49 -0500 Subject: [PATCH] INT-3927: Docs for `IntegrationComponentScan` JIRA: https://jira.spring.io/browse/INT-3927 PR Comments --- .../annotation/IntegrationComponentScan.java | 28 +++++++++++-------- .../annotation/MessagingGateway.java | 18 +++++++++--- src/reference/asciidoc/configuration.adoc | 20 +++++++++++++ src/reference/asciidoc/gateway.adoc | 7 +++-- 4 files changed, 56 insertions(+), 17 deletions(-) diff --git a/spring-integration-core/src/main/java/org/springframework/integration/annotation/IntegrationComponentScan.java b/spring-integration-core/src/main/java/org/springframework/integration/annotation/IntegrationComponentScan.java index bfbd9c49b6..88de2f957b 100644 --- a/spring-integration-core/src/main/java/org/springframework/integration/annotation/IntegrationComponentScan.java +++ b/spring-integration-core/src/main/java/org/springframework/integration/annotation/IntegrationComponentScan.java @@ -1,5 +1,5 @@ /* - * Copyright 2014 the original author or authors. + * Copyright 2014-2016 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -22,15 +22,22 @@ import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +import org.springframework.context.annotation.ComponentScan; import org.springframework.context.annotation.Import; +import org.springframework.core.annotation.AliasFor; import org.springframework.integration.config.IntegrationComponentScanRegistrar; /** - * Configures component scanning directives for use with @{@link org.springframework.context.annotation.Configuration} classes. - * Scan Spring Integration specific components. + * Configures component scanning directives for use with + * {@link org.springframework.context.annotation.Configuration} classes. + *

+ * Scans for {@link MessagingGateway} on interfaces to create {@code GatewayProxyFactoryBean}s. * * @author Artem Bilan * @since 4.0 + * + * @see ComponentScan + * @see MessagingGateway */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.TYPE) @@ -41,28 +48,27 @@ public @interface IntegrationComponentScan { /** * Alias for the {@link #basePackages()} attribute. * Allows for more concise annotation declarations e.g.: - * {@code @ComponentScan("org.my.pkg")} instead of - * {@code @ComponentScan(basePackages="org.my.pkg")}. - * + * {@code @IntegrationComponentScan("org.my.pkg")} instead of + * {@code @IntegrationComponentScan(basePackages="org.my.pkg")}. * @return the array of 'basePackages'. */ + @AliasFor("basePackages") String[] value() default {}; /** * Base packages to scan for annotated components. - *

{@link #value()} is an alias for (and mutually exclusive with) this attribute. - *

Use {@link #basePackageClasses()} for a type-safe alternative to String-based package names. - * + * The {@link #value()} is an alias for (and mutually exclusive with) this attribute. + * Use {@link #basePackageClasses()} for a type-safe alternative to String-based package names. * @return the array of 'basePackages'. */ + @AliasFor("value") String[] basePackages() default {}; /** * Type-safe alternative to {@link #basePackages()} for specifying the packages * to scan for annotated components. The package of each class specified will be scanned. - *

Consider creating a special no-op marker class or interface in each package + * Consider creating a special no-op marker class or interface in each package * that serves no purpose other than being referenced by this attribute. - * * @return the array of 'basePackageClasses'. */ Class[] basePackageClasses() default {}; diff --git a/spring-integration-core/src/main/java/org/springframework/integration/annotation/MessagingGateway.java b/spring-integration-core/src/main/java/org/springframework/integration/annotation/MessagingGateway.java index 6ed5924c9c..20c7e08cf4 100644 --- a/spring-integration-core/src/main/java/org/springframework/integration/annotation/MessagingGateway.java +++ b/spring-integration-core/src/main/java/org/springframework/integration/annotation/MessagingGateway.java @@ -1,5 +1,5 @@ /* - * Copyright 2014-2015 the original author or authors. + * Copyright 2014-2016 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -27,9 +27,17 @@ import java.lang.annotation.Target; * ({@code }) as an abstraction over the messaging API. The target * application’s business logic may be completely unaware of the Spring Integration * API, with the code interacting only via the interface. + *

+ * Important: The {@link IntegrationComponentScan} annotation is required along with + * {@link org.springframework.context.annotation.Configuration} + * to scan interfaces annotated with {@link MessagingGateway}, because the + * standard {@link org.springframework.context.annotation.ComponentScan} + * ignores interfaces. * * @author Artem Bilan * @since 4.0 + * + * @see IntegrationComponentScan */ @Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME) @@ -44,14 +52,16 @@ public @interface MessagingGateway { String name() default ""; /** - * Identifies default channel the messages will be sent to upon invocation of methods of the gateway proxy. + * Identifies the default channel to which messages will be sent upon invocation + * of methods of the gateway proxy. * @return the suggested channel name, if any */ String defaultRequestChannel() default ""; /** - * Identifies default channel the gateway proxy will subscribe to to receive reply {@code Message}s, which will then be - * converted to the return type of the method signature. + * Identifies the default channel the gateway proxy will subscribe to, to receive reply + * {@code Message}s, the payloads of + * which will be converted to the return type of the method signature. * @return the suggested channel name, if any */ String defaultReplyChannel() default ""; diff --git a/src/reference/asciidoc/configuration.adoc b/src/reference/asciidoc/configuration.adoc index 65dbf6e4cf..cc8d9c8cd2 100644 --- a/src/reference/asciidoc/configuration.adoc +++ b/src/reference/asciidoc/configuration.adoc @@ -256,6 +256,8 @@ Annotations available in Spring Integration include: * @InboundChannelAdapter * @BridgeFrom * @BridgeTo +* @MessagingGateway +* @IntegrationComponentScan The behavior of each is described in its own chapter or section within this reference. @@ -438,6 +440,24 @@ public String foo() { The first example requires that the default poller has been declared elsewhere in the application context. +*@MessagingGateway* + +See <>. + +*@IntegrationComponentScan* + +The standard Spring Framework `@ComponentScan` annotation doesn't scan interfaces for stereotype `@Component` +annotations. +To overcome this limitation and allow the configuration of `@MessagingGateway` (see <>), +the `@IntegrationComponentScan` mechanism has been introduced. +This annotation must be placed along with a `@Configuration` annotation, and customized for the scanning options, +such as `basePackages` and `basePackageClasses`. +In this case all discovered interfaces annotated with `@MessagingGateway` will be parsed and registered +as a `GatewayProxyFactoryBean` s. +All other class-based components are parsed by the standard `@ComponentScan`. +In future, more scanning logic may be added to the `@IntegrationComponentScan`. + + [[meta-annotations]] ==== Messaging Meta-Annotations diff --git a/src/reference/asciidoc/gateway.adoc b/src/reference/asciidoc/gateway.adoc index 3c52e6128b..f6db8c52a3 100644 --- a/src/reference/asciidoc/gateway.adoc +++ b/src/reference/asciidoc/gateway.adoc @@ -277,8 +277,11 @@ public interface TestGateway { } ---- -As with the XML version, Spring Integration creates the `proxy` implementation with its messaging infrastructure, when discovering these annotations during a component scan. -To perform this scan and register the `BeanDefinition` in the application context, add the `@IntegrationComponentScan` annotation to a `@Configuration` class - see also <>. +IMPORTANT: As with the XML version, Spring Integration creates the `proxy` implementation with its messaging infrastructure, when discovering these annotations during a component scan. +To perform this scan and register the `BeanDefinition` in the application context, add the `@IntegrationComponentScan` annotation to a `@Configuration` class. +The standard `@ComponentScan` infrastructure doesn't deal with interfaces, therefore the custom `@IntegrationComponentScan` logic has been introduced +to determine `@MessagingGateway` annotation on the interfaces and register `GatewayProxyFactoryBean` s for them. +See also <> [[gateway-calling-no-argument-methods]] ==== Invoking No-Argument Methods