private static Link extractResponseLink(MethodDoc methodDoc) {
// this means there is a response body for this method.
Type returnType = methodDoc.returnType();
String schema = SchemaUtils.getEffectiveSchema(returnType.qualifiedTypeName());
if (schema == null) return null;
Link reponseLink = new Link();
StringBuilder builder = new StringBuilder();
builder.append("${").append(returnType.qualifiedTypeName()).append("}");
reponseLink.setHref(builder.toString());
reponseLink.setDisplay(returnType.simpleTypeName());
return reponseLink;
}
public ResourceMethod(MethodDoc method, MethodDoc declaringMethod, ResourceClass resource) {
this.resource = resource;
this.method = method;
this.declaringClass = resource.getDeclaringClass();
this.declaringMethod = declaringMethod;
this.output = new MethodOutput(declaringMethod);
try {
formClass = Class.forName("org.jboss.resteasy.annotations.Form");
} catch (ClassNotFoundException e) {
// we won't support @Form
}
setupPath();
setupParameters();
setupMethods();
setupMIMEs();
// is this a resource locator?
if (methods.isEmpty() && !declaringMethod.returnType().isPrimitive()) {
// Handle Class style resource locator factory methods
Type t = declaringMethod.returnType();
if ("java.lang.Class".equals(t.qualifiedTypeName())) {
ParameterizedType p = t.asParameterizedType();
if (p != null) {
t = p.typeArguments()[0];
}
}
resourceLocator = new ResourceClass(t.asClassDoc(), this);
}
}
private void printOutputGenericType(Type type) {
String link = null;
if (!type.isPrimitive()) {
link = Utils.getExternalLink(configuration.parentConfiguration, type, writer);
}
if (link == null) {
print(type.qualifiedTypeName());
} else {
around("a href='" + link + "'", type.typeName());
}
ParameterizedType pType = type.asParameterizedType();
if (pType != null) {
boolean first = true;
print("<");
for (Type genericType : pType.typeArguments()) {
if (first) {
first = false;
} else {
print(",");
}
printOutputGenericType(genericType);
}
print(">");
}
print(type.dimension());
}
/** Print a a basic type t */
private String type(Options opt, Type t) {
String type = "";
if (opt.showQualified) type = t.qualifiedTypeName();
else type = t.typeName();
type += typeParameters(opt, t.asParameterizedType());
return type;
}
/**
* Parse type variables for generics
*
* @param variables
* @return
*/
protected static TypeVar[] ParseTypeVariables(TypeVariable[] variables, ParamTag[] tags) {
TypeVar[] vars = null;
if (variables != null && variables.length > 0) {
ArrayList<TypeVar> varsList = new ArrayList<TypeVar>();
for (TypeVariable variable : variables) {
TypeVar var = new TypeVar();
var.name = variable.typeName();
Type[] bounds = variable.bounds();
if (bounds != null && bounds.length > 0) {
ArrayList<String> list = new ArrayList<String>();
for (Type bound : bounds) {
list.add(bound.qualifiedTypeName());
}
var.bounds = list.toArray(new String[] {});
}
for (ParamTag tag : tags)
if (tag.parameterName().equals(var.name)) var.comment = tag.parameterComment();
varsList.add(var);
}
vars = varsList.toArray(new TypeVar[] {});
}
return vars;
}
private static String generateResponseExample(final DocHttpMethod httpMethod) {
Type returnType = httpMethod.getReturnDetails().getReturnType();
String typeName = returnType.qualifiedTypeName();
if (typeName.equals(void.class.getName())) {
return RESPONSE_HAS_NO_BODY_MSG;
}
String generateExample = null;
try {
generateExample = responseExampleGenerator.generateExample(returnType);
generateExample = Utils.getIndentJson(generateExample);
} catch (Exception e) {
logger.warning(
"Could not generate response example for method: "
+ httpMethod.getMethodSignatureName()
+ " with the return value type ["
+ typeName
+ "]. Exception was: "
+ e);
generateExample =
RestDocConstants.FAILED_TO_CREATE_RESPONSE_EXAMPLE
+ LINE_SEPARATOR
+ "Return value type: "
+ typeName
+ "."
+ LINE_SEPARATOR
+ "The exception caught was "
+ e;
}
return generateExample;
}
/**
* Parses a type definition
*
* @param type
* @return
*/
protected static TypeInfo ParseType(Type type) {
TypeInfo typeInfo = new TypeInfo();
typeInfo.qualifiedName = type.qualifiedTypeName();
typeInfo.dimension = type.dimension();
typeInfo.wildcard = ParseWildCard(type.asWildcardType());
typeInfo.generics = ParseGenerics(type.asParameterizedType());
return typeInfo;
}
/**
* Parses the enum type definition
*
* @param docClass
* @return
*/
protected static Enum ParseEnum(ClassDoc docClass) {
assert (docClass != null);
Enum xmlEnum = new Enum();
xmlEnum.name = docClass.name();
xmlEnum.qualifiedName = docClass.qualifiedName();
xmlEnum.comment = docClass.commentText();
xmlEnum.isIncluded = docClass.isIncluded();
xmlEnum.scope = DetermineScope(docClass);
Type superClassType = docClass.superclassType();
if (superClassType != null) {
xmlEnum.superClass = superClassType.qualifiedTypeName();
}
Type[] interfaces = docClass.interfaceTypes();
ArrayList<String> interfaceTypeNames = new ArrayList<String>();
if (interfaces != null && interfaces.length > 0) {
for (Type interfaceType : interfaces) {
interfaceTypeNames.add(interfaceType.qualifiedTypeName());
}
}
xmlEnum.extendedFrom = interfaceTypeNames.toArray(new String[] {});
FieldDoc[] fields = docClass.enumConstants();
if (fields != null && fields.length > 0) {
ArrayList<EnumField> fieldList = new ArrayList<EnumField>();
for (FieldDoc field : fields) {
fieldList.add(ParseEnumField(field));
}
xmlEnum.fields = fieldList.toArray(new EnumField[] {});
}
xmlEnum.annotationInstances =
ParseAnnotationInstances(docClass.annotations(), docClass.qualifiedName());
return xmlEnum;
}
private static String generateRequestExmple(final DocHttpMethod httpMethod) {
List<DocParameter> params = httpMethod.getParams();
Type type = null;
for (DocParameter docParameter : params) {
if (requestBodyParamFilter.filter(httpMethod, docParameter)) {
type = docParameter.getType();
break;
}
}
if (type == null) {
return REQUEST_HAS_NO_BODY_MSG;
}
String generateExample = null;
try {
generateExample = requestExampleGenerator.generateExample(type);
generateExample = Utils.getIndentJson(generateExample);
} catch (Exception e) {
logger.warning(
"Could not generate request example for method: "
+ httpMethod.getMethodSignatureName()
+ " with the request parameter type "
+ type.qualifiedTypeName()
+ ". Exception was: "
+ e);
generateExample =
RestDocConstants.FAILED_TO_CREATE_REQUEST_EXAMPLE
+ "."
+ LINE_SEPARATOR
+ "Parameter type: "
+ type.qualifiedTypeName()
+ "."
+ LINE_SEPARATOR
+ "The exception caught was "
+ e;
}
return generateExample;
}
/** The documentation for values() and valueOf() in Enums are set by the doclet. */
public static void setEnumDocumentation(Configuration configuration, ClassDoc classDoc) {
MethodDoc[] methods = classDoc.methods();
for (int j = 0; j < methods.length; j++) {
MethodDoc currentMethod = methods[j];
if (currentMethod.name().equals("values") && currentMethod.parameters().length == 0) {
currentMethod.setRawCommentText(
configuration.getText("doclet.enum_values_doc", classDoc.name()));
} else if (currentMethod.name().equals("valueOf") && currentMethod.parameters().length == 1) {
Type paramType = currentMethod.parameters()[0].type();
if (paramType != null && paramType.qualifiedTypeName().equals(String.class.getName())) {
currentMethod.setRawCommentText(configuration.getText("doclet.enum_valueof_doc"));
}
}
}
}
/**
* Determinse if a specified class definition is a Annotation
*
* @param classDoc
* @return
*/
protected static boolean isAnnotation(ClassDoc classDoc) {
boolean isAnnotation = false;
if (classDoc != null) {
Type[] types = classDoc.interfaceTypes();
if (types != null) {
for (Type type : types) {
isAnnotation =
0
== type.qualifiedTypeName()
.compareTo(java.lang.annotation.Annotation.class.getName());
if (isAnnotation) {
break;
}
}
}
}
return isAnnotation;
}
/**
* Parses an interface type definition
*
* @param docClass
* @return
*/
protected static Interface ParseInterface(ClassDoc docClass) {
assert (docClass != null);
Interface xmlInterface = new Interface();
xmlInterface.name = docClass.name();
xmlInterface.qualifiedName = docClass.qualifiedName();
xmlInterface.comment = docClass.commentText();
xmlInterface.isIncluded = docClass.isIncluded();
xmlInterface.scope = DetermineScope(docClass);
xmlInterface.typeVariables =
ParseTypeVariables(docClass.typeParameters(), docClass.typeParamTags());
Type[] interfaces = docClass.interfaceTypes();
ArrayList<String> interfaceTypeNames = new ArrayList<String>();
if (interfaces != null && interfaces.length > 0) {
for (Type interfaceType : interfaces) {
interfaceTypeNames.add(interfaceType.qualifiedTypeName());
}
xmlInterface.interfaces = interfaceTypeNames.toArray(new String[] {});
}
MethodDoc[] methods = docClass.methods();
if (methods != null && methods.length > 0) {
ArrayList<Method> methodList = new ArrayList<Method>();
for (MethodDoc method : methods) {
methodList.add(ParseMethod(method));
}
xmlInterface.methods = methodList.toArray(new Method[] {});
} else {
log.debug("No methods in interface: " + docClass.name());
}
xmlInterface.annotationInstances =
ParseAnnotationInstances(docClass.annotations(), docClass.qualifiedName());
return xmlInterface;
}
/**
* Process the methods in the class.
*
* @param md An array of MethodDoc objects
*/
public void processMethods(ClassDoc cd, MethodDoc[] md) {
if (trace) System.out.println("PROCESSING " + cd.name() + " METHODS, number = " + md.length);
for (int i = 0; i < md.length; i++) {
String methodName = md[i].name();
if (trace) System.out.println("PROCESSING METHOD: " + methodName);
// Skip <init> and <clinit>
if (methodName.startsWith("<")) continue;
// Only save the shown elements
if (!shownElement(md[i], memberVisibilityLevel)) continue;
outputFile.print(" <method name=\"" + methodName + "\"");
com.sun.javadoc.Type retType = md[i].returnType();
if (retType.qualifiedTypeName().compareTo("void") == 0) {
// Don't add a return attribute if the return type is void
outputFile.println();
} else {
outputFile.print(" return=\"");
emitType(retType);
outputFile.println("\"");
}
outputFile.print(" abstract=\"" + md[i].isAbstract() + "\"");
outputFile.print(" native=\"" + md[i].isNative() + "\"");
outputFile.println(" synchronized=\"" + md[i].isSynchronized() + "\"");
addCommonModifiers(md[i], 6);
outputFile.println(">");
// Generate the parameter elements, if any
Parameter[] params = md[i].parameters();
for (int j = 0; j < params.length; j++) {
outputFile.print(" <param name=\"" + params[j].name() + "\"");
outputFile.print(" type=\"");
emitType(params[j].type());
outputFile.println("\"/>");
}
// Generate the exception elements if any exceptions are thrown
processExceptions(md[i].thrownExceptions());
addDocumentation(md[i], 6);
outputFile.println(" </method>");
} // for
} // processMethods()
private FieldRelationInfo getFieldRelationInfo(FieldDoc field) {
Type type = field.type();
if (type.isPrimitive() || type instanceof WildcardType || type instanceof TypeVariable)
return null;
if (type.dimension().endsWith("[]")) {
return new FieldRelationInfo(type.asClassDoc(), true);
}
Options opt = optionProvider.getOptionsFor(type.asClassDoc());
if (opt.matchesCollPackageExpression(type.qualifiedTypeName())) {
Type[] argTypes = getInterfaceTypeArguments(collectionClassDoc, type);
if (argTypes != null && argTypes.length == 1 && !argTypes[0].isPrimitive())
return new FieldRelationInfo(argTypes[0].asClassDoc(), true);
argTypes = getInterfaceTypeArguments(mapClassDoc, type);
if (argTypes != null && argTypes.length == 2 && !argTypes[1].isPrimitive())
return new FieldRelationInfo(argTypes[1].asClassDoc(), true);
}
return new FieldRelationInfo(type.asClassDoc(), false);
}
protected void forwardDecls(PrintWriter pw, ClassDoc clazz) throws ClassNotFoundException {
ClassDoc clazzfield = null;
if (clazz.qualifiedName().equals("java.lang.Object")) return;
genHandleType(pw, clazz.qualifiedName());
ClassDoc superClass = clazz.superclass();
if (superClass != null) {
String superClassName = superClass.qualifiedName();
forwardDecls(pw, superClass);
}
for (int i = 0; i < fields.length; i++) {
FieldDoc field = (FieldDoc) fields[i];
if (!field.isStatic()) {
Type t = field.type();
String tname = t.qualifiedTypeName();
TypeSignature newTypeSig = new TypeSignature(root);
String sig = newTypeSig.getTypeSignature(tname);
if (sig.charAt(0) != '[') forwardDeclsFromSig(pw, sig);
}
}
for (int i = 0; i < methods.length; i++) {
MethodDoc method = (MethodDoc) methods[i];
if (method.isNative()) {
Type retType = method.returnType();
String typesig = method.signature();
TypeSignature newTypeSig = new TypeSignature(root);
String sig = newTypeSig.getTypeSignature(typesig, retType);
if (sig.charAt(0) != '[') forwardDeclsFromSig(pw, sig);
}
}
}
/**
* Parses annotation instances from the javadoc annotation instance type
*
* @param annotationDocs Annotations decorated on some type
* @return Serializable representation of annotations
*/
protected static AnnotationInstance[] ParseAnnotationInstances(
AnnotationDesc[] annotationDocs, String origin) {
AnnotationInstance[] annotations = null;
if (annotationDocs != null && annotationDocs.length > 0) {
ArrayList<AnnotationInstance> list = new ArrayList<AnnotationInstance>();
for (AnnotationDesc annot : annotationDocs) {
AnnotationInstance instance = new AnnotationInstance();
AnnotationTypeDoc annotTypeInfo = null;
try {
annotTypeInfo = annot.annotationType();
instance.name = annot.annotationType().name();
instance.qualifiedName = annot.annotationType().qualifiedTypeName();
} catch (ClassCastException castException) {
log.error("Unable to obtain type data about an annotation found on: " + origin);
log.error("Add to the -cp parameter the class/jar that defines this annotation.");
instance.name = null;
instance.qualifiedName = null;
}
AnnotationDesc.ElementValuePair[] arguments = annot.elementValues();
if (arguments != null && arguments.length > 0) {
ArrayList<AnnotationArgument> argumentList = new ArrayList<AnnotationArgument>();
for (AnnotationDesc.ElementValuePair pair : arguments) {
AnnotationArgument annotationArgument = new AnnotationArgument();
annotationArgument.name = pair.element().name();
Type annotationArgumentType = pair.element().returnType();
annotationArgument.type = annotationArgumentType.qualifiedTypeName();
annotationArgument.isPrimitive = annotationArgumentType.isPrimitive();
annotationArgument.isArray = annotationArgumentType.dimension().length() > 0;
Object objValue = pair.value().value();
if (objValue instanceof AnnotationValue[]) {
AnnotationValue[] realValues = (AnnotationValue[]) objValue;
String[] values = new String[realValues.length];
for (int i = 0; i < realValues.length; i++) {
values[i] = realValues[i].value().toString();
}
annotationArgument.value = values;
} else if (objValue instanceof Number) {
Number number = (Number) objValue;
annotationArgument.value = new String[] {number.toString()};
} else if (objValue instanceof Character) {
Character character = (Character) objValue;
annotationArgument.value = new String[] {character.toString()};
} else if (objValue instanceof Boolean) {
Boolean booleanValue = (Boolean) objValue;
annotationArgument.value = new String[] {booleanValue.toString()};
} else if (objValue instanceof String) {
String stringValue = (String) objValue;
annotationArgument.value = new String[] {stringValue};
} else if (objValue instanceof FieldDoc) {
FieldDoc field = (FieldDoc) objValue;
annotationArgument.value = new String[] {field.name()};
} else if (objValue instanceof ClassDoc) {
ClassDoc classDoc = (ClassDoc) objValue;
annotationArgument.value = new String[] {classDoc.qualifiedTypeName()};
}
argumentList.add(annotationArgument);
}
instance.arguments = argumentList.toArray(new AnnotationArgument[] {});
}
list.add(instance);
}
annotations = list.toArray(new AnnotationInstance[] {});
}
return annotations;
}
public int compare(Type type1, Type type2) {
return type1
.qualifiedTypeName()
.toLowerCase()
.compareTo(type2.qualifiedTypeName().toLowerCase());
}
