Package io.smallrye.openapi.runtime.scanner.spi

Class AbstractParameterProcessor

  • public abstract class AbstractParameterProcessor
extends Object
    Common parameter processing that may be customized by individual frameworks such as JAX-RS, Spring, Vert.x, etc.
    Author:
    Michael Edgar <[email protected]>

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      protected void addEncoding​(Map<String,​org.eclipse.microprofile.openapi.models.media.Encoding> encodings, String paramName, org.jboss.jandex.AnnotationTarget paramTarget)
      Determine if the paramTarget is annotated with the RestEasy PartType annotation and add the value to the encodings map.
      protected String fullPathOf​(org.jboss.jandex.AnnotationTarget target)
      Find the full path of the target, including parent resources if the annotation target is a member of a sub-resource class.
      protected String generatePath​(org.jboss.jandex.AnnotationTarget target, List<org.eclipse.microprofile.openapi.models.parameters.Parameter> parameters)
      Generate the path for the provided annotation target, either a class or a method.
      protected Set<org.jboss.jandex.DotName> getDefaultAnnotationNames()  
      protected String getDefaultAnnotationProperty()  
      protected String getDefaultFormMediaType()  
      protected Object getDefaultValue​(org.jboss.jandex.AnnotationTarget target)
      Scan and parse a default value annotation.
      protected org.eclipse.microprofile.openapi.models.media.Content getFormBodyContent()
      Create a Content and use the scanned form parameters as the properties.
      protected abstract FrameworkParameter getMatrixParameter()  
      protected List<org.eclipse.microprofile.openapi.models.parameters.Parameter> getParameters​(org.jboss.jandex.MethodInfo resourceMethod)
      Performs the final merging of framework parameters with MP-OAI parameters to produce the list of Parameters found while scanning the current level (class or method).
      protected abstract Pattern getTemplateParameterPattern()  
      protected static org.jboss.jandex.Type getType​(org.jboss.jandex.AnnotationTarget target)
      Determines the type of the target.
      protected AbstractParameterProcessor.ParameterContext getUnannotatedPathParameter​(org.jboss.jandex.MethodInfo resourceMethod, String name)  
      protected boolean hasParameters​(Collection<org.jboss.jandex.AnnotationInstance> annotations)
      Check for the existence relevant parameter annotations in the collection.
      protected boolean isIgnoredParameter​(org.eclipse.microprofile.openapi.models.parameters.Parameter parameter, org.jboss.jandex.AnnotationTarget resourceMethod)
      Determine if this is an ignored parameter, per the MP+OAI specification in @Parameter.
      protected abstract boolean isParameter​(org.jboss.jandex.DotName annotationName)  
      protected boolean isReadableParameterAnnotation​(org.jboss.jandex.DotName name)  
      protected abstract boolean isResourceMethod​(org.jboss.jandex.MethodInfo method)
      Determines if the given method is a framework resource method annotated by one of the HTTP method annotations.
      protected abstract boolean isSubResourceLocator​(org.jboss.jandex.MethodInfo method)
      Determines if the given method is a sub-resource locator method annotated by @Path but NOT annotated with one of the HTTP method annotations.
      protected String lastPathSegmentOf​(org.jboss.jandex.AnnotationTarget target)
      Retrieves the last path segment of the full path associated with the target.
      protected static String paramName​(org.jboss.jandex.AnnotationInstance annotation)
      Retrieves the "value" parameter from annotation to be used as the name.
      protected abstract String pathOf​(org.jboss.jandex.AnnotationTarget target)
      Reads the framework's path annotation present on the target and strips leading and trailing slashes.
      protected Object primitiveToObject​(org.jboss.jandex.PrimitiveType.Primitive primitive, String stringValue)  
      protected ResourceParameters process​(org.jboss.jandex.ClassInfo resourceClass, org.jboss.jandex.MethodInfo resourceMethod)  
      protected void processFinalize​(org.jboss.jandex.ClassInfo resourceClass, org.jboss.jandex.MethodInfo resourceMethod, ResourceParameters parameters)  
      protected void processOperationParameters​(org.jboss.jandex.MethodInfo resourceMethod, ResourceParameters parameters)  
      protected void processPathParameters​(org.jboss.jandex.ClassInfo resourceClass, org.jboss.jandex.MethodInfo resourceMethod, ResourceParameters parameters)  
      protected void readAnnotatedType​(org.jboss.jandex.AnnotationInstance annotation)
      Read a single annotation that is either {@literal @}Parameter or one of the framework parameter annotations.
      protected abstract void readAnnotatedType​(org.jboss.jandex.AnnotationInstance annotation, org.jboss.jandex.AnnotationInstance beanParamAnnotation, boolean overriddenParametersOnly)
      Read a single annotation that is either {@literal @}Parameter or one of the framework parameter annotations.
      protected void readFrameworkParameter​(org.jboss.jandex.AnnotationInstance annotation, FrameworkParameter frameworkParam, boolean overriddenParametersOnly)  
      protected void readParameter​(AbstractParameterProcessor.ParameterContextKey key, org.eclipse.microprofile.openapi.models.parameters.Parameter oaiParam, FrameworkParameter frameworkParam, Object defaultValue, org.jboss.jandex.AnnotationTarget target, boolean overriddenParametersOnly)
      Merges MP-OAI Parameters and framework-specific parameters for the same Parameter.In and name, and Parameter.Style.
      protected void readParameterAnnotation​(org.jboss.jandex.AnnotationInstance annotation)
      Read a single annotation that is either {@literal @}Parameter or {@literal @}Parameters.
      protected void readParameterAnnotation​(org.jboss.jandex.AnnotationInstance annotation, boolean overriddenParametersOnly)  
      protected void readParameters​(org.jboss.jandex.ClassInfo clazz, org.jboss.jandex.AnnotationInstance beanParamAnnotation, boolean overriddenParametersOnly)
      Scans for class level parameters.
      protected void readParametersInherited​(org.jboss.jandex.ClassInfo clazz, org.jboss.jandex.AnnotationInstance beanParamAnnotation, boolean overriddenParametersOnly)
      Scans for class level parameters on the given class argument and its ancestors.
      protected void reset()  
      protected org.jboss.jandex.Type resolveType​(org.jboss.jandex.Type targetType)
      Attempt to resolve the type of targetType, using the full stack of resolvers from the scanning context.
      protected void setMediaType​(FrameworkParameter frameworkParam)
      Set this AbstractParameterProcessor's formMediaType if it has not already been set and the value is explicitly known for the parameter type.
      protected void setSchemaProperties​(org.eclipse.microprofile.openapi.models.media.Schema schema, Map<String,​org.eclipse.microprofile.openapi.models.media.Encoding> encodings, Map<String,​org.jboss.jandex.AnnotationInstance> params, boolean schemaAnnotationSupported)
      Converts the collection of parameter annotations to properties set on the given schema.
      protected static org.eclipse.microprofile.openapi.models.parameters.Parameter.Style styleOf​(org.eclipse.microprofile.openapi.models.parameters.Parameter param)
      Retrieves either the provided parameter Parameter.Style, the default style of the parameter based on the in attribute, or null if in is not defined.

    • Field Detail

      • contextPath

        protected final String contextPath

      • index

        protected final org.jboss.jandex.IndexView index

      • readerFunction

        protected final Function<org.jboss.jandex.AnnotationInstance,​org.eclipse.microprofile.openapi.models.parameters.Parameter> readerFunction

      • formParams

        protected Map<String,​org.jboss.jandex.AnnotationInstance> formParams
        Collection of form parameters found during scanning. These annotations will be used as schema properties for a generated schema used in the MP-OAI APIResponse if a value has not be provided by the application.

      • formMediaType

        protected String formMediaType
        The media type of a form schema found while scanning the parameters.

      • matrixParams

        protected Map<String,​Map<String,​org.jboss.jandex.AnnotationInstance>> matrixParams
        Collection of matrix parameters found during scanning. These annotations will be used as schema properties for the schema of a path parameter having style of Parameter.Style.MATRIX.

    • Method Detail

      • reset

        protected void reset()

      • process

        protected ResourceParameters process​(org.jboss.jandex.ClassInfo resourceClass,
                                     org.jboss.jandex.MethodInfo resourceMethod)

      • processPathParameters

        protected void processPathParameters​(org.jboss.jandex.ClassInfo resourceClass,
                                     org.jboss.jandex.MethodInfo resourceMethod,
                                     ResourceParameters parameters)

      • processOperationParameters

        protected void processOperationParameters​(org.jboss.jandex.MethodInfo resourceMethod,
                                          ResourceParameters parameters)

      • processFinalize

        protected void processFinalize​(org.jboss.jandex.ClassInfo resourceClass,
                               org.jboss.jandex.MethodInfo resourceMethod,
                               ResourceParameters parameters)

      • generatePath

        protected String generatePath​(org.jboss.jandex.AnnotationTarget target,
                              List<org.eclipse.microprofile.openapi.models.parameters.Parameter> parameters)
        Generate the path for the provided annotation target, either a class or a method. Add the name of any discovered matrix parameters.
        Parameters:
        target - the target (either class or method)
        parameters - list of all parameters processed
        Returns:
        the path for the target

      • getTemplateParameterPattern

        protected abstract Pattern getTemplateParameterPattern()

      • getParameters

        protected List<org.eclipse.microprofile.openapi.models.parameters.Parameter> getParameters​(org.jboss.jandex.MethodInfo resourceMethod)
        Performs the final merging of framework parameters with MP-OAI parameters to produce the list of Parameters found while scanning the current level (class or method).
        Parameters:
        resourceMethod - the method to which the returned parameters are applicable
        Returns:
        list of Parameters

      • getUnannotatedPathParameter

        protected AbstractParameterProcessor.ParameterContext getUnannotatedPathParameter​(org.jboss.jandex.MethodInfo resourceMethod,
                                                                                  String name)
        Parameters:
        resourceMethod - method potentially containing an un-annotated path parameter argument
        name - name of the path parameter without any associated annotations
        Returns:
        a new ParameterContext if the parameter is found, otherwise null

      • resolveType

        protected org.jboss.jandex.Type resolveType​(org.jboss.jandex.Type targetType)
        Attempt to resolve the type of targetType, using the full stack of resolvers from the scanning context.
        Parameters:
        targetType - the type to resolve
        Returns:
        the resolved type or targetType unchanged if resolution is not possible

      • setSchemaProperties

        protected void setSchemaProperties​(org.eclipse.microprofile.openapi.models.media.Schema schema,
                                   Map<String,​org.eclipse.microprofile.openapi.models.media.Encoding> encodings,
                                   Map<String,​org.jboss.jandex.AnnotationInstance> params,
                                   boolean schemaAnnotationSupported)
        Converts the collection of parameter annotations to properties set on the given schema.
        Parameters:
        schema - the Schema on which the properties will be set
        encodings - map of encodings applicable to the current MediaType being processed
        params - the name/value pairs of annotations for conversion to schema properties
        schemaAnnotationSupported - true if the parameter supports a co-located @Schema annotation

      • getFormBodyContent

        protected org.eclipse.microprofile.openapi.models.media.Content getFormBodyContent()
        Create a Content and use the scanned form parameters as the properties. The media type will be determined by the framework's subclass - e.g. for JAX-RS it may be defaulted to 'application/x-www-form-urlencoded' or set to 'multipart/form-data' if a RESTEasy MultipartForm annotation was used to wrap the javax.ws.rs.FormParams. The encoding values for the Content will be set to the value of any RESTEasy PartType annotations found for each parameter.
        Returns:
        generated form content

      • getDefaultFormMediaType

        protected String getDefaultFormMediaType()

      • addEncoding

        protected void addEncoding​(Map<String,​org.eclipse.microprofile.openapi.models.media.Encoding> encodings,
                           String paramName,
                           org.jboss.jandex.AnnotationTarget paramTarget)
        Determine if the paramTarget is annotated with the RestEasy PartType annotation and add the value to the encodings map.
        Parameters:
        encodings - map of encodings applicable to the current MediaType being processed
        paramName - name of the current form parameter being mapped to a schema property
        paramTarget - the target annotated with the framework's form annotation

      • isIgnoredParameter

        protected boolean isIgnoredParameter​(org.eclipse.microprofile.openapi.models.parameters.Parameter parameter,
                                     org.jboss.jandex.AnnotationTarget resourceMethod)
        Determine if this is an ignored parameter, per the MP+OAI specification in @Parameter. Path parameters that do not have a corresponding path segment will be ignored.
        Parameters:
        parameter - the parameter to determine if ignored
        resourceMethod - the resource method to which the parameter may apply
        Returns:
        true if the parameter should be ignored, false otherwise
        See Also:
        Parameter.name(), Parameter.in()

      • readParameterAnnotation

        protected void readParameterAnnotation​(org.jboss.jandex.AnnotationInstance annotation)
        Read a single annotation that is either {@literal @}Parameter or {@literal @}Parameters. The results are stored in the private params collection.
        Parameters:
        annotation - a parameter annotation to be read and processed

      • readAnnotatedType

        protected void readAnnotatedType​(org.jboss.jandex.AnnotationInstance annotation)
        Read a single annotation that is either {@literal @}Parameter or one of the framework parameter annotations. The results are stored in the private params collection, depending on the type of parameter.
        Parameters:
        annotation - a parameter annotation to be read and processed

      • readAnnotatedType

        protected abstract void readAnnotatedType​(org.jboss.jandex.AnnotationInstance annotation,
                                          org.jboss.jandex.AnnotationInstance beanParamAnnotation,
                                          boolean overriddenParametersOnly)
        Read a single annotation that is either {@literal @}Parameter or one of the framework parameter annotations. The results are stored in the private params collection. When overriddenParametersOnly is true, new parameters not already known in params will be ignored.
        Parameters:
        annotation - a parameter annotation to be read and processed
        beanParamAnnotation - a framework's bean-type (POJO) parameter annotation
        overriddenParametersOnly - true if only parameters already known to the scanner are considered, false otherwise

      • styleOf

        protected static org.eclipse.microprofile.openapi.models.parameters.Parameter.Style styleOf​(org.eclipse.microprofile.openapi.models.parameters.Parameter param)
        Retrieves either the provided parameter Parameter.Style, the default style of the parameter based on the in attribute, or null if in is not defined.
        Parameters:
        param - the Parameter
        Returns:
        the param's style, the default style defined based on in, or null if in is not defined.

      • setMediaType

        protected void setMediaType​(FrameworkParameter frameworkParam)
        Set this AbstractParameterProcessor's formMediaType if it has not already been set and the value is explicitly known for the parameter type.
        Parameters:
        frameworkParam - parameter to check for a form media type

      • paramName

        protected static String paramName​(org.jboss.jandex.AnnotationInstance annotation)
        Retrieves the "value" parameter from annotation to be used as the name. If no value was specified or an empty value, return the name of the annotation target.
        Parameters:
        annotation - parameter annotation
        Returns:
        the name of the parameter

      • getDefaultAnnotationNames

        protected Set<org.jboss.jandex.DotName> getDefaultAnnotationNames()

      • getDefaultAnnotationProperty

        protected String getDefaultAnnotationProperty()

      • getDefaultValue

        protected Object getDefaultValue​(org.jboss.jandex.AnnotationTarget target)
        Scan and parse a default value annotation. If the target is a Java primitive, the value will be parsed into an equivalent wrapper object.
        Parameters:
        target - target annotated with a parameter annotation
        Returns:
        the default value

      • primitiveToObject

        protected Object primitiveToObject​(org.jboss.jandex.PrimitiveType.Primitive primitive,
                                   String stringValue)

      • lastPathSegmentOf

        protected String lastPathSegmentOf​(org.jboss.jandex.AnnotationTarget target)
        Retrieves the last path segment of the full path associated with the target. If the last path segment contains a path variable name, returns the variable name.
        Parameters:
        target -
        Returns:
        the last path segment of the target, or null if no path is defined

      • fullPathOf

        protected String fullPathOf​(org.jboss.jandex.AnnotationTarget target)
        Find the full path of the target, including parent resources if the annotation target is a member of a sub-resource class. Method-level targets will include both the path to the resource and the path to the method joined with a '/'.
        Parameters:
        target - target item for which the path is being generated
        Returns:
        full path (excluding application path) of the target

      • pathOf

        protected abstract String pathOf​(org.jboss.jandex.AnnotationTarget target)
        Reads the framework's path annotation present on the target and strips leading and trailing slashes.
        Parameters:
        target - target object
        Returns:
        value of the framework's path annotation without leading/trailing slashes.

      • getType

        protected static org.jboss.jandex.Type getType​(org.jboss.jandex.AnnotationTarget target)
        Determines the type of the target. Method annotations will give the name of a single argument, assumed to be a "setter" method.
        Parameters:
        target - target object
        Returns:
        object type

      • isReadableParameterAnnotation

        protected boolean isReadableParameterAnnotation​(org.jboss.jandex.DotName name)

      • readParameterAnnotation

        protected void readParameterAnnotation​(org.jboss.jandex.AnnotationInstance annotation,
                                       boolean overriddenParametersOnly)

      • readFrameworkParameter

        protected void readFrameworkParameter​(org.jboss.jandex.AnnotationInstance annotation,
                                      FrameworkParameter frameworkParam,
                                      boolean overriddenParametersOnly)

      • readParameter

        protected void readParameter​(AbstractParameterProcessor.ParameterContextKey key,
                             org.eclipse.microprofile.openapi.models.parameters.Parameter oaiParam,
                             FrameworkParameter frameworkParam,
                             Object defaultValue,
                             org.jboss.jandex.AnnotationTarget target,
                             boolean overriddenParametersOnly)
        Merges MP-OAI Parameters and framework-specific parameters for the same Parameter.In and name, and Parameter.Style. When overriddenParametersOnly is true, new parameters not already known in params will be ignored. The given key contains:
        • the name of the parameter specified by application
        • location, given by @Parameter.in or implied by the type of framework annotation used on the target
        • style, the parameter's style, either specified by the application or implied by the parameter's location
        Parameters:
        key - the key for the parameter being processed
        oaiParam - scanned @Parameter
        frameworkParam - Meta detail about the framework parameter being processed, if found.
        defaultValue - value read from the framework's default-value annotation.
        target - target of the annotation
        overriddenParametersOnly - true if only parameters already known to the scanner are considered, false otherwise

      • readParametersInherited

        protected void readParametersInherited​(org.jboss.jandex.ClassInfo clazz,
                                       org.jboss.jandex.AnnotationInstance beanParamAnnotation,
                                       boolean overriddenParametersOnly)
        Scans for class level parameters on the given class argument and its ancestors.
        Parameters:
        clazz - the class to be scanned for parameters.
        beanParamAnnotation - the bean parameter annotation to be used for path derivation
        overriddenParametersOnly - true if only parameters already known to the scanner are considered, false otherwise

      • readParameters

        protected void readParameters​(org.jboss.jandex.ClassInfo clazz,
                              org.jboss.jandex.AnnotationInstance beanParamAnnotation,
                              boolean overriddenParametersOnly)
        Scans for class level parameters. This method is used for both resource class annotation scanning and framework-specific 'bean' parameter type target type scanning.
        Parameters:
        clazz - the class to be scanned for parameters.
        beanParamAnnotation - the bean parameter annotation to be used for path derivation
        overriddenParametersOnly - true if only parameters already known to the scanner are considered, false otherwise

      • isSubResourceLocator

        protected abstract boolean isSubResourceLocator​(org.jboss.jandex.MethodInfo method)
        Determines if the given method is a sub-resource locator method annotated by @Path but NOT annotated with one of the HTTP method annotations.
        Parameters:
        method - method to check
        Returns:
        true if the method is sub-resource locator, false otherwise

      • isResourceMethod

        protected abstract boolean isResourceMethod​(org.jboss.jandex.MethodInfo method)
        Determines if the given method is a framework resource method annotated by one of the HTTP method annotations.
        Parameters:
        method - method to check
        Returns:
        true if the method is annotated with a framework-specific HTTP method annotation, false otherwise

      • hasParameters

        protected boolean hasParameters​(Collection<org.jboss.jandex.AnnotationInstance> annotations)
        Check for the existence relevant parameter annotations in the collection.
        Parameters:
        annotations - collection of annotations
        Returns:
        true if any of the annotations is a relevant parameter annotation.

      • isParameter

        protected abstract boolean isParameter​(org.jboss.jandex.DotName annotationName)