Repository: nifi
Updated Branches:
refs/heads/master 5cf4bf61b -> 289dde098
NIFI-3896 - Makes DeprecationNotice more intuitive. This closes #1799
Update developers guide on how to deprecate a component
Project: http://git-wip-us.apache.org/repos/asf/nifi/repo
Commit: http://git-wip-us.apache.org/repos/asf/nifi/commit/289dde09
Tree: http://git-wip-us.apache.org/repos/asf/nifi/tree/289dde09
Diff: http://git-wip-us.apache.org/repos/asf/nifi/diff/289dde09
Branch: refs/heads/master
Commit: 289dde098e8f14c7ed586e03a0d9f70ccc8b97ac
Parents: 5cf4bf6
Author: Andre F de Miranda <[email protected]>
Authored: Tue May 16 00:30:02 2017 +1000
Committer: Matt Gilman <[email protected]>
Committed: Wed May 17 16:37:11 2017 -0400
----------------------------------------------------------------------
.../annotation/documentation/DeprecationNotice.java | 3 ++-
nifi-docs/src/main/asciidoc/developer-guide.adoc | 16 ++++++++++++++++
.../documentation/html/HtmlDocumentationWriter.java | 2 +-
.../documentation/example/DeprecatedProcessor.java | 2 +-
4 files changed, 20 insertions(+), 3 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/nifi/blob/289dde09/nifi-api/src/main/java/org/apache/nifi/annotation/documentation/DeprecationNotice.java
----------------------------------------------------------------------
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 a3bbdf4..f9d47dd 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<? extends ConfigurableComponent>[] value() default {};
+ Class<? extends ConfigurableComponent>[] alternatives() default {};
String[] classNames() default {};
http://git-wip-us.apache.org/repos/asf/nifi/blob/289dde09/nifi-docs/src/main/asciidoc/developer-guide.adoc
----------------------------------------------------------------------
diff --git a/nifi-docs/src/main/asciidoc/developer-guide.adoc
b/nifi-docs/src/main/asciidoc/developer-guide.adoc
index 7b2ba35..d4195a1 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!
http://git-wip-us.apache.org/repos/asf/nifi/blob/289dde09/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-documentation/src/main/java/org/apache/nifi/documentation/html/HtmlDocumentationWriter.java
----------------------------------------------------------------------
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 e5badc8..6497e41 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<? extends ConfigurableComponent>[] componentNames =
deprecationNotice.value();
+ Class<? extends ConfigurableComponent>[] componentNames =
deprecationNotice.alternatives();
String[] classNames = deprecationNotice.classNames();
if (componentNames.length > 0 || classNames.length > 0) {
http://git-wip-us.apache.org/repos/asf/nifi/blob/289dde09/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-documentation/src/test/java/org/apache/nifi/documentation/example/DeprecatedProcessor.java
----------------------------------------------------------------------
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 af44195..0c4ca95 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")
