Package org.revapi

Class AnalysisContext

  • public final class AnalysisContext
extends Object
    An analysis context is an aggregation of the APIs to check and configuration for the analysis.

    The analysis context can also contain arbitrary data that can be then accessed by the extensions. This can be used to pass runtime data to the extensions that cannot be captured by their configurations.

    The configuration accepted by the builder is actually of 2 forms.

    1. The "old style" configuration where each extension could be configured at most once
    2. The "new style" configuration that enables multiple configurations for each extension and is more easily translatable to XML.

    In the old format, the configuration of an extension was nested inside objects corresponding to its exploded extension id. E.g. if the extension had an id of "my.extension", the configuration would look like: 

     
     {
         "my": {
             "extension": {
                 ... the actual configuration of the extension ...
             }
         }
     }
    The original idea for doing things this way was that such configuration is easily mergeable (e.g. when configuration is split across multiple files). There can be only one configuration for each extension and each extension resides in a different "section" of the configuration. The nesting provides for a seemingly logical structure of the configuration.

    On the other hand the new configuration format is different. It stresses the possibility of having more than 1 configuration for an extension and is more easily translatable into XML. On the other hand it is not that well nested as the old configuration style so it might not look that well logically structured. The new configuration looks like this: 

     
     [
         {
             "extension": "my.extension",
             "id": "optional-id",
             "configuration": {
                 ... the actual configuration of the extension ...
             }
         },
         {
             "extension": "other.extension",
             "configuration": {
                 ... the actual configuration of the extension ...
             }
         }
     ]
    Notice that configurations for different extensions (as well as different configurations for the same extension) are contained in a top level list. The configurations of different extensions are therefore no longer nested inside each other, but are "laid out" sequentially.

    Each such configuration can optionally be identified by an arbitrary ID which can be used during merging of configuration from multiple sources.

    Merging Configurations

    As was the case with the old style configurations, the new style configurations can also be merged into each other enabling composition of the final analysis configuration from multiple sources. Because each extension can be configured multiple times in the new style configuration, the identification of the configs to merge is slightly more complicated than it used to.

    As long as the "master" configuration and "mergee" configuration contain ids for each configuration of each extension things are simple. Configurations for the same extension with the same ID are merged together, otherwise their added to the list of all extension configurations.

    Things get a little bit more complex when the configurations don't have an explicit ID. This use case is supported for seamless conversion from old style configuration (where it didn't make sense to have any kind of configuration ID) to new style configurations that we support now (after all there are quite some clients already having their configurations set up and it would be bad to force them to rewrite them all).

    Simply put, id-less configurations are mergeable as long as the master configuration contains only a single configuration for given extension and there is just 1 id-less configuration for given extension in the "mergee".

    Since:
    0.1
    Author:
    Lukas Krejci

    • Method Detail

      • builder

        public static AnalysisContext.Builder builder​(Revapi revapi)
        Returns a new analysis context builder that extracts the information about the available extensions from the provided Revapi instance.

        The extensions have to be known so that both old and new style of configuration can be usefully worked with.

        Parameters:
        revapi - the revapi instance to read the available extensions from
        Returns:
        a new analysis context builder

      • builder

        public static AnalysisContext.Builder builder​(PipelineConfiguration pipelineConfiguration)
        Returns a new analysis context builder that extracts the information about the available extensions from the provided pipeline configuration.

        The extensions have to be known so that both old and new style of configuration can be usefully worked with.

        Parameters:
        pipelineConfiguration - the pipeline configuration to initialize from
        Returns:
        a new analysis context builder

      • builder

        public static AnalysisContext.Builder builder()
        This method can be used to instantiate a new analysis context builder without the need for prior instantiation of Revapi. Such builder is only able to process a new-style configuration though!

        This analysis context will also always uses the default criticalities and severity-to-criticality mapping.

        Returns:
        a new analysis context builder

      • copyWithConfiguration

        @Deprecated
public AnalysisContext copyWithConfiguration​(org.jboss.dmr.ModelNode configuration)
        Deprecated.
        use the Jackson-based variant
        This is generally only useful for extensions that delegate some of their functionality to other "internal" extensions of their own that they need to configure.
        Parameters:
        configuration - the configuration to be supplied with the returned analysis context.
        Returns:
        an analysis context that is a clone of this instance but its configuration is replaced with the provided one.

      • copyWithConfiguration

        public AnalysisContext copyWithConfiguration​(com.fasterxml.jackson.databind.JsonNode configuration)
        This is generally only useful for extensions that delegate some of their functionality to other "internal" extensions of their own that they need to configure.
        Parameters:
        configuration - the configuration to be supplied with the returned analysis context.
        Returns:
        an analysis context that is a clone of this instance but its configuration is replaced with the provided one.

      • copyWithMatchers

        public AnalysisContext copyWithMatchers​(Set<ElementMatcher> matchers)
        A helper method to instantiate a new analysis context with the provided set of matchers. This is only meant to be used during analysis initialization.
        Parameters:
        matchers - the list of matchers to provide through this context
        Returns:
        a copy of this instance with the provided matchers replacing any existing in this instance

      • getLocale

        public Locale getLocale()

      • getConfigurationNode

        public com.fasterxml.jackson.databind.JsonNode getConfigurationNode()
        Returns the configuration node. This is never null. If the configuration is not present a NullNode is returned.

      • getOldApi

        public API getOldApi()

      • getNewApi

        public API getNewApi()