You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@nifi.apache.org by jo...@apache.org on 2015/03/21 22:00:32 UTC
[02/29] incubator-nifi git commit: NIFI-309 - Adding support or
SeeAlso
NIFI-309 - Adding support or SeeAlso
Project: http://git-wip-us.apache.org/repos/asf/incubator-nifi/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-nifi/commit/faf976ca
Tree: http://git-wip-us.apache.org/repos/asf/incubator-nifi/tree/faf976ca
Diff: http://git-wip-us.apache.org/repos/asf/incubator-nifi/diff/faf976ca
Branch: refs/heads/develop
Commit: faf976ca91d4e083d28a520974c98dff1acc1905
Parents: 3ac9cba
Author: danbress <db...@onyxconsults.com>
Authored: Thu Mar 5 11:20:51 2015 -0500
Committer: danbress <db...@onyxconsults.com>
Committed: Fri Mar 20 09:42:14 2015 -0400
----------------------------------------------------------------------
.../html/HtmlDocumentationWriter.java | 213 ++++++++++++-------
.../example/FullyDocumentedProcessor.java | 2 +
2 files changed, 139 insertions(+), 76 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-nifi/blob/faf976ca/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-documentation/src/main/java/org/apache/nifi/documentation/html/HtmlDocumentationWriter.java
----------------------------------------------------------------------
diff --git a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-documentation/src/main/java/org/apache/nifi/documentation/html/HtmlDocumentationWriter.java b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-documentation/src/main/java/org/apache/nifi/documentation/html/HtmlDocumentationWriter.java
index b547934..1beeb9f 100644
--- a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-documentation/src/main/java/org/apache/nifi/documentation/html/HtmlDocumentationWriter.java
+++ b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-documentation/src/main/java/org/apache/nifi/documentation/html/HtmlDocumentationWriter.java
@@ -27,6 +27,7 @@ import javax.xml.stream.XMLStreamWriter;
import org.apache.commons.lang3.StringUtils;
import org.apache.nifi.annotation.documentation.CapabilityDescription;
+import org.apache.nifi.annotation.documentation.SeeAlso;
import org.apache.nifi.annotation.documentation.Tags;
import org.apache.nifi.components.AllowableValue;
import org.apache.nifi.components.ConfigurableComponent;
@@ -68,12 +69,14 @@ public class HtmlDocumentationWriter implements DocumentationWriter {
}
/**
- * Writes the head portion of the HTML documentation.
- *
- * @param configurableComponent the component to describe
- * @param xmlStreamWriter the stream to write to
- * @throws XMLStreamException thrown if there was a problem writing to the
- * stream
+ * Writes the head portion of the HTML documentation.
+ *
+ * @param configurableComponent
+ * the component to describe
+ * @param xmlStreamWriter
+ * the stream to write to
+ * @throws XMLStreamException
+ * thrown if there was a problem writing to the stream
*/
protected void writeHead(final ConfigurableComponent configurableComponent,
final XMLStreamWriter xmlStreamWriter) throws XMLStreamException {
@@ -93,9 +96,10 @@ public class HtmlDocumentationWriter implements DocumentationWriter {
}
/**
- * Gets the class name of the component.
- *
- * @param configurableComponent the component to describe
+ * Gets the class name of the component.
+ *
+ * @param configurableComponent
+ * the component to describe
* @return the class name of the component
*/
protected String getTitle(final ConfigurableComponent configurableComponent) {
@@ -104,42 +108,80 @@ public class HtmlDocumentationWriter implements DocumentationWriter {
/**
* Writes the body section of the documentation, this consists of the
- * component description, the tags, and the PropertyDescriptors.
- *
- * @param configurableComponent the component to describe
- * @param xmlStreamWriter the stream writer
- * @param hasAdditionalDetails whether there are additional details present
- * or not
- * @throws XMLStreamException thrown if there was a problem writing to the
- * XML stream
+ * component description, the tags, and the PropertyDescriptors.
+ *
+ * @param configurableComponent
+ * the component to describe
+ * @param xmlStreamWriter
+ * the stream writer
+ * @param hasAdditionalDetails
+ * whether there are additional details present or not
+ * @throws XMLStreamException
+ * thrown if there was a problem writing to the XML stream
*/
- private void writeBody(final ConfigurableComponent configurableComponent,
+ private final void writeBody(final ConfigurableComponent configurableComponent,
final XMLStreamWriter xmlStreamWriter, final boolean hasAdditionalDetails)
throws XMLStreamException {
xmlStreamWriter.writeStartElement("body");
writeDescription(configurableComponent, xmlStreamWriter, hasAdditionalDetails);
writeTags(configurableComponent, xmlStreamWriter);
writeProperties(configurableComponent, xmlStreamWriter);
- writeAdditionalBodyInfo(configurableComponent, xmlStreamWriter);
+ writeAdditionalBodyInfo(configurableComponent, xmlStreamWriter);
+ writeSeeAlso(configurableComponent, xmlStreamWriter);
xmlStreamWriter.writeEndElement();
}
+ /**
+ * Writes the list of components that may be linked from this component.
+ *
+ * @param configurableComponent
+ * the component to describe
+ * @param xmlStreamWriter
+ * the stream writer to use
+ * @throws XMLStreamException
+ * thrown if there was a problem writing the XML
+ */
+ private void writeSeeAlso(ConfigurableComponent configurableComponent, XMLStreamWriter xmlStreamWriter)
+ throws XMLStreamException {
+ final SeeAlso seeAlso = configurableComponent.getClass().getAnnotation(SeeAlso.class);
+ if (seeAlso != null && seeAlso.value().length > 0) {
+ writeSimpleElement(xmlStreamWriter, "h3", "See Also:");
+ xmlStreamWriter.writeStartElement("p");
+ int index = 0;
+ for (final Class<? extends ConfigurableComponent> linkedComponent : seeAlso.value()) {
+ if (index != 0) {
+ xmlStreamWriter.writeCharacters(", ");
+ }
+
+ final String link = "../" + linkedComponent.getCanonicalName() + "/index.html";
+
+ writeLink(xmlStreamWriter, linkedComponent.getSimpleName(), link);
+
+ ++index;
+ }
+ xmlStreamWriter.writeEndElement();
+ }
+ }
+
/**
* This method may be overridden by sub classes to write additional
* information to the body of the documentation.
- *
- * @param configurableComponent the component to describe
- * @param xmlStreamWriter the stream writer
- * @throws XMLStreamException thrown if there was a problem writing to the
- * XML stream
+ *
+ * @param configurableComponent
+ * the component to describe
+ * @param xmlStreamWriter
+ * the stream writer
+ * @throws XMLStreamException
+ * thrown if there was a problem writing to the XML stream
*/
protected void writeAdditionalBodyInfo(final ConfigurableComponent configurableComponent,
final XMLStreamWriter xmlStreamWriter) throws XMLStreamException {
+
}
/**
- * Writes the tags attached to a ConfigurableComponent.
- *
+ * Writes the tags attached to a ConfigurableComponent.
+ *
* @param configurableComponent
* @param xmlStreamWriter
* @throws XMLStreamException
@@ -162,14 +204,17 @@ public class HtmlDocumentationWriter implements DocumentationWriter {
}
/**
- * Writes a description of the configurable component.
- *
- * @param configurableComponent the component to describe
- * @param xmlStreamWriter the stream writer
- * @param hasAdditionalDetails whether there are additional details
- * available as 'additionalDetails.html'
- * @throws XMLStreamException thrown if there was a problem writing to the
- * XML stream
+ * Writes a description of the configurable component.
+ *
+ * @param configurableComponent
+ * the component to describe
+ * @param xmlStreamWriter
+ * the stream writer
+ * @param hasAdditionalDetails
+ * whether there are additional details available as
+ * 'additionalDetails.html'
+ * @throws XMLStreamException
+ * thrown if there was a problem writing to the XML stream
*/
protected void writeDescription(final ConfigurableComponent configurableComponent,
final XMLStreamWriter xmlStreamWriter, final boolean hasAdditionalDetails)
@@ -187,9 +232,10 @@ public class HtmlDocumentationWriter implements DocumentationWriter {
/**
* Gets a description of the ConfigurableComponent using the
- * CapabilityDescription annotation.
- *
- * @param configurableComponent the component to describe
+ * CapabilityDescription annotation.
+ *
+ * @param configurableComponent
+ * the component to describe
* @return a description of the configurableComponent
*/
protected String getDescription(final ConfigurableComponent configurableComponent) {
@@ -207,12 +253,14 @@ public class HtmlDocumentationWriter implements DocumentationWriter {
}
/**
- * Writes the PropertyDescriptors out as a table.
- *
- * @param configurableComponent the component to describe
- * @param xmlStreamWriter the stream writer
- * @throws XMLStreamException thrown if there was a problem writing to the
- * XML Stream
+ * Writes the PropertyDescriptors out as a table.
+ *
+ * @param configurableComponent
+ * the component to describe
+ * @param xmlStreamWriter
+ * the stream writer
+ * @throws XMLStreamException
+ * thrown if there was a problem writing to the XML Stream
*/
protected void writeProperties(final ConfigurableComponent configurableComponent,
final XMLStreamWriter xmlStreamWriter) throws XMLStreamException {
@@ -222,9 +270,8 @@ public class HtmlDocumentationWriter implements DocumentationWriter {
writeSimpleElement(xmlStreamWriter, "strong", "bold");
xmlStreamWriter.writeCharacters(". Any "
+ "other properties (not in bold) are considered optional. The table also "
- + "indicates any default values, whether a property supports the ");
- writeLink(xmlStreamWriter, "NiFi Expression Language",
- "../../html/expression-language-guide.html");
+ + "indicates any default values, whether a property supports the ");
+ writeLink(xmlStreamWriter, "NiFi Expression Language", "../../html/expression-language-guide.html");
xmlStreamWriter.writeCharacters(", and whether a property is considered "
+ "\"sensitive\", meaning that its value will be encrypted. Before entering a "
+ "value in a sensitive property, ensure that the ");
@@ -303,12 +350,14 @@ public class HtmlDocumentationWriter implements DocumentationWriter {
/**
* Interrogates a PropertyDescriptor to get a list of AllowableValues, if
- * there are none, nothing is written to the stream.
- *
- * @param xmlStreamWriter the stream writer to use
- * @param property the property to describe
- * @throws XMLStreamException thrown if there was a problem writing to the
- * XML Stream
+ * there are none, nothing is written to the stream.
+ *
+ * @param xmlStreamWriter
+ * the stream writer to use
+ * @param property
+ * the property to describe
+ * @throws XMLStreamException
+ * thrown if there was a problem writing to the XML Stream
*/
protected void writeValidValues(XMLStreamWriter xmlStreamWriter, PropertyDescriptor property)
throws XMLStreamException {
@@ -325,8 +374,10 @@ public class HtmlDocumentationWriter implements DocumentationWriter {
}
xmlStreamWriter.writeEndElement();
- } else if (property.getControllerServiceDefinition() != null) {
- Class<? extends ControllerService> controllerServiceClass = property.getControllerServiceDefinition();
+ } else if (property.getControllerServiceDefinition() != null) {
+ Class<? extends ControllerService> controllerServiceClass = property
+ .getControllerServiceDefinition();
+
writeSimpleElement(xmlStreamWriter, "strong", "Controller Service: ");
xmlStreamWriter.writeEmptyElement("br");
xmlStreamWriter.writeCharacters(controllerServiceClass.getSimpleName());
@@ -335,14 +386,18 @@ public class HtmlDocumentationWriter implements DocumentationWriter {
/**
* Writes a begin element, then text, then end element for the element of a
- * users choosing. Example: <p>text</p>
- *
- * @param writer the stream writer to use
- * @param elementName the name of the element
- * @param characters the characters to insert into the element
- * @param strong whether the characters should be strong or not.
- * @throws XMLStreamException thrown if there was a problem writing to the
- * stream.
+ * users choosing. Example: <p>text</p>
+ *
+ * @param writer
+ * the stream writer to use
+ * @param elementName
+ * the name of the element
+ * @param characters
+ * the characters to insert into the element
+ * @param strong
+ * whether the characters should be strong or not.
+ * @throws XMLStreamException
+ * thrown if there was a problem writing to the stream.
*/
protected final static void writeSimpleElement(final XMLStreamWriter writer, final String elementName,
final String characters, boolean strong) throws XMLStreamException {
@@ -359,13 +414,16 @@ public class HtmlDocumentationWriter implements DocumentationWriter {
/**
* Writes a begin element, then text, then end element for the element of a
- * users choosing. Example: <p>text</p>
- *
- * @param writer the stream writer to use
- * @param elementName the name of the element
- * @param characters the characters to insert into the element
- * @throws XMLStreamException thrown if there was a problem writing to the
- * stream
+ * users choosing. Example: <p>text</p>
+ *
+ * @param writer
+ * the stream writer to use
+ * @param elementName
+ * the name of the element
+ * @param characters
+ * the characters to insert into the element
+ * @throws XMLStreamException
+ * thrown if there was a problem writing to the stream
*/
protected final static void writeSimpleElement(final XMLStreamWriter writer, final String elementName,
final String characters) throws XMLStreamException {
@@ -373,13 +431,16 @@ public class HtmlDocumentationWriter implements DocumentationWriter {
}
/**
- * A helper method to write a link
- *
- * @param xmlStreamWriter the stream to write to
- * @param text the text of the link
- * @param location the location of the link
- * @throws XMLStreamException thrown if there was a problem writing to the
- * stream
+ * A helper method to write a link
+ *
+ * @param xmlStreamWriter
+ * the stream to write to
+ * @param text
+ * the text of the link
+ * @param location
+ * the location of the link
+ * @throws XMLStreamException
+ * thrown if there was a problem writing to the stream
*/
protected void writeLink(final XMLStreamWriter xmlStreamWriter, final String text, final String location)
throws XMLStreamException {
http://git-wip-us.apache.org/repos/asf/incubator-nifi/blob/faf976ca/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-documentation/src/test/java/org/apache/nifi/documentation/example/FullyDocumentedProcessor.java
----------------------------------------------------------------------
diff --git a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-documentation/src/test/java/org/apache/nifi/documentation/example/FullyDocumentedProcessor.java b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-documentation/src/test/java/org/apache/nifi/documentation/example/FullyDocumentedProcessor.java
index 20307e8..b9bce91 100644
--- a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-documentation/src/test/java/org/apache/nifi/documentation/example/FullyDocumentedProcessor.java
+++ b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-documentation/src/test/java/org/apache/nifi/documentation/example/FullyDocumentedProcessor.java
@@ -24,6 +24,7 @@ import java.util.Set;
import org.apache.nifi.annotation.documentation.CapabilityDescription;
import org.apache.nifi.annotation.documentation.ReadsAttribute;
+import org.apache.nifi.annotation.documentation.SeeAlso;
import org.apache.nifi.annotation.documentation.Tags;
import org.apache.nifi.annotation.documentation.WritesAttribute;
import org.apache.nifi.annotation.documentation.WritesAttributes;
@@ -41,6 +42,7 @@ import org.apache.nifi.processor.util.StandardValidators;
@CapabilityDescription("This is a processor that is used to test documentation.")
@WritesAttributes({@WritesAttribute(attribute="first", description="this is the first attribute i write"), @WritesAttribute(attribute="second")})
@ReadsAttribute(attribute = "incoming", description="this specifies the format of the thing")
+@SeeAlso({FullyDocumentedControllerService.class, FullyDocumentedReportingTask.class})
public class FullyDocumentedProcessor extends AbstractProcessor {
public static final PropertyDescriptor DIRECTORY = new PropertyDescriptor.Builder().name("Input Directory")