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

Class AbstractParameterProcessor

java.lang.Object
io.smallrye.openapi.runtime.scanner.spi.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 <michael@xlate.io>

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    protected static class 
    AbstractParameterProcessor.ParameterContext
    Used for collecting and merging any scanned Parameter annotations with the framework-specific parameter annotations.
    protected static class 
    AbstractParameterProcessor.ParameterContextKey
    Key used to store AbstractParameterProcessor.ParameterContext objects in a map sorted by Parameter.In, then by name, nulls first.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected static final String
    APPLICATION_FORM_URLENCODED
     
    protected final Optional<BeanValidationScanner>
    beanValidationScanner
     
    protected final String
    contextPath
     
    protected final List<AnnotationScannerExtension>
    extensions
     
    protected String
    formMediaType
    The media type of a form schema found while scanning the parameters.
    protected Map<String,org.jboss.jandex.AnnotationInstance>
    formParams
    Collection of form parameters found during scanning.
    protected final org.jboss.jandex.IndexView
    index
     
    protected Map<String,Map<String,org.jboss.jandex.AnnotationInstance>>
    matrixParams
    Collection of matrix parameters found during scanning.
    protected Map<AbstractParameterProcessor.ParameterContextKey,AbstractParameterProcessor.ParameterContext>
    params
    Collection of parameters scanned at the current level.
    protected final Function<org.jboss.jandex.AnnotationInstance,org.eclipse.microprofile.openapi.models.parameters.Parameter>
    readerFunction
     
    protected final AnnotationScannerContext
    scannerContext
     

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    AbstractParameterProcessor(AnnotationScannerContext scannerContext, String contextPath, Function<org.jboss.jandex.AnnotationInstance,org.eclipse.microprofile.openapi.models.parameters.Parameter> reader, List<AnnotationScannerExtension> extensions)
     

  • Method Summary

    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 @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 @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 @Parameter or @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.
    protected static org.jboss.jandex.MethodInfo
    targetMethod(org.jboss.jandex.AnnotationTarget target)
    Obtain the MethodInfo associated with the annotation target.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • APPLICATION_FORM_URLENCODED

      protected static final String APPLICATION_FORM_URLENCODED
      See Also:

    • scannerContext

      protected final AnnotationScannerContext scannerContext

    • 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

    • extensions

      protected final List<AnnotationScannerExtension> extensions

    • beanValidationScanner

      protected final Optional<BeanValidationScanner> beanValidationScanner

    • params

      protected Map<AbstractParameterProcessor.ParameterContextKey,AbstractParameterProcessor.ParameterContext> params
      Collection of parameters scanned at the current level. This map contains all parameter types except for form parameters and matrix parameters.

    • 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.

  • Constructor Details

  • Method Details

    • 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

    • getMatrixParameter

      protected abstract FrameworkParameter getMatrixParameter()

    • 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 @Parameter or @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 @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 @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

    • targetMethod

      protected static org.jboss.jandex.MethodInfo targetMethod(org.jboss.jandex.AnnotationTarget target)
      Obtain the MethodInfo associated with the annotation target.
      Parameters:
      target - annotated item. Only method and method parameter targets.
      Returns:
      the MethodInfo associated with the target, or null if target is not a method or parameter.

    • 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)