NIFI-309 documenting @SeeAlso, @ReadsAttributes, @WritesAttributes
Project: http://git-wip-us.apache.org/repos/asf/incubator-nifi/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-nifi/commit/90fd0eda Tree: http://git-wip-us.apache.org/repos/asf/incubator-nifi/tree/90fd0eda Diff: http://git-wip-us.apache.org/repos/asf/incubator-nifi/diff/90fd0eda Branch: refs/heads/develop Commit: 90fd0edaf85e3d175a5908760d1c841b4ac97096 Parents: 201cfea Author: danbress <[email protected]> Authored: Sun Mar 8 12:00:11 2015 -0400 Committer: danbress <[email protected]> Committed: Fri Mar 20 09:49:29 2015 -0400 ---------------------------------------------------------------------- .../src/main/asciidoc/developer-guide.adoc | 35 ++++++++++++++++++++ 1 file changed, 35 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-nifi/blob/90fd0eda/nifi/nifi-docs/src/main/asciidoc/developer-guide.adoc ---------------------------------------------------------------------- diff --git a/nifi/nifi-docs/src/main/asciidoc/developer-guide.adoc b/nifi/nifi-docs/src/main/asciidoc/developer-guide.adoc index d8b5d50..35a4eb8 100644 --- a/nifi/nifi-docs/src/main/asciidoc/developer-guide.adoc +++ b/nifi/nifi-docs/src/main/asciidoc/developer-guide.adoc @@ -656,6 +656,41 @@ public static final ExampleProcessor extends Processor { } ---- +=== Documenting FlowFile Attribute Interaction + +Many times a processor will expect certain FlowFile attributes be set on in-bound FlowFiles in order +for the processor to function properly. In other cases a processor may update or +create FlowFile attributes on the out-bound FlowFile. Processor developers may document both of these +behaviors using the `ReadsAttribute` and `WritesAttribute` documentation annotations. These attributes are used to generate documentation +that gives users a better understanding of how a processor will interact with the flow. + +Note: Because Java 7 does not support +repeated annotations on a type, you may need to use `ReadsAttributes` and `WritesAttributes` to indicate +that a processor reads or writes multiple FlowFile attributes. This annotation can only be applied to Processors. An example is listed below: + +[source, java] +---- +@WritesAttributes({ @WritesAttribute(attribute = "invokehttp.status.code", description = "The status code that is returned"), + @WritesAttribute(attribute = "invokehttp.status.message", description = "The status message that is returned"), + @WritesAttribute(attribute = "invokehttp.response.body", description = "The response body"), + @WritesAttribute(attribute = "invokehttp.request.url", description = "The request URL"), + @WritesAttribute(attribute = "invokehttp.tx.id", description = "The transaction ID that is returned after reading the response"), + @WritesAttribute(attribute = "invokehttp.remote.dn", description = "The DN of the remote server") }) +public final class InvokeHTTP extends AbstractProcessor { +---- + +=== Documenting Related Components +Often Processors and ControllerServices are related to one another. Sometimes its a put/get relation as in `PutFile` and `GetFile`. +Sometimes a Processor uses a ControllerService like `InvokeHTTP` and `StandardSSLContextService`. Sometimes one ControllerService uses another +like `DistributedMapCacheClientService` and `DistributedMapCacheServer`. Developers of these extension points may relate these +different components using the `SeeAlso` tag. This annotation links these components in the documentation. +`SeeAlso` can be applied to Processors, ControllerServices and ReportingTasks. An example of how to do this is listed below: + +[source, java] +---- +@SeeAlso(GetFile.class) +public class PutFile extends AbstractProcessor { +---- === Advanced Documentation
