You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by da...@apache.org on 2017/03/10 08:21:37 UTC
[3/3] camel git commit: Cleaned Javadoc and Ascii doc for REST DSL
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 <da...@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) {