[jira] [Commented] (NIFI-5859) Update NAR maven plugin to include information about Extensions

["ASF GitHub Bot (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/NIFI-5859?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16710175#comment-16710175 ] 

ASF GitHub Bot commented on NIFI-5859:
--------------------------------------

Github user markap14 commented on a diff in the pull request:

    https://github.com/apache/nifi/pull/3192#discussion_r239101308
  
    --- Diff: nifi-api/src/main/java/org/apache/nifi/documentation/AbstractDocumentationWriter.java ---
    @@ -0,0 +1,301 @@
    +/*
    + * Licensed to the Apache Software Foundation (ASF) under one or more
    + * contributor license agreements.  See the NOTICE file distributed with
    + * this work for additional information regarding copyright ownership.
    + * The ASF licenses this file to You under the Apache License, Version 2.0
    + * (the "License"); you may not use this file except in compliance with
    + * the License.  You may obtain a copy of the License at
    + *
    + *     http://www.apache.org/licenses/LICENSE-2.0
    + *
    + * Unless required by applicable law or agreed to in writing, software
    + * distributed under the License is distributed on an "AS IS" BASIS,
    + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    + * See the License for the specific language governing permissions and
    + * limitations under the License.
    + */
    +package org.apache.nifi.documentation;
    +
    +import org.apache.nifi.annotation.behavior.DynamicProperties;
    +import org.apache.nifi.annotation.behavior.DynamicProperty;
    +import org.apache.nifi.annotation.behavior.DynamicRelationship;
    +import org.apache.nifi.annotation.behavior.InputRequirement;
    +import org.apache.nifi.annotation.behavior.ReadsAttribute;
    +import org.apache.nifi.annotation.behavior.ReadsAttributes;
    +import org.apache.nifi.annotation.behavior.Restricted;
    +import org.apache.nifi.annotation.behavior.Stateful;
    +import org.apache.nifi.annotation.behavior.SystemResourceConsideration;
    +import org.apache.nifi.annotation.behavior.WritesAttribute;
    +import org.apache.nifi.annotation.behavior.WritesAttributes;
    +import org.apache.nifi.annotation.documentation.CapabilityDescription;
    +import org.apache.nifi.annotation.documentation.DeprecationNotice;
    +import org.apache.nifi.annotation.documentation.SeeAlso;
    +import org.apache.nifi.annotation.documentation.Tags;
    +import org.apache.nifi.components.ConfigurableComponent;
    +import org.apache.nifi.components.PropertyDescriptor;
    +import org.apache.nifi.controller.ControllerService;
    +import org.apache.nifi.documentation.init.DocumentationControllerServiceInitializationContext;
    +import org.apache.nifi.documentation.init.DocumentationProcessorInitializationContext;
    +import org.apache.nifi.documentation.init.DocumentationReportingInitializationContext;
    +import org.apache.nifi.processor.Processor;
    +import org.apache.nifi.processor.Relationship;
    +import org.apache.nifi.reporting.InitializationException;
    +import org.apache.nifi.reporting.ReportingTask;
    +
    +import java.io.BufferedReader;
    +import java.io.IOException;
    +import java.io.InputStream;
    +import java.io.InputStreamReader;
    +import java.io.Reader;
    +import java.io.StringWriter;
    +import java.io.Writer;
    +import java.util.ArrayList;
    +import java.util.Arrays;
    +import java.util.Collection;
    +import java.util.Collections;
    +import java.util.List;
    +import java.util.Set;
    +
    +/**
    + * Base class for DocumentationWriter that simplifies iterating over all information for a component, creating a separate method
    + * for each, to ensure that implementations properly override all methods and therefore properly account for all information about
    + * a component.
    + *
    + * Please note that while this class lives within the nifi-api, it is provided primarily as a means for documentation components within
    + * the NiFi NAR Maven Plugin. Its home is the nifi-api, however, because the API is needed in order to extract the relevant information and
    + * the NAR Maven Plugin cannot have a direct dependency on nifi-api (doing so would cause a circular dependency). By having this homed within
    + * the nifi-api, the Maven plugin is able to discover the class dynamically and invoke the one or two methods necessary to create the documentation.
    + *
    + * This is a new capability in 1.9.0 in preparation for the Extension Registry and therefore, you should
    + * <b>NOTE WELL:</b> At this time, while this class is part of nifi-api, it is still evolving and may change in a non-backward-compatible manner or even be
    + * removed from one incremental release to the next. Use at your own risk!
    + */
    +public abstract class AbstractDocumentationWriter implements DocumentationWriter {
    +
    +    @Override
    +    public final void write(final ConfigurableComponent component) throws IOException {
    +        write(component, null);
    +    }
    +
    +    @Override
    +    public final void write(final ConfigurableComponent component, final Collection<ProvidedServiceAPI> providedServices) throws IOException {
    +        initialize(component);
    +
    +        writeHeader(component);
    +        writeBody(component);
    +
    +        if (providedServices != null && component instanceof ControllerService) {
    +            writeProvidedServices(providedServices);
    +        }
    +
    +        writeFooter(component);
    +    }
    +
    +    private void initialize(final ConfigurableComponent component) {
    +        try {
    +            if (component instanceof Processor) {
    +                initialize((Processor) component);
    +            } else if (component instanceof ControllerService) {
    +                initialize((ControllerService) component);
    +            } else if (component instanceof ReportingTask) {
    +                initialize((ReportingTask) component);
    +            }
    +        } catch (final InitializationException ie) {
    +            throw new RuntimeException("Failed to initialize " + component, ie);
    +        }
    +    }
    +
    +    protected void initialize(final Processor processor) {
    +        processor.initialize(new DocumentationProcessorInitializationContext());
    +    }
    +
    +    protected void initialize(final ControllerService service) throws InitializationException {
    +        service.initialize(new DocumentationControllerServiceInitializationContext());
    +    }
    +
    +    protected void initialize(final ReportingTask reportingTask) throws InitializationException {
    +        reportingTask.initialize(new DocumentationReportingInitializationContext());
    +    }
    +
    +    protected void writeBody(final ConfigurableComponent component) throws IOException {
    +        final String additionalDetails = getAdditionalDetailsHtml(component);
    +
    +        writeExtensionName(component.getClass().getName());
    +        writeDeprecationNotice(component.getClass().getAnnotation(DeprecationNotice.class));
    +        writeDescription(getDescription(component));
    +        writeTags(getTags(component));
    +        writeProperties(component.getPropertyDescriptors());
    +        writeDynamicProperties(getDynamicProperties(component));
    +
    +        if (component instanceof Processor) {
    +            final Processor processor = (Processor) component;
    +
    +            writeRelationships(processor.getRelationships());
    +            writeDynamicRelationship(getDynamicRelationship(processor));
    +            writeReadsAttributes(getReadsAttributes(processor));
    +            writeWritesAttributes(getWritesAttributes(processor));
    +        }
    +
    +        writeStatefulInfo(component.getClass().getAnnotation(Stateful.class));
    +        writeRestrictedInfo(component.getClass().getAnnotation(Restricted.class));
    +        writeInputRequirementInfo(getInputRequirement(component));
    +        writeSystemResourceConsiderationInfo(getSystemResourceConsiderations(component));
    +        writeSeeAlso(component.getClass().getAnnotation(SeeAlso.class));
    +        writeAdditionalDetails(additionalDetails);
    +    }
    +
    +    protected String getAdditionalDetailsHtml(final ConfigurableComponent component) throws IOException {
    --- End diff --
    
    That's probably a good idea. Will do that.


> Update NAR maven plugin to include information about Extensions
> ---------------------------------------------------------------
>
>                 Key: NIFI-5859
>                 URL: https://issues.apache.org/jira/browse/NIFI-5859
>             Project: Apache NiFi
>          Issue Type: New Feature
>          Components: Tools and Build
>            Reporter: Mark Payne
>            Assignee: Mark Payne
>            Priority: Major
>
> In order to have the NiFi Registry host any extensions, the registry will need a way to know what extensions exist in a given NAR. Currently, that information is not available directly.
> The NAR maven plugin should be updated to provide a list of extensions and for each one, provide at least the following minimal information:
>  * Extension Type
>  * Extension Name
>  * Capability Description
>  * Whether or not the component is Restricted, "sub-restrictions" it has, and explanations of both
>  * Any Tags that the component has
>  * If the component is a Controller Service, any Controller Service API's that it provides
> Additionally, it would be ideal to provide all documentation for the component within the NAR. It is best, though, not to write the documentation in HTML as is done now but rather in XML or some sort of form that provides the information in a structured way without any styling. This would allow the documentation to be rendered consistently, even if the styling changes from 1 version to the next.



--
This message was sent by Atlassian JIRA
(v7.6.3#76005)