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 <[email protected]> Authored: Thu Mar 5 11:20:51 2015 -0500 Committer: danbress <[email protected]> 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")
