From 289dde098e8f14c7ed586e03a0d9f70ccc8b97ac Mon Sep 17 00:00:00 2001 From: Andre F de Miranda Date: Tue, 16 May 2017 00:30:02 +1000 Subject: [PATCH] NIFI-3896 - Makes DeprecationNotice more intuitive. This closes #1799 Update developers guide on how to deprecate a component --- .../documentation/DeprecationNotice.java | 3 ++- nifi-docs/src/main/asciidoc/developer-guide.adoc | 16 ++++++++++++++++ .../html/HtmlDocumentationWriter.java | 2 +- .../example/DeprecatedProcessor.java | 2 +- 4 files changed, 20 insertions(+), 3 deletions(-) diff --git a/nifi-api/src/main/java/org/apache/nifi/annotation/documentation/DeprecationNotice.java b/nifi-api/src/main/java/org/apache/nifi/annotation/documentation/DeprecationNotice.java index a3bbdf4deb..f9d47dda5e 100644 --- a/nifi-api/src/main/java/org/apache/nifi/annotation/documentation/DeprecationNotice.java +++ b/nifi-api/src/main/java/org/apache/nifi/annotation/documentation/DeprecationNotice.java @@ -36,8 +36,9 @@ import java.lang.annotation.Target; @Target({ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) @Inherited + public @interface DeprecationNotice { - Class[] value() default {}; + Class[] alternatives() default {}; String[] classNames() default {}; diff --git a/nifi-docs/src/main/asciidoc/developer-guide.adoc b/nifi-docs/src/main/asciidoc/developer-guide.adoc index 7b2ba35869..d4195a1399 100644 --- a/nifi-docs/src/main/asciidoc/developer-guide.adoc +++ b/nifi-docs/src/main/asciidoc/developer-guide.adoc @@ -2379,6 +2379,22 @@ bundled with an extension that requires it, even if @RequiresInstanceClassLoadin logged to help avoid this bad practice. +[[deprecation]] +== Deprecating a Component +Sometimes it may be desirable to deprecate a component. Whenever this occurs the developer may use the + @DeprecationNotice annotation to indicate that a component has been deprecated, aloowing the developer + to describe a reason for the deprecation and suggest alternative components. An example of how to do this can + be found below: + +[source, java] +---- + @DeprecationNotice(alternatives = {ListenSyslog.class}, classNames = {"org.apache.nifi.processors.standard.ListenRELP"}, reason = "Technologyhas been superseded", ) + public class ListenOldProtocol extends AbstractProcessor { +---- +As you can see, the alternatives can be used to define and array of alternative Components, while classNames can be +used to represent the similar content through an array of strings. + + == How to contribute to Apache NiFi We are always excited to have contributions from the community - especially from new contributors! diff --git a/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-documentation/src/main/java/org/apache/nifi/documentation/html/HtmlDocumentationWriter.java b/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-documentation/src/main/java/org/apache/nifi/documentation/html/HtmlDocumentationWriter.java index e5badc8222..6497e41227 100644 --- a/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-documentation/src/main/java/org/apache/nifi/documentation/html/HtmlDocumentationWriter.java +++ b/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-documentation/src/main/java/org/apache/nifi/documentation/html/HtmlDocumentationWriter.java @@ -249,7 +249,7 @@ public class HtmlDocumentationWriter implements DocumentationWriter { xmlStreamWriter.writeCharacters("Please consider using one the following alternatives: "); - Class[] componentNames = deprecationNotice.value(); + Class[] componentNames = deprecationNotice.alternatives(); String[] classNames = deprecationNotice.classNames(); if (componentNames.length > 0 || classNames.length > 0) { diff --git a/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-documentation/src/test/java/org/apache/nifi/documentation/example/DeprecatedProcessor.java b/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-documentation/src/test/java/org/apache/nifi/documentation/example/DeprecatedProcessor.java index af44195820..0c4ca95be3 100644 --- a/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-documentation/src/test/java/org/apache/nifi/documentation/example/DeprecatedProcessor.java +++ b/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-documentation/src/test/java/org/apache/nifi/documentation/example/DeprecatedProcessor.java @@ -57,7 +57,7 @@ import java.util.Set; @DynamicRelationship(name = "name from dynamic property", description = "all files that match the properties XPath") @Stateful(scopes = {Scope.CLUSTER, Scope.LOCAL}, description = "state management description") @Restricted("processor restriction description") -@DeprecationNotice({FullyDocumentedProcessor.class, FullyDocumentedReportingTask.class}) +@DeprecationNotice(alternatives = {FullyDocumentedProcessor.class, FullyDocumentedReportingTask.class}) public class DeprecatedProcessor extends AbstractProcessor { public static final PropertyDescriptor DIRECTORY = new PropertyDescriptor.Builder().name("Input Directory")