Skip to content

Commit 8776e59

Browse files
ryberryber
committed
update javadoc
1 parent 923f68f commit 8776e59

3 files changed

Lines changed: 93 additions & 3 deletions

File tree

‎unirest/src/main/java/kong/unirest/core/HttpMethod.java‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,18 +30,36 @@
3030
import java.util.Map;
3131
import java.util.Set;
3232

33+
/**
34+
* Represents an HTTP method (verb) such as GET, POST, or PUT.
35+
* <p>
36+
* Unlike a fixed enum, instances are interned in an internal registry, so custom
37+
* or non-standard verbs can be created and reused via {@link #valueOf(String)}.
38+
* Standard verbs are provided as constants for convenience.
39+
* </p>
40+
*/
3341
public class HttpMethod {
3442
private static final Map<String, HttpMethod> REGISTRY = new HashMap<>();
3543

44+
/** The HTTP GET method. */
3645
public static final HttpMethod GET = valueOf("GET");
46+
/** The HTTP POST method. */
3747
public static final HttpMethod POST = valueOf("POST");
48+
/** The HTTP QUERY method. */
3849
public static final HttpMethod QUERY = valueOf("QUERY");
50+
/** The HTTP PUT method. */
3951
public static final HttpMethod PUT = valueOf("PUT");
52+
/** The HTTP DELETE method. */
4053
public static final HttpMethod DELETE = valueOf("DELETE");
54+
/** The HTTP PATCH method. */
4155
public static final HttpMethod PATCH = valueOf("PATCH");
56+
/** The HTTP HEAD method. */
4257
public static final HttpMethod HEAD = valueOf("HEAD");
58+
/** The HTTP OPTIONS method. */
4359
public static final HttpMethod OPTIONS = valueOf("OPTIONS");
60+
/** The HTTP TRACE method. */
4461
public static final HttpMethod TRACE = valueOf("TRACE");
62+
/** The pseudo-method used for WebSocket connections. */
4563
public static final HttpMethod WEBSOCKET = valueOf("WEBSOCKET");
4664

4765
private final String name;
@@ -50,14 +68,28 @@ private HttpMethod(String name){
5068
this.name = name;
5169
}
5270

71+
/**
72+
* Return the interned {@link HttpMethod} for the given verb, creating it if necessary.
73+
* The verb is normalized to upper case, so lookups are case-insensitive.
74+
* @param verb the HTTP method name
75+
* @return the corresponding HttpMethod instance
76+
*/
5377
public static HttpMethod valueOf(String verb){
5478
return REGISTRY.computeIfAbsent(String.valueOf(verb).toUpperCase(), HttpMethod::new);
5579
}
5680

81+
/**
82+
* Return all HttpMethod instances currently registered.
83+
* @return a set of all known HttpMethods
84+
*/
5785
public Set<HttpMethod> all(){
5886
return new HashSet<>(REGISTRY.values());
5987
}
6088

89+
/**
90+
* Return the name of this HTTP method.
91+
* @return the method name in upper case
92+
*/
6193
public String name() {
6294
return name;
6395
}

‎unirest/src/main/java/kong/unirest/core/Unirest.java‎

Lines changed: 40 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,23 @@
2525

2626
package kong.unirest.core;
2727

28+
/**
29+
* Static entry point for the primary Unirest client.
30+
* <p>
31+
* Use this facade to access the default shared {@link UnirestInstance}, configure
32+
* the global client, create requests, or spawn isolated instances when you need
33+
* separate configuration.
34+
* </p>
35+
*
36+
* <h2>Typical usage</h2>
37+
* <pre>{@code
38+
* Unirest.config().defaultBaseUrl("https://api.example.com");
39+
* String body = Unirest.get("/status").asString().getBody();
40+
* }</pre>
41+
*
42+
* @see UnirestInstance
43+
* @see Config
44+
*/
2845
public class Unirest {
2946

3047
private static UnirestInstance primaryInstance = new UnirestInstance(new Config());
@@ -116,6 +133,11 @@ public static HttpRequestWithBody put(String url) {
116133
return primaryInstance.put(url);
117134
}
118135

136+
/**
137+
* Start a QUERY HttpRequest from the primary config.
138+
* @param url the endpoint to access. Can include placeholders for path params using curly braces {}
139+
* @return A HttpRequest builder
140+
*/
119141
public static HttpRequestWithBody query(String url){
120142
return primaryInstance.query(url);
121143
}
@@ -130,14 +152,30 @@ public static JsonPatchRequest jsonPatch(String url) {
130152
return primaryInstance.jsonPatch(url);
131153
}
132154

155+
/**
156+
* Start an HttpRequest for the given HTTP method from the primary config.
157+
* @param method the HTTP method name
158+
* @param url the endpoint to access. Can include placeholders for path params using curly braces {}
159+
* @return A HttpRequest builder
160+
*/
133161
public static HttpRequestWithBody request(String method, String url) {
134162
return primaryInstance.request(method, url);
135163
}
136164

165+
/**
166+
* Start a WebSocket request from the primary config.
167+
* @param url the endpoint to access
168+
* @return a WebSocket request builder
169+
*/
137170
public static WebSocketRequest webSocket(String url) {
138171
return primaryInstance.webSocket(url);
139172
}
140173

174+
/**
175+
* Start a Server-Sent Events request from the primary config.
176+
* @param url the endpoint to access
177+
* @return an SSE request builder
178+
*/
141179
public static SseRequest sse(String url) {
142180
return primaryInstance.sse(url);
143181
}
@@ -154,9 +192,8 @@ public static UnirestInstance spawnInstance() {
154192
}
155193

156194
/**
157-
* return the primary UnirestInstance.
158-
*
159-
* @return a new UnirestInstance
195+
* Return the shared primary {@link UnirestInstance}.
196+
* @return the primary instance
160197
*/
161198
public static UnirestInstance primaryInstance() {
162199
return primaryInstance;

‎unirest/src/main/java/kong/unirest/core/UnirestInstance.java‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,11 @@ public HttpRequestWithBody post(String url) {
102102
return new HttpRequestBody(config, HttpMethod.POST, url);
103103
}
104104

105+
/**
106+
* Start a QUERY HttpRequest from this instance.
107+
* @param url the endpoint to access. Can include placeholders for path params using curly braces {}
108+
* @return a HttpRequest builder
109+
*/
105110
public HttpRequestWithBody query(String url) {
106111
return new HttpRequestBody(config, HttpMethod.QUERY, url);
107112
}
@@ -143,6 +148,12 @@ public JsonPatchRequest jsonPatch(String url) {
143148
return new HttpRequestJsonPatch(config, url);
144149
}
145150

151+
/**
152+
* Start an HttpRequest for the given HTTP method.
153+
* @param method the HTTP method name
154+
* @param url the endpoint to access. Can include placeholders for path params using curly braces {}
155+
* @return a HttpRequest builder
156+
*/
146157
public HttpRequestWithBody request(String method, String url) {
147158
return new HttpRequestBody(config, HttpMethod.valueOf(method), url);
148159
}
@@ -157,10 +168,20 @@ public void close() {
157168
reset(true);
158169
}
159170

171+
/**
172+
* Start a WebSocket request from this instance.
173+
* @param url the endpoint to access
174+
* @return a WebSocket request builder
175+
*/
160176
public WebSocketRequest webSocket(String url) {
161177
return new WebSocketRequestImpl(config, url);
162178
}
163179

180+
/**
181+
* Start a Server-Sent Events request from this instance.
182+
* @param url the endpoint to access
183+
* @return an SSE request builder
184+
*/
164185
public SseRequestImpl sse(String url) {
165186
return new SseRequestImpl(config, url);
166187
}

0 commit comments

Comments
 (0)