package com.iggroup.restdoc.doclet;
/**
* An abstract parameter.
*
* Abstraction is used when a parameter is searched by a predicate.
*/
public abstract class AbstractParameter {
/**
* Gets the name of this parameter.
*
* @return the parameter's name.
*/
public abstract String getName();
/**
* Gets the Java type of this parameter.
*
* @return the parameter's Java type.
*/
public abstract String getType();
}
package com.iggroup.restdoc.doclet;
/**
* This parameter is for HTTP response content-type sent as a HTTP request-header.
*/
public class AcceptApplicationParameter extends ApplicationParameter {
/**
* The name of HTTP response content-type header.
*/
public static final String NAME = "Accept";
/**
* No-argument constructor.
*/
public AcceptApplicationParameter() {
super(NAME, "Response Content-Type");
}
}
package com.iggroup.restdoc.doclet;
import static org.apache.commons.lang.StringUtils.trimToNull;
import org.apache.commons.lang.builder.CompareToBuilder;
import org.apache.commons.lang.builder.EqualsBuilder;
import org.apache.commons.lang.builder.HashCodeBuilder;
import org.apache.commons.lang.builder.ToStringBuilder;
import org.apache.commons.lang.builder.ToStringStyle;
/**
* This class creates an application-parameter.
*
* These parameters are method-arguments annotated with <code>@RequestParam</code>
*
* <p>The HTTP response content-type (see {@link AcceptApplicationParameter}) is used by default.
*
* <p>Since version 2.x, these parameters were no longer serialised.
*/
public class ApplicationParameter extends AbstractParameter implements Comparable<ApplicationParameter> {
/**
* The name of this parameter.
*/
private String name;
/**
* The Java type of this parameter.
*
* The type of application-parameters is <code>java.lang.String</code>.
*/
private String type = String.class.getSimpleName();
/**
* The documentation of this parameter.
*/
private String javadoc;
/**
* No-argument constructor for this class to be used as a bean or by JiBX binding.
*/
public ApplicationParameter() {
super();
}
/**
* Constructs this parameter with its name.
*
* @param name the parameter's name.
*/
public ApplicationParameter(final String name) {
super();
this.name = trimToNull(name);
}
/**
* Constructs this parameter with its name and its documentation.
*
* @param name the parameter's name.
* @param javadoc the parameter's documentation.
*/
public ApplicationParameter(final String name, final String javadoc) {
this(name);
this.javadoc = trimToNull(javadoc);
}
/**
* {@inheritDoc}
*/
public String getName() {
return name;
}
/**
* Sets the name of this parameter.
*
* @param name the parameter's name.
*/
public void setName(final String name) {
this.name = trimToNull(name);
}
/**
* {@inheritDoc}
*/
public String getType() {
return type;
}
/**
* Sets the Java type of this parameter.
*
* @param type the parameter's Java type.
*/
public void setType(final String type) {
this.type = trimToNull(type);
}
/**
* Gets the documentation of this parameter.
*
* @return the parameter's documentation.
*/
public String getJavadoc() {
return javadoc;
}
/**
* Sets the documentation of this parameter.
*
* @param javadoc the parameter's documentation.
*/
public void setJavadoc(final String javadoc) {
this.javadoc = trimToNull(javadoc);
}
/**
* {@inheritDoc}
*/
public boolean equals(final Object obj) {
boolean result;
if (obj instanceof ApplicationParameter) {
final ApplicationParameter param = (ApplicationParameter) obj;
result = new EqualsBuilder()
.append(name, param.name)
.append(type, param.type)
.isEquals();
} else {
result = false;
}
return result;
}
/**
* {@inheritDoc}
*/
public int hashCode() {
return new HashCodeBuilder()
.append(name)
.append(type)
.toHashCode();
}
/**
* {@inheritDoc}
*/
public int compareTo(final ApplicationParameter param) {
int result;
if (param == null) {
result = 1;
} else {
result = new CompareToBuilder()
.append(name, param.name)
.append(type, param.type)
.toComparison();
}
return result;
}
/**
* {@inheritDoc}
*/
public String toString() {
return new ToStringBuilder(this, ToStringStyle.SHORT_PREFIX_STYLE)
.append("name", name)
.append("type", type)
.append("javadoc", javadoc)
.toString();
}
}
package com.iggroup.restdoc.doclet;
import static com.iggroup.restdoc.doclet.util.AnnotationUtils.elementValue;
import static org.apache.commons.lang.StringUtils.isBlank;
import java.util.Collection;
import org.apache.commons.lang.builder.CompareToBuilder;
import org.apache.commons.lang.builder.EqualsBuilder;
import org.apache.commons.lang.builder.HashCodeBuilder;
import org.apache.commons.lang.builder.ToStringBuilder;
import org.apache.commons.lang.builder.ToStringStyle;
import org.springframework.web.bind.annotation.RequestBody;
import com.iggroup.restdoc.doclet.util.AnnotationUtils;
import com.iggroup.restdoc.doclet.util.DocletUtils;
import com.sun.javadoc.AnnotationValue;
import com.sun.javadoc.ClassDoc;
import com.sun.javadoc.ParamTag;
import com.sun.javadoc.Parameter;
/**
* This class creates documentation for a body-parameter.
*/
public class BodyParameter extends AbstractParameter implements
Comparable<BodyParameter> {
/**
* The name of this parameter.
*/
private String name;
/**
* The Java type of this parameter.
*/
private String type;
/**
* The documentation of this parameter.
*/
private String javadoc;
/**
* The field-parameters in this body-parameter.
*/
private Collection<FieldParameter> fields;
/**
* No-argument constructor for this class to be used as a bean or by JiBX
* binding.
*/
public BodyParameter() {
super();
}
/**
* Constructs this parameter from its Java documentation object and Java
* documentation tags of the parameters of the method it belongs to.
*
* <p>
* The name of this parameter is the value of <code>@bodyAttribute</code>
* annotation. If not defined, the name of its argument is used.
*
* @param param
* the parameter's Java documentation object.
* @param tags
* the Java documentation tags of the parameters of the method
* this parameter belongs to.
*/
public BodyParameter(final Parameter param, final ParamTag[] tags) {
super();
initName(param);
initType(param);
initJavadoc(param, tags);
initFields(param.type().asClassDoc());
}
/**
* Initialises the name of this parameter.
*
* @param param
* the parameter's Java documentation object.
*/
private void initName(final Parameter param) {
final AnnotationValue value = elementValue(param, RequestBody.class,
"value");
if (value == null) {
name = param.name();
} else {
if (isBlank(value.value().toString())) {
name = param.name();
} else {
name = value.value().toString().trim();
}
}
}
/**
* Initialises the Java type of this parameter.
*
* @param param
* the parameter's Java documentation object.
*/
private void initType(final Parameter param) {
type = AnnotationUtils.getTypeName(param.type());
}
/**
* Initialises the documentation of this parameter.
*
* @param param
* the parameter's Java documentation object.
* @param tags
* the Java documentation tags of the parameters of the method
* this parameter belongs to.
*/
private void initJavadoc(final Parameter param, final ParamTag[] tags) {
for (ParamTag tag : tags) {
if (param.name().equals(tag.parameterName())) {
javadoc = AnnotationUtils.getTypeDoc(param.type());
if (javadoc.isEmpty()) { // no class doc found, revert to tag comment
javadoc = tag.parameterComment();
}
break;
}
}
}
/**
* Initialises the field-parameters in this body-parameter.
*
* @param classDoc
* the parameter's Java documentation object.
*/
private void initFields(final ClassDoc classDoc) {
fields = DocletUtils.getPublicFields(classDoc);
}
/**
* {@inheritDoc}
*/
public String getName() {
return name;
}
/**
* Sets the name of this parameter.
*
* @param name
* the parameter's name.
*/
public void setName(final String name) {
this.name = name;
}
/**
* {@inheritDoc}
*/
public String getType() {
return type;
}
/**
* Sets the Java type of this parameter.
*
* @param type
* the parameter's Java type.
*/
public void setType(final String type) {
this.type = type;
}
/**
* Gets the documentation of this parameter.
*
* @return the parameter's documentation.
*/
public String getJavadoc() {
return javadoc;
}
/**
* Sets the documentation of this parameter.
*
* @param javadoc
* the parameter's documentation.
*/
public void setJavadoc(final String javadoc) {
this.javadoc = javadoc;
}
/**
* Gets the field-parameters of this parameter.
*
* @return the parameter's field-parameters.
*/
public Collection<FieldParameter> getFields() {
return fields;
}
/**
* Sets the field-parameters of this parameter.
*
* @param fields
* the parameter's field-parameters.
*/
public void setFields(final Collection<FieldParameter> fields) {
this.fields = fields;
}
/**
* {@inheritDoc}
*/
public boolean equals(final Object obj) {
boolean result;
if (obj instanceof BodyParameter) {
final BodyParameter param = (BodyParameter) obj;
result = new EqualsBuilder().append(name, param.name)
.append(type, param.type).isEquals();
} else {
result = false;
}
return result;
}
/**
* {@inheritDoc}
*/
public int hashCode() {
return new HashCodeBuilder().append(name).append(type).toHashCode();
}
/**
* {@inheritDoc}
*/
public int compareTo(final BodyParameter param) {
int result;
if (param == null) {
result = 1;
} else {
result = new CompareToBuilder().append(name, param.name)
.append(type, param.type).toComparison();
}
return result;
}
/**
* {@inheritDoc}
*/
public String toString() {
return new ToStringBuilder(this, ToStringStyle.SHORT_PREFIX_STYLE)
.append("name", name).append("type", type)
.append("fields", fields).append("javadoc", javadoc).toString();
}
}
package com.iggroup.restdoc.doclet;
import static com.iggroup.restdoc.doclet.util.AnnotationUtils.isAnnotated;
import static org.apache.commons.lang.StringUtils.trimToNull;
import java.util.ArrayList;
import java.util.Collection;
import org.apache.commons.lang.builder.CompareToBuilder;
import org.apache.commons.lang.builder.EqualsBuilder;
import org.apache.commons.lang.builder.HashCodeBuilder;
import org.apache.commons.lang.builder.ToStringBuilder;
import org.apache.commons.lang.builder.ToStringStyle;
import org.springframework.web.bind.annotation.RequestMapping;
import com.sun.javadoc.ClassDoc;
/**
* This class creates documentation for Spring's controllers. The classes should be annotated with
* <code>@Controller</code>.
*/
public class Controller implements Comparable<Controller> {
/**
* The filename suffix of documentation created by {@link XmlDoclet} for controllers.
*
* For example, if the classname is <code>foo.Baz</code>, its documentation will be created in
* <code>foo/Baz.controller.xml</code>.
*/
public static final String FILE_SUFFIX = ".controller.xml";
/**
* The Java type of this controller.
*/
private String type;
/**
* The documentation of this controller.
*/
private String javadoc;
/**
* The methods annotated with <code>@RequestMapping</code> in the source class.
*/
private Collection<Method> methods;
/**
* No-argument constructor for this class to be used as a bean or by JiBX binding.
*/
public Controller() {
/* no-argument constructor */
}
/**
* Constructs this controller using its Java type, its documentation and its methods. The methods
* are annotated with <code>@RequestMapping</code>.
*
* <p>This constructor is used while generating services.
*
* @param type the controller's Java type.
* @param javadoc the controller's documentation.
* @param methods the controller's methods.
*/
public Controller(final String type, final String javadoc, final Collection<Method> methods) {
this.type = trimToNull(type);
this.javadoc = trimToNull(javadoc);
this.methods = methods;
}
/**
* Constructs this controller using its Java documentation object.
*
* @param classDoc the controller's Java documentation object.
*/
public Controller(final ClassDoc classDoc) {
initType(classDoc);
initJavadoc(classDoc);
initMethods(classDoc);
}
/**
* Initialises the Java type of this controller.
*
* @param classDoc the controller's Java documentation object.
*/
private void initType(final ClassDoc classDoc) {
type = classDoc.qualifiedName();
}
/**
* Initialises the documentation of this controller.
*
* @param classDoc the controller's Java documentation object.
*/
private void initJavadoc(final ClassDoc classDoc) {
javadoc = trimToNull(classDoc.commentText());
}
/**
* Initialises the methods in this controller annotated with <code>@RequestMapping</code> in the
* source class.
*
* @param classDoc the controller's Java documentation object.
*/
private void initMethods(final ClassDoc classDoc) {
methods = new ArrayList<Method>();
for (int i = 0; classDoc.methods(false) != null && i < classDoc.methods(false).length; i++) {
if (isAnnotated(classDoc.methods(false)[i], RequestMapping.class)) {
methods.add(new Method(classDoc.methods(false)[i]));
}
}
}
/**
* Gets the Java type of this controller.
*
* @return the controller's Java type.
*/
public String getType() {
return type;
}
/**
* Sets the Java type of this controller.
*
* @param type the controller's Java type.
*/
public void setType(final String type) {
this.type = trimToNull(type);
}
/**
* Gets the documentation of this controller.
*
* @return the controller's documentation.
*/
public String getJavadoc() {
return javadoc;
}
/**
* Sets the documentation of this controller.
*
* @param javadoc the controller's documentation.
*/
public void setJavadoc(final String javadoc) {
this.javadoc = javadoc;
}
/**
* Gets the methods in this controller annotated with <code>@RequestMapping</code> in the source
* class.
*
* @return the controller's methods.
*/
public Collection<Method> getMethods() {
return methods;
}
/**
* Sets the methods in this controller annotated with <code>@RequestMapping</code> in the source
* class.
*
* @param methods the controller's methods.
*/
public void setMethods(final Collection<Method> methods) {
if (methods == null) {
throw new IllegalArgumentException("setMethods(null)");
} else {
this.methods = methods;
}
}
/**
* {@inheritDoc}
*/
public boolean equals(final Object obj) {
boolean result;
if (obj instanceof Controller) {
final Controller cntrl = (Controller) obj;
result = new EqualsBuilder()
.append(type, cntrl.type)
.isEquals();
} else {
result = false;
}
return result;
}
/**
* {@inheritDoc}
*/
public int hashCode() {
return new HashCodeBuilder()
.append(type)
.toHashCode();
}
/**
* {@inheritDoc}
*/
public int compareTo(final Controller controller) {
int result;
if (controller == null) {
result = 1;
} else {
result = new CompareToBuilder()
.append(type, controller.type)
.toComparison();
}
return result;
}
/**
* {@inheritDoc}
*/
public String toString() {
return new ToStringBuilder(ToStringStyle.SHORT_PREFIX_STYLE)
.append("type", type)
.append("javadoc", javadoc)
.append("methods", methods)
.toString();
}
}