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 and 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 and Description
protected ClassLoader	cl
protected 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 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 Function<org.jboss.jandex.AnnotationInstance,org.eclipse.microprofile.openapi.models.parameters.Parameter>	readerFunction
protected AnnotationScannerContext	scannerContext

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and 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.
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 org.jboss.jandex.DotName	getDefaultAnnotationName()
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	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.

Methods inherited from class java.lang.Object

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

Field Detail

scannerContext

protected final AnnotationScannerContext scannerContext

index

protected final org.jboss.jandex.IndexView index

cl

protected final ClassLoader cl

readerFunction

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

extensions

protected final List<AnnotationScannerExtension> extensions

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 Detail

AbstractParameterProcessor

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

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

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 {@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

getDefaultAnnotationName

protected org.jboss.jandex.DotName getDefaultAnnotationName()

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

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)