com.phoenixnap.oss.ramlapisync.parser

Class ResourceParser

java.lang.Object

com.phoenixnap.oss.ramlapisync.parser.ResourceParser

Direct Known Subclasses:

SpringMvcResourceParser

public abstract class ResourceParser
extends Object

Common service scanning functionality

Since:

0.0.1

Author:

Kurt Paris

Field Summary

Fields

Modifier and Type	Field and Description
static String	CATCH_ALL_MEDIA_TYPE
protected static String	CSRF_HEADER
protected String	defaultMediaType
protected static Pattern	IGNORE_METHOD_REGEX
protected JavaDocExtractor	javaDocs
protected static org.slf4j.Logger	logger
protected String	version

Constructor Summary

Constructors

Constructor and Description
ResourceParser(File javaDocPath, String version, String defaultMediaType)

Method Summary

Modifier and Type	Method and Description
protected abstract void	addHeadersForMethod(RamlAction action, RamlActionType actionType, Method method) Allows children to add common headers to API methods (eg CSRF, Authorization)
static boolean	doesActionTypeSupportMultipartMime(RamlActionType target) Method to check if a specific action type supports multipart mime request
static boolean	doesActionTypeSupportRequestBody(RamlActionType target) Method to check if a specific action type supports payloads in the body of the request
protected abstract void	extractAndAppendResourceInfo(Class<?> clazz, Method method, JavaDocEntry docEntry, RamlResource parentResource) Extracts relevant info from a Java method and converts it into a RAML resource
protected String	extractExpectedMimeTypeFromMethod(Method method) Checks the annotations and return type that the method returns and the mime it corresponds to
protected String	extractMimeTypeFromMethod(Method method) Checks the annotations and return type that the method returns and the mime it corresponds to
protected Map<String,RamlQueryParameter>	extractQueryParameters(RamlActionType apiAction, Method method, Map<String,String> parameterComments) Extracts parameters from a method call and attaches these with the comments extracted from the javadoc
protected Pair<String,RamlMimeType>	extractRequestBody(Method method, Map<String,String> parameterComments, String comment, List<ApiParameterMetadata> apiParameters) Converts a method body into a request json schema and a mime type.
protected Map<String,RamlMimeType>	extractRequestBodyFromMethod(RamlActionType apiAction, Method method, Map<String,String> parameterComments) Extracts the TOs and other parameters from a method and will convert into JsonSchema for inclusion in the body TODO refactor this code structure
protected abstract ApiParameterMetadata[]	extractResourceIdParameter(Method method) Queries the parameters in the Method and checks for an AjaxParameter Annotation with the resource Id flag enabled
RamlResource	extractResourceInfo(Class<?> clazz) Extracts class information from a (believe it or not) java class as well as the contained methods.
protected RamlResponse	extractResponseFromMethod(Method method, String responseComment) Extracts the Response Body from a method in JsonSchema Format and embeds it into a response object based on the defaultMediaType
protected abstract List<ApiParameterMetadata>	getApiParameters(Method method, boolean includeUrlParameters, boolean includeNonUrlParameters) Allows children to specify which parameters within a method should be included in API generation
protected abstract Map<RamlActionType,String>	getHttpMethodAndName(Class<?> clazz, Method method) Extracts the http method (verb) as well as the name of the api call
protected abstract String	getResourceName(Class<?> clazz) Extracts the name of the resource that this class manages
protected abstract boolean	isActionOnResourceWithoutCommand(Method method) Checks is this api call is made directly on a resource without a trailing command in the URL.
protected abstract boolean	isQueryParameter(Parameter param) Allows children to specify whether a parameter should be included when generating query parameters for a method
void	setJavaDocs(JavaDocExtractor javaDocs) Update JavaDoc extractor
protected abstract boolean	shouldAddMethodToApi(Method method) Allows child Scanners to add their own logic on whether a method should be treated as an API or ignored

Methods inherited from class java.lang.Object

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

Field Detail

logger

protected static final org.slf4j.Logger logger

IGNORE_METHOD_REGEX

protected static final Pattern IGNORE_METHOD_REGEX

CSRF_HEADER

protected static final String CSRF_HEADER

See Also:

Constant Field Values

CATCH_ALL_MEDIA_TYPE

public static final String CATCH_ALL_MEDIA_TYPE

See Also:

Constant Field Values

javaDocs

protected JavaDocExtractor javaDocs

version

protected String version

defaultMediaType

protected String defaultMediaType

Constructor Detail

ResourceParser

public ResourceParser(File javaDocPath,
                      String version,
                      String defaultMediaType)

Method Detail

setJavaDocs

public void setJavaDocs(JavaDocExtractor javaDocs)

Update JavaDoc extractor

Parameters:

javaDocs - The java doc extractor to use (if any)

doesActionTypeSupportRequestBody

public static boolean doesActionTypeSupportRequestBody(RamlActionType target)

Method to check if a specific action type supports payloads in the body of the request

Parameters:

target - The target Verb to check

Returns:

If true, the verb supports a payload in the request body

doesActionTypeSupportMultipartMime

public static boolean doesActionTypeSupportMultipartMime(RamlActionType target)

Method to check if a specific action type supports multipart mime request

Parameters:

target - The target Verb to check

Returns:

If true, the verb supports multipart mime request

shouldAddMethodToApi

protected abstract boolean shouldAddMethodToApi(Method method)

Allows child Scanners to add their own logic on whether a method should be treated as an API or ignored

Parameters:

method - The method to inspect

Returns:

If true the method is annotated in such a way that it should be included in the raml

extractQueryParameters

protected Map<String,RamlQueryParameter> extractQueryParameters(RamlActionType apiAction,
                                                                Method method,
                                                                Map<String,String> parameterComments)

Extracts parameters from a method call and attaches these with the comments extracted from the javadoc

Parameters:

apiAction - The Verb of the action containing these parametes

method - The method to inspect

parameterComments - The parameter comments associated with these parameters

Returns:

A collection of parameters keyed by name

isQueryParameter

protected abstract boolean isQueryParameter(Parameter param)

Allows children to specify whether a parameter should be included when generating query parameters for a method

Parameters:

param - The the Parameter to be checked

Returns:

IF true this is a parameter that shuold be appended in the query string

getApiParameters

protected abstract List<ApiParameterMetadata> getApiParameters(Method method,
                                                               boolean includeUrlParameters,
                                                               boolean includeNonUrlParameters)

Allows children to specify which parameters within a method should be included in API generation

Parameters:

method - The method to inspect

includeUrlParameters - If true this will include URL parameters

includeNonUrlParameters - If true this will include query and body params

Returns:

A list of request parameters for this API

extractRequestBodyFromMethod

protected Map<String,RamlMimeType> extractRequestBodyFromMethod(RamlActionType apiAction,
                                                                Method method,
                                                                Map<String,String> parameterComments)

Extracts the TOs and other parameters from a method and will convert into JsonSchema for inclusion in the body TODO refactor this code structure

Parameters:

apiAction - The Verb of the action to be added

method - The method to be inspected

parameterComments - The parameter comments associated with these parameters

Returns:

A map of supported mime types for the request

extractRequestBody

protected Pair<String,RamlMimeType> extractRequestBody(Method method,
                                                       Map<String,String> parameterComments,
                                                       String comment,
                                                       List<ApiParameterMetadata> apiParameters)

Converts a method body into a request json schema and a mime type. TODO refactor this code structure

Parameters:

method - The method to be used to get the request object

parameterComments - Associated JavaDoc for Parameters (if any)

comment - Main Method Javadoc Comment (if any)

apiParameters - The Parameters identifed from this method

Returns:

The Request Body as a schema and the associated mime type

addHeadersForMethod

protected abstract void addHeadersForMethod(RamlAction action,
                                            RamlActionType actionType,
                                            Method method)

Allows children to add common headers to API methods (eg CSRF, Authorization)

Parameters:

action - The action to be modified

actionType - The verb of the Action

method - The method to inspect for headers

extractResourceIdParameter

protected abstract ApiParameterMetadata[] extractResourceIdParameter(Method method)

Queries the parameters in the Method and checks for an AjaxParameter Annotation with the resource Id flag enabled

Parameters:

method - The Method to be inspected

Returns:

A list of parameters that are exposed in the API

getHttpMethodAndName

protected abstract Map<RamlActionType,String> getHttpMethodAndName(Class<?> clazz,
                                                                   Method method)

Extracts the http method (verb) as well as the name of the api call

Parameters:

clazz - The controller class

method - The Method to inspect

Returns:

The Verb and Name (partial url if a resource needs to be created) of this method

extractAndAppendResourceInfo

protected abstract void extractAndAppendResourceInfo(Class<?> clazz,
                                                     Method method,
                                                     JavaDocEntry docEntry,
                                                     RamlResource parentResource)

Extracts relevant info from a Java method and converts it into a RAML resource

Parameters:

clazz - The controller class

method - The Java method to introspect

docEntry - The associated JavaDoc (may be null)

parentResource - The Resource which contains this method

isActionOnResourceWithoutCommand

protected abstract boolean isActionOnResourceWithoutCommand(Method method)

Checks is this api call is made directly on a resource without a trailing command in the URL. eg: POST on /myResource/

Parameters:

method - The method to check

Returns:

If true then this is an Action/Verb on a resource collection

extractMimeTypeFromMethod

protected String extractMimeTypeFromMethod(Method method)

Checks the annotations and return type that the method returns and the mime it corresponds to

Parameters:

method - The method to inspect

Returns:

The mime type as string

extractExpectedMimeTypeFromMethod

protected String extractExpectedMimeTypeFromMethod(Method method)

Checks the annotations and return type that the method returns and the mime it corresponds to

Parameters:

method - The method to inspect

Returns:

The mime type this method can work on

extractResponseFromMethod

protected RamlResponse extractResponseFromMethod(Method method,
                                                 String responseComment)

Extracts the Response Body from a method in JsonSchema Format and embeds it into a response object based on the defaultMediaType

Parameters:

method - The method to inspect

responseComment - The JavaDoc (if any) for this response

Returns:

The response RAML model for this method (success only)

extractResourceInfo

public RamlResource extractResourceInfo(Class<?> clazz)

Extracts class information from a (believe it or not) java class as well as the contained methods.

Parameters:

clazz - The Class to be inspected

Returns:

The RAML Resource model for this class

getResourceName

protected abstract String getResourceName(Class<?> clazz)

Extracts the name of the resource that this class manages

Parameters:

clazz - The Class to inspect

Returns:

The name of the resource this class maps to