From 5fcf71e7692ac97f6a655946f5639cd8bef921f0 Mon Sep 17 00:00:00 2001 From: Greg Brown Date: Fri, 13 Sep 2024 17:16:22 -0400 Subject: [PATCH] Add support for URI arguments and deprecate support for URL arguments. --- README.md | 66 +++++---- .../org/httprpc/kilo/WebServiceProxy.java | 130 +++++++++++------- .../org/httprpc/kilo/beans/BeanAdapter.java | 38 ++--- .../org/httprpc/kilo/io/TemplateEncoder.java | 102 +++++++++++--- .../httprpc/kilo/io/TemplateEncoderTest.java | 90 ++++++------ .../java/org/httprpc/kilo/IndexServlet.java | 2 +- .../java/org/httprpc/kilo/WebService.java | 2 +- .../org/httprpc/kilo/test/PetService.java | 4 +- .../org/httprpc/kilo/test/AbstractTest.java | 31 ----- .../org/httprpc/kilo/test/BulkUploadTest.java | 11 +- .../org/httprpc/kilo/test/CatalogTest.java | 7 +- .../httprpc/kilo/test/DocumentationTest.java | 7 +- .../org/httprpc/kilo/test/EmployeesTest.java | 15 +- .../java/org/httprpc/kilo/test/Examples.java | 21 +-- .../java/org/httprpc/kilo/test/FilmsTest.java | 7 +- .../java/org/httprpc/kilo/test/PetsTest.java | 13 +- .../org/httprpc/kilo/test/TiingoTest.java | 13 +- .../kilo/test/WebServiceProxyTest.java | 103 +++++++------- .../httprpc/kilo/test/XMLTransformTest.java | 2 +- .../kotlin/org/httprpc/kilo/test/UserTest.kt | 5 +- 20 files changed, 360 insertions(+), 309 deletions(-) delete mode 100644 kilo-test/src/test/java/org/httprpc/kilo/test/AbstractTest.java diff --git a/README.md b/README.md index be824f707..0e5b18423 100644 --- a/README.md +++ b/README.md @@ -76,9 +76,9 @@ public class MathService extends WebService { The `RequestMethod` annotation associates an HTTP verb such as `GET` or `POST` with a service method, or "handler". The optional `ResourcePath` annotation associates a handler with a specific path, or "endpoint", relative to the servlet. If unspecified, the handler is associated with the servlet itself. The optional `Description` annotation is used to document a service implementation and is discussed in more detail [later](#api-documentation). -Arguments may be provided via the query string, resource path, or request body. They may also be submitted as [form data](https://www.w3.org/TR/2014/REC-html5-20141028/forms.html#attr-fs-enctype). `WebService` converts the values to the expected types, invokes the method, and writes the return value (if any) to the output stream as JSON. +Arguments may be provided via the query string, resource path, or request body. `WebService` converts the values to the expected types, invokes the method, and writes the return value (if any) to the output stream as JSON. -Multiple methods may be associated with the same verb and path. `WebService` selects the best method to execute based on the provided argument values. For example, this request would invoke the first method: +Multiple methods may be associated with the same verb and path. `WebService` selects the best method to execute based on the provided values. For example, this request would invoke the first method: ``` GET /math/sum?a=2&b=4 @@ -113,7 +113,6 @@ Method parameters may be any of the following types: * `java.time.Period` * `java.util.UUID` * `java.util.List`, `java.util.Set`, array/varargs -* `java.net.URL` Additionally, `java.util.Map`, bean, and record types are supported for [body content](#body-content). @@ -121,22 +120,17 @@ Unspecified values are automatically converted to `0`, `false`, or the null char `List`, `Set`, and array elements are automatically converted to their declared types. If no values are provided for a list, set, or array parameter, an empty value (not `null`) will be passed to the method. -`URL` parameters represent file uploads. They may be used only with `POST` requests submitted using the multi-part form data encoding. See the [file upload](https://github.com/HTTP-RPC/Kilo/blob/master/kilo-test/src/main/java/org/httprpc/kilo/test/FileUploadService.java) example for more information. - If a provided value cannot be coerced to the expected type, an HTTP 403 (forbidden) response will be returned. If no method is found that matches the provided arguments, HTTP 405 (method not allowed) will be returned. Note that service classes must be compiled with the `-parameters` flag so that parameter names are available at runtime. #### Required Parameters -Parameters that must be provided by the caller can be indicated by the `Required` annotation. For example, the following service method accepts a single required `file` argument: +Parameters that must be provided by the caller can be indicated by the `Required` annotation. For example, the following service method accepts a single required `owner` argument: ```java -@RequestMethod("POST") -@Description("Uploads a single file.") -public long uploadFile( - @Description("The file to upload.") @Required URL file -) throws IOException { - ... +@RequestMethod("GET") +public List getPets(@Required String owner) throws SQLException { + ... } ``` @@ -346,15 +340,13 @@ A JSON version of the generated documentation can be obtained by specifying an " The `WebServiceProxy` class is used to submit API requests to a server. It provides the following two constructors: ```java -public WebServiceProxy(String method, URL url) { ... } -public WebServiceProxy(String method, URL baseURL, String path, Object... arguments) throws MalformedURLException { ... } +public WebServiceProxy(String method, URI uri) { ... } +public WebServiceProxy(String method, URI baseURI, String path, Object... arguments) throws MalformedURLException { ... } ``` -The first version accepts a string representing the HTTP method to execute and the URL of the requested resource. The second accepts the HTTP method, a base URL, and a relative path (as a format string, to which the optional trailing arguments are applied). - -Request arguments are specified via a map passed to the `setArguments()` method. Argument values for `GET`, `PUT`, and `DELETE` requests are always sent in the query string. `POST` arguments are typically sent in the request body, and may be submitted as either "application/x-www-form-urlencoded" or "multipart/form-data" (specified via the proxy's `setEncoding()` method). +The first version accepts a string representing the HTTP method to execute and the URI of the requested resource. The second accepts the HTTP method, a base URI, and a relative path (as a format string, to which the optional trailing arguments are applied). -Any value may be used as an argument and will generally be encoded using its string representation. However, `Date` instances are automatically converted to a long value representing epoch time in milliseconds. Additionally, `Collection` or array instances represent multi-value parameters and behave similarly to `` tags in HTML. +Query arguments are specified via a map passed to the `setArguments()` method. Any value may be used as an argument and will generally be encoded using its string representation. However, `Date` instances are first converted to a long value representing epoch time in milliseconds. Additionally, `Collection` or array instances represent multi-value parameters and behave similarly to `