Cleaned Javadoc and Ascii doc for REST DSL
Project: http://git-wip-us.apache.org/repos/asf/camel/repo Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/fca73e05 Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/fca73e05 Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/fca73e05 Branch: refs/heads/master Commit: fca73e0521105d269b8bbd616aa7af28627f8b4f Parents: 0d9cb00 Author: Scott Cranton <sc...@cranton.com> Authored: Thu Mar 9 21:33:09 2017 -0500 Committer: Claus Ibsen <davscl...@apache.org> Committed: Fri Mar 10 09:21:26 2017 +0100 ---------------------------------------------------------------------- .../src/main/docs/rest-api-component.adoc | 21 +++++++- .../camel/model/rest/RestBindingDefinition.java | 34 +++++++----- .../apache/camel/model/rest/VerbDefinition.java | 56 +++++++++++--------- 3 files changed, 71 insertions(+), 40 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/fca73e05/camel-core/src/main/docs/rest-api-component.adoc ---------------------------------------------------------------------- diff --git a/camel-core/src/main/docs/rest-api-component.adoc b/camel-core/src/main/docs/rest-api-component.adoc index 2d9429d..efd4477 100644 --- a/camel-core/src/main/docs/rest-api-component.adoc +++ b/camel-core/src/main/docs/rest-api-component.adoc @@ -408,6 +408,25 @@ rest("/users/") .to("direct:newUser"); ----------------------------------------------------------------------------------------------------------- +To specify input and/or output using an array, append `[]` to the end +of the canonical class name, or you can alternatively use the Java DSL only +continence `typeList` and `outTypeList` where you just specify the array element type. +Both approaches are shown in the following Java DSL: + +[source,java] +----------------------------------------------------------------------------------------------------------- +// configure to use restlet on localhost with the given port +// and enable auto binding mode +restConfiguration().component("restlet").host("localhost").port(portNum).bindingMode(RestBindingMode.auto); + +// use the rest DSL to define the rest services +rest("/users/") + .post().type(UserPojo[].class).outType(CountryPojo[].class) + .to("direct:newUser") + .put().typeList(UserPojo.class).outTypeList(CountryPojo.class) + .to("direct:updateUser"); +----------------------------------------------------------------------------------------------------------- + The `UserPojo` is just a plain pojo with getter/setter as shown: [source,java] @@ -660,7 +679,7 @@ onException(JsonParseException.class)  -### Parameter default Values +### Query Parameter default Values You can specify default values for parameters in the rest-dsl, such as the verbose parameter below: http://git-wip-us.apache.org/repos/asf/camel/blob/fca73e05/camel-core/src/main/java/org/apache/camel/model/rest/RestBindingDefinition.java ---------------------------------------------------------------------- diff --git a/camel-core/src/main/java/org/apache/camel/model/rest/RestBindingDefinition.java b/camel-core/src/main/java/org/apache/camel/model/rest/RestBindingDefinition.java index 8c1c291..1c037d4 100644 --- a/camel-core/src/main/java/org/apache/camel/model/rest/RestBindingDefinition.java +++ b/camel-core/src/main/java/org/apache/camel/model/rest/RestBindingDefinition.java @@ -244,8 +244,8 @@ public class RestBindingDefinition extends OptionalIdentifiedDefinition<RestBind /** * Adds a default value for the query parameter * - * @param paramName query parameter name - * @param defaultValue the default value + * @param paramName query parameter name. + * @param defaultValue the default value. */ public void addDefaultValue(String paramName, String defaultValue) { if (defaultValues == null) { @@ -254,7 +254,6 @@ public class RestBindingDefinition extends OptionalIdentifiedDefinition<RestBind defaultValues.put(paramName, defaultValue); } - /** * Gets the registered default values for query parameters */ @@ -263,7 +262,7 @@ public class RestBindingDefinition extends OptionalIdentifiedDefinition<RestBind } /** - * Sets the component name that this definition will apply to + * @param component name of the component that this definition will apply to. */ public void setComponent(String component) { this.component = component; @@ -274,7 +273,7 @@ public class RestBindingDefinition extends OptionalIdentifiedDefinition<RestBind } /** - * To define the content type what the REST service consumes (accept as input), such as application/xml or application/json + * @param consumes the HTTP Content Type of the input data, such as {@code application/xml} or {@code application/json}. */ public void setConsumes(String consumes) { this.consumes = consumes; @@ -285,7 +284,7 @@ public class RestBindingDefinition extends OptionalIdentifiedDefinition<RestBind } /** - * To define the content type what the REST service produces (uses for output), such as application/xml or application/json + * @param produces the HTTP Content Type of the output data, such as {@code application/xml} or {@code application/json}. */ public void setProduces(String produces) { this.produces = produces; @@ -296,9 +295,9 @@ public class RestBindingDefinition extends OptionalIdentifiedDefinition<RestBind } /** - * Sets the binding mode to use. - * <p/> - * The default value is off + * @param bindingMode the binding mode to use. The default value is {@code RestBindingMode.off}. + * + * @see RestBindingMode */ public void setBindingMode(RestBindingMode bindingMode) { this.bindingMode = bindingMode; @@ -310,6 +309,9 @@ public class RestBindingDefinition extends OptionalIdentifiedDefinition<RestBind /** * Sets the class name to use for binding from input to POJO for the incoming data + * + * @param type the canonical name of the class of the input data. Append a {@code []} to the end + * of the canonical name if you want the input to be an array of {@code type}. */ public void setType(String type) { this.type = type; @@ -321,6 +323,9 @@ public class RestBindingDefinition extends OptionalIdentifiedDefinition<RestBind /** * Sets the class name to use for binding from POJO to output for the outgoing data + * + * @param outType the canonical name of the class of the output data. Append a {@code []} to the end + * of the canonical name if you want the output to be an array of {@code outType}. */ public void setOutType(String outType) { this.outType = outType; @@ -331,8 +336,11 @@ public class RestBindingDefinition extends OptionalIdentifiedDefinition<RestBind } /** - * Whether to skip binding on output if there is a custom HTTP error code header. - * This allows to build custom error messages that do not bind to json / xml etc, as success messages otherwise will do. + * @param skipBindingOnErrorCode set to {@code true} to ignore the specified binding mode on output if there + * is a custom HTTP error code header. This allows to build custom error messages + * that do not bind to json / xml etc, as success messages otherwise will do. + * + * @see VerbDefinition#setBindingMode(RestBindingMode) */ public void setSkipBindingOnErrorCode(Boolean skipBindingOnErrorCode) { this.skipBindingOnErrorCode = skipBindingOnErrorCode; @@ -343,9 +351,7 @@ public class RestBindingDefinition extends OptionalIdentifiedDefinition<RestBind } /** - * Whether to enable CORS headers in the HTTP response. - * <p/> - * The default value is false. + * @param enableCORS set to {@code true} to enable CORS headers in the HTTP response. The default value is {@code false}. */ public void setEnableCORS(Boolean enableCORS) { this.enableCORS = enableCORS; http://git-wip-us.apache.org/repos/asf/camel/blob/fca73e05/camel-core/src/main/java/org/apache/camel/model/rest/VerbDefinition.java ---------------------------------------------------------------------- diff --git a/camel-core/src/main/java/org/apache/camel/model/rest/VerbDefinition.java b/camel-core/src/main/java/org/apache/camel/model/rest/VerbDefinition.java index cc6731e..35f66e9 100644 --- a/camel-core/src/main/java/org/apache/camel/model/rest/VerbDefinition.java +++ b/camel-core/src/main/java/org/apache/camel/model/rest/VerbDefinition.java @@ -129,7 +129,7 @@ public class VerbDefinition extends OptionalIdentifiedDefinition<VerbDefinition> } /** - * Sets swagger operation response messages + * Sets swagger operation response messages. */ public void setResponseMsgs(List<RestOperationResponseMsgDefinition> params) { this.responseMsgs = responseMsgs; @@ -140,7 +140,7 @@ public class VerbDefinition extends OptionalIdentifiedDefinition<VerbDefinition> } /** - * The HTTP verb such as GET or POST + * @param method the HTTP verb name such as {@code get, post, put, patch, delete, head}. */ public void setMethod(String method) { this.method = method; @@ -151,7 +151,7 @@ public class VerbDefinition extends OptionalIdentifiedDefinition<VerbDefinition> } /** - * Uri template of this REST service such as /{id}. + * @param uri the query path for this REST service, such as {@code /{id}}. */ public void setUri(String uri) { this.uri = uri; @@ -162,8 +162,8 @@ public class VerbDefinition extends OptionalIdentifiedDefinition<VerbDefinition> } /** - * To define the content type what the REST service consumes (accept as input), such as application/xml or application/json. - * This option will override what may be configured on a parent level + * @param consumes the HTTP Content Type of the input data, such as {@code application/xml} or {@code application/json}. + * This option will override what may be configured on a parent level. */ public void setConsumes(String consumes) { this.consumes = consumes; @@ -174,8 +174,8 @@ public class VerbDefinition extends OptionalIdentifiedDefinition<VerbDefinition> } /** - * To define the content type what the REST service produces (uses for output), such as application/xml or application/json - * This option will override what may be configured on a parent level + * @param produces the HTTP Content Type of the output data, such as {@code application/xml} or {@code application/json}. + * This option will override what may be configured on a parent level. */ public void setProduces(String produces) { this.produces = produces; @@ -186,10 +186,10 @@ public class VerbDefinition extends OptionalIdentifiedDefinition<VerbDefinition> } /** - * Sets the binding mode to use. - * This option will override what may be configured on a parent level - * <p/> - * The default value is auto + * @param bindingMode the binding mode to use. The default value is {@code RestBindingMode.auto}. + * This option will override what may be configured on a parent level. + * + * @see RestBindingMode */ public void setBindingMode(RestBindingMode bindingMode) { this.bindingMode = bindingMode; @@ -200,9 +200,12 @@ public class VerbDefinition extends OptionalIdentifiedDefinition<VerbDefinition> } /** - * Whether to skip binding on output if there is a custom HTTP error code header. - * This allows to build custom error messages that do not bind to json / xml etc, as success messages otherwise will do. - * This option will override what may be configured on a parent level + * @param skipBindingOnErrorCode set to {@code true} to ignore the specified binding mode on output if there + * is a custom HTTP error code header. This allows to build custom error messages + * that do not bind to json / xml etc, as success messages otherwise will do. + * This option will override what may be configured on a parent level. + * + * @see VerbDefinition#setBindingMode(RestBindingMode) */ public void setSkipBindingOnErrorCode(Boolean skipBindingOnErrorCode) { this.skipBindingOnErrorCode = skipBindingOnErrorCode; @@ -213,10 +216,8 @@ public class VerbDefinition extends OptionalIdentifiedDefinition<VerbDefinition> } /** - * Whether to enable CORS headers in the HTTP response. - * This option will override what may be configured on a parent level - * <p/> - * The default value is false. + * @param enableCORS set to {@code true} to enable CORS headers in the HTTP response. The default value is {@code false}. + * This option will override what may be configured on a parent level. */ public void setEnableCORS(Boolean enableCORS) { this.enableCORS = enableCORS; @@ -228,7 +229,10 @@ public class VerbDefinition extends OptionalIdentifiedDefinition<VerbDefinition> /** * Sets the class name to use for binding from input to POJO for the incoming data - * This option will override what may be configured on a parent level + * This option will override what may be configured on a parent level. + * + * @param type the canonical name of the class of the input data. Append a {@code []} to the end + * of the canonical name if you want the input to be an array of {@code type}. */ public void setType(String type) { this.type = type; @@ -240,7 +244,10 @@ public class VerbDefinition extends OptionalIdentifiedDefinition<VerbDefinition> /** * Sets the class name to use for binding from POJO to output for the outgoing data - * This option will override what may be configured on a parent level + * This option will override what may be configured on a parent level. + * + * @param outType the canonical name of the class of the output data. Append a {@code []} to the end + * of the canonical name if you want the output to be an array of {@code outType}. */ public void setOutType(String outType) { this.outType = outType; @@ -251,7 +258,7 @@ public class VerbDefinition extends OptionalIdentifiedDefinition<VerbDefinition> } /** - * The route id this rest-dsl is using (read-only) + * @param routeId the route id this rest-dsl is using (read-only). */ public void setRouteId(String routeId) { this.routeId = routeId; @@ -262,9 +269,8 @@ public class VerbDefinition extends OptionalIdentifiedDefinition<VerbDefinition> } /** - * Whether to include or exclude the VerbDefinition in API documentation. - * <p/> - * The default value is true. + * @param apiDocs set to {@code true} to include or exclude the VerbDefinition in API documentation. + * The default value is true. */ public void setApiDocs(Boolean apiDocs) { this.apiDocs = apiDocs; @@ -389,7 +395,7 @@ public class VerbDefinition extends OptionalIdentifiedDefinition<VerbDefinition> public String asVerb() { // we do not want the jaxb model to repeat itself, by outputting <get method="get"> - // so we defer the verb from the instance type + // so we infer the verb from the instance type if (this instanceof GetVerbDefinition) { return "get"; } else if (this instanceof PostVerbDefinition) {
