Skip to content

Commit f16c1d7

Browse files
gk-browngk-brown
committed
Update README.md.
1 parent 198a077 commit f16c1d7

File tree

4 files changed

+54
-22
lines changed

4 files changed

+54
-22
lines changed

‎README.md‎

Lines changed: 43 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
[![Maven Central](https://img.shields.io/maven-central/v/org.httprpc/httprpc.svg)](http://repo1.maven.org/maven2/org/httprpc/httprpc/)
33

44
# Introduction
5-
HTTP-RPC is an open-source framework for implementing and interacting with RESTful and REST-like web services in Java. It is extremely lightweight and requires only a Java runtime environment and a servlet container. The entire framework is distributed as a single JAR file that is about 60KB in size, making it an ideal choice for applications where a minimal footprint is desired.
5+
HTTP-RPC is an open-source framework for implementing and interacting with RESTful and REST-like web services in Java. It is extremely lightweight and requires only a Java runtime environment and a servlet container. The entire framework is distributed as a single JAR file that is less than 70KB in size, making it an ideal choice for applications where a minimal footprint is desired.
66

77
This guide introduces the HTTP-RPC framework and provides an overview of its key features.
88

@@ -245,7 +245,9 @@ protected String getKey(int index) { ... }
245245

246246
For example, given the following request:
247247

248-
GET /contacts/jsmith/addresses/home
248+
```
249+
GET /contacts/jsmith/addresses/home
250+
```
249251

250252
the value of the key at index 0 would be "jsmith", and the value at index 1 would be "home".
251253

@@ -266,6 +268,45 @@ protected String getKey(String name) { ... }
266268

267269
For example, given the preceding request, the key with name "contactID" would be "jsmith" and the key with name "addressType" would be "home".
268270

271+
### Documentation
272+
API documentation can be viewed by appending "?api" to a service URL; for example:
273+
274+
```
275+
GET /math?api
276+
```
277+
278+
Service methods are grouped by resource path. Method parameters and return values are encoded as follows:
279+
280+
* `Object`: "any"
281+
* `Void` or `void`: "void"
282+
* `Byte` or `byte`: "byte"
283+
* `Short` or `short`: "short"
284+
* `Integer` or `int`: "integer"
285+
* `Long` or `long`: "long"
286+
* `Float` or `float`: "float"
287+
* `Double` or `double`: "double"
288+
* Any other type that extends `Number`: "number"
289+
* Any type that implements `CharSequence`: "string"
290+
* Any `Enum` type: "enum"
291+
* Any type that extends `java.util.Date`: "date"
292+
* `java.util.time.LocalDate`: "date-local"
293+
* `java.util.time.LocalTime`: "time-local"
294+
* `java.util.time.LocalDateTime`: "datetime-local"
295+
* `java.util.List`: "[<em>element type</em>]"
296+
* `java.util.Map`: "[<em>key type</em>: <em>value type</em>]"
297+
* Any other type: "{property1: <em>property 1 type</em>, property2: <em>property 2 type</em>, ...}"
298+
299+
Methods that produce a custom response can use the `Response` annotation to describe the result. For example:
300+
301+
```
302+
@RequestMethod("GET")
303+
@ResourcePath("map")
304+
@Response("{text: string, number: integer, flag: boolean}")
305+
public void getMap() {
306+
...
307+
}
308+
```
309+
269310
## JSONEncoder and JSONDecoder
270311
The `JSONEncoder` class is used internally by `WebService` to serialize a service response. However, it can also be used by application code. For example, the following method would produce the same result as the map example shown earlier (albeit more verbosely):
271312

‎httprpc-test/src/main/webapp/index.jsp‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
<body>
99

1010
<h2>Test</h2>
11-
<a href="${pageContext.request.contextPath}/math?description">Math (description)</a><br/>
11+
<a href="${pageContext.request.contextPath}/math?api">Math (API)</a><br/>
1212
<br/>
1313

1414
<a href="${pageContext.request.contextPath}/math/sum?a=2&b=4">Sum</a><br/>
@@ -17,15 +17,15 @@
1717

1818
<hr/>
1919

20-
<a href="${pageContext.request.contextPath}/catalog?description">Catalog (description)</a><br/>
20+
<a href="${pageContext.request.contextPath}/catalog?api">Catalog (API)</a><br/>
2121
<br/>
2222

2323
<a href="${pageContext.request.contextPath}/catalog/items">Items</a><br/>
2424
<a href="${pageContext.request.contextPath}/catalog/items/1">Item 1</a><br/>
2525

2626
<hr/>
2727

28-
<a href="${pageContext.request.contextPath}/upload?description">Upload (description)</a><br/>
28+
<a href="${pageContext.request.contextPath}/upload?api">Upload (API)</a><br/>
2929
<br/>
3030

3131
<form action="${pageContext.request.contextPath}/upload" method="post" enctype="multipart/form-data">
@@ -54,14 +54,14 @@
5454

5555
<hr>
5656

57-
<a href="${pageContext.request.contextPath}/tree?description">Tree (description)</a><br/>
57+
<a href="${pageContext.request.contextPath}/tree?api">Tree (API)</a><br/>
5858
<br/>
5959

6060
<a href="${pageContext.request.contextPath}/tree">Tree</a><br/>
6161

6262
<hr>
6363

64-
<a href="${pageContext.request.contextPath}/test?description">Test (description)</a><br/>
64+
<a href="${pageContext.request.contextPath}/test?api">Test (API)</a><br/>
6565
<br/>
6666

6767
<a href="${pageContext.request.contextPath}/test?string=héllo&strings=a&strings=b&strings=c&number=123&flag=true&date=0&localDate=2018-06-28&localTime=10:45&localDateTime=2018-06-28T10:45">GET</a><br/>
@@ -149,7 +149,7 @@
149149

150150
<h2>MongoDB</h2>
151151

152-
<a href="${pageContext.request.contextPath}/restaurants?description">Restaurants (description)</a><br/>
152+
<a href="${pageContext.request.contextPath}/restaurants?api">Restaurants (API)</a><br/>
153153
<br/>
154154

155155
<a href="${pageContext.request.contextPath}/restaurants?zipCode=10462">Restaurants</a><br/>
@@ -159,7 +159,7 @@
159159

160160
<h2>MySQL</h2>
161161

162-
<a href="${pageContext.request.contextPath}/pets?description">Pets (description)</a><br/>
162+
<a href="${pageContext.request.contextPath}/pets?api">Pets (API)</a><br/>
163163
<br/>
164164

165165
<a href="${pageContext.request.contextPath}/pets?owner=Gwen">Pets</a><br/>

‎httprpc/src/main/java/org/httprpc/WebService.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -154,7 +154,7 @@ protected void service(HttpServletRequest request, HttpServletResponse response)
154154
if (verb.equals("get") && pathInfo == null) {
155155
String queryString = request.getQueryString();
156156

157-
if (queryString != null && queryString.equals("description")) {
157+
if (queryString != null && queryString.equals("api")) {
158158
describeService(request, response);
159159
return;
160160
}

‎httprpc/src/main/java/org/httprpc/beans/BeanAdapter.java‎

Lines changed: 3 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -770,20 +770,11 @@ public V setValue(V value) {
770770
* <li>{@link LocalDate}: "date-local"</li>
771771
* <li>{@link LocalTime}: "time-local"</li>
772772
* <li>{@link LocalDateTime}: "datetime-local"</li>
773-
* <li>{@link List}: "[<i>element description</i>]"</li>
774-
* <li>{@link Map}: "[<i>key description</i>: <i>value description</i>]"</li>
773+
* <li>{@link List}: "[<i>element type</i>]"</li>
774+
* <li>{@link Map}: "[<i>key type</i>: <i>value type</i>]"</li>
775+
* <li>Any other type: "{property1: <i>property 1 type</i>, property2: <i>property 2 type</i>, ...}"</li>
775776
* </ul>
776777
*
777-
* Otherwise, the type is assumed to be a bean and is described as follows:
778-
*
779-
* <blockquote>
780-
* {
781-
* property1: <i>property 1 description</i>,
782-
* property2: <i>property 2 description</i>,
783-
* ...
784-
* }
785-
* </blockquote>
786-
*
787778
* @param type
788779
* The type to describe.
789780
*

0 commit comments

Comments
 (0)