This is an automated email from the ASF dual-hosted git repository.
He-Pin pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pekko-http.git
The following commit(s) were added to refs/heads/main by this push:
new da4342b29 fix: fix javadoc warnings in Java sources across pekko-http
modules (#1119)
da4342b29 is described below
commit da4342b296d11670a69457ee9a574de05dcc5dd7
Author: He-Pin(kerr) <[email protected]>
AuthorDate: Sun Jul 5 16:41:49 2026 +0800
fix: fix javadoc warnings in Java sources across pekko-http modules (#1119)
Motivation:
Running `sbt doc` produces javadoc and compilation warnings in Java
source files across http-core, http, and http-jackson modules:
multi-line {@link} tags, Scala-style [[...]] links, invalid link
syntax, unchecked casts, and deprecated API usage.
Modification:
- Fix invalid {@link} tags in Authority.java, HttpApp.java,
HttpHeader.java, Multipart.java, CustomHeader.java
- Replace Scala-style [[...]] links with {@code}/{@link} in
HttpEntity, HttpMessage, HttpMethod, ServerSentEvent, ContentTypeResolver
- Add javadoc to public methods in Jackson.java (jackson & jackson3)
and example classes
- Add @SuppressWarnings("deprecation") to ContentTypes, Coder,
Jackson, ParserSettingsTest
- Add @SuppressWarnings("unchecked") to AttributeKeys
- Apply javafmt to all modified Java files
Result:
All javadoc and compilation warnings in Java sources are eliminated.
Tests:
Manually verified via `sbt doc` and grep pattern search
References:
Follow-up to #908
---
.../apache/pekko/http/javadsl/model/Authority.java | 4 +-
.../pekko/http/javadsl/model/HttpEntity.java | 10 ++---
.../pekko/http/javadsl/model/HttpHeader.java | 2 +-
.../pekko/http/javadsl/model/HttpMessage.java | 8 ++--
.../pekko/http/javadsl/model/HttpMethod.java | 2 +-
.../apache/pekko/http/javadsl/model/Multipart.java | 13 +++---
.../http/javadsl/model/sse/ServerSentEvent.java | 12 +++---
.../http/javadsl/marshallers/jackson/Jackson.java | 49 ++++++++++++++++++++++
.../http/javadsl/marshallers/jackson3/Jackson.java | 49 ++++++++++++++++++++++
.../http/javadsl/server/examples/petstore/Pet.java | 1 +
.../examples/petstore/PetStoreController.java | 12 ++++++
.../server/examples/petstore/PetStoreExample.java | 13 ++++++
.../server/examples/simple/SimpleServerApp.java | 33 +++++++++++++++
.../examples/simple/SimpleServerHttpHttpsApp.java | 12 ++++++
.../apache/pekko/http/javadsl/server/HttpApp.java | 15 +++----
.../server/directives/ContentTypeResolver.java | 4 +-
16 files changed, 205 insertions(+), 34 deletions(-)
diff --git
a/http-core/src/main/java/org/apache/pekko/http/javadsl/model/Authority.java
b/http-core/src/main/java/org/apache/pekko/http/javadsl/model/Authority.java
index d1aae751b..7ece4e62e 100644
--- a/http-core/src/main/java/org/apache/pekko/http/javadsl/model/Authority.java
+++ b/http-core/src/main/java/org/apache/pekko/http/javadsl/model/Authority.java
@@ -22,8 +22,8 @@ public abstract class Authority {
public abstract Host host();
/**
- * A port number that may be `0` to signal the default port of for scheme.
In general what you
- * want is not the value of this field but {@link Uri::port::}
+ * A port number that may be {@code 0} to signal the default port of for
scheme. In general what
+ * you want is not the value of this field but {@link Uri#port()}
*/
public abstract int port();
diff --git
a/http-core/src/main/java/org/apache/pekko/http/javadsl/model/HttpEntity.java
b/http-core/src/main/java/org/apache/pekko/http/javadsl/model/HttpEntity.java
index a9ecf9c45..8645f0c8a 100644
---
a/http-core/src/main/java/org/apache/pekko/http/javadsl/model/HttpEntity.java
+++
b/http-core/src/main/java/org/apache/pekko/http/javadsl/model/HttpEntity.java
@@ -114,7 +114,7 @@ public interface HttpEntity {
* always keep an upper limit on accepted entities to avoid potential
attackers flooding you with
* too large requests/responses, so use this method with caution.
*
- * <p>See [[withSizeLimit]] for more details.
+ * <p>See {@link #withSizeLimit(long)} for more details.
*/
HttpEntity withoutSizeLimit();
@@ -170,8 +170,8 @@ public interface HttpEntity {
* entity.
*
* <p>Note: It is crucial that entities are either discarded, or consumed by
running the
- * underlying [[org.apache.pekko.stream.javadsl.Source]] as otherwise the
lack of consuming of the
- * data will trigger back-pressure to the underlying TCP connection (as
designed), however
+ * underlying {@code org.apache.pekko.stream.javadsl.Source} as otherwise
the lack of consuming of
+ * the data will trigger back-pressure to the underlying TCP connection (as
designed), however
* possibly leading to an idle-timeout that will close the connection,
instead of just having
* ignored the data.
*
@@ -195,8 +195,8 @@ public interface HttpEntity {
* entity.
*
* <p>Note: It is crucial that entities are either discarded, or consumed by
running the
- * underlying [[org.apache.pekko.stream.javadsl.Source]] as otherwise the
lack of consuming of the
- * data will trigger back-pressure to the underlying TCP connection (as
designed), however
+ * underlying {@code org.apache.pekko.stream.javadsl.Source} as otherwise
the lack of consuming of
+ * the data will trigger back-pressure to the underlying TCP connection (as
designed), however
* possibly leading to an idle-timeout that will close the connection,
instead of just having
* ignored the data.
*
diff --git
a/http-core/src/main/java/org/apache/pekko/http/javadsl/model/HttpHeader.java
b/http-core/src/main/java/org/apache/pekko/http/javadsl/model/HttpHeader.java
index f0d35f53d..752e01ad5 100644
---
a/http-core/src/main/java/org/apache/pekko/http/javadsl/model/HttpHeader.java
+++
b/http-core/src/main/java/org/apache/pekko/http/javadsl/model/HttpHeader.java
@@ -18,7 +18,7 @@ import
org.apache.pekko.http.scaladsl.model.IllegalHeaderException;
/**
* The base type representing Http headers. All actual header values will be
instances of one of the
- * subtypes defined in the `headers` packages. Unknown headers will be
subtypes of {@link
+ * subtypes defined in the {@code headers} packages. Unknown headers will be
subtypes of {@link
* org.apache.pekko.http.javadsl.model.headers.RawHeader}. Not for user
extension.
*/
@DoNotInherit
diff --git
a/http-core/src/main/java/org/apache/pekko/http/javadsl/model/HttpMessage.java
b/http-core/src/main/java/org/apache/pekko/http/javadsl/model/HttpMessage.java
index 0530ef6d7..13a004602 100644
---
a/http-core/src/main/java/org/apache/pekko/http/javadsl/model/HttpMessage.java
+++
b/http-core/src/main/java/org/apache/pekko/http/javadsl/model/HttpMessage.java
@@ -77,8 +77,8 @@ public interface HttpMessage {
* {@code entity} of this HTTP message.
*
* <p>Note: It is crucial that entities are either discarded, or consumed by
running the
- * underlying [[org.apache.pekko.stream.javadsl.Source]] as otherwise the
lack of consuming of the
- * data will trigger back-pressure to the underlying TCP connection (as
designed), however
+ * underlying {@code org.apache.pekko.stream.javadsl.Source} as otherwise
the lack of consuming of
+ * the data will trigger back-pressure to the underlying TCP connection (as
designed), however
* possibly leading to an idle-timeout that will close the connection,
instead of just having
* ignored the data.
*
@@ -102,8 +102,8 @@ public interface HttpMessage {
* {@code entity} of this HTTP message.
*
* <p>Note: It is crucial that entities are either discarded, or consumed by
running the
- * underlying [[org.apache.pekko.stream.javadsl.Source]] as otherwise the
lack of consuming of the
- * data will trigger back-pressure to the underlying TCP connection (as
designed), however
+ * underlying {@code org.apache.pekko.stream.javadsl.Source} as otherwise
the lack of consuming of
+ * the data will trigger back-pressure to the underlying TCP connection (as
designed), however
* possibly leading to an idle-timeout that will close the connection,
instead of just having
* ignored the data.
*
diff --git
a/http-core/src/main/java/org/apache/pekko/http/javadsl/model/HttpMethod.java
b/http-core/src/main/java/org/apache/pekko/http/javadsl/model/HttpMethod.java
index 5373f18ec..efc57aa2f 100644
---
a/http-core/src/main/java/org/apache/pekko/http/javadsl/model/HttpMethod.java
+++
b/http-core/src/main/java/org/apache/pekko/http/javadsl/model/HttpMethod.java
@@ -21,7 +21,7 @@ package org.apache.pekko.http.javadsl.model;
*/
public abstract class HttpMethod {
- /** Returns the name of the method, always equal to [[value]]. */
+ /** Returns the name of the method, always equal to {@link #value()}. */
public final String name() {
return value();
}
diff --git
a/http-core/src/main/java/org/apache/pekko/http/javadsl/model/Multipart.java
b/http-core/src/main/java/org/apache/pekko/http/javadsl/model/Multipart.java
index bc4fa458a..35db1133d 100644
--- a/http-core/src/main/java/org/apache/pekko/http/javadsl/model/Multipart.java
+++ b/http-core/src/main/java/org/apache/pekko/http/javadsl/model/Multipart.java
@@ -26,12 +26,13 @@ import org.apache.pekko.stream.javadsl.Source;
* The model of multipart content for media-types `multipart/\*` (general
multipart content),
* `multipart/form-data` and `multipart/byteranges`.
*
- * <p>The basic modelling classes for these media-types
- * ([[org.apache.pekko.http.scaladsl.Multipart.General]],
[[Multipart.FormData]] and
- * [[org.apache.pekko.http.scaladsl.Multipart.ByteRanges]], respectively) are
stream-based but each
- * have a strict counterpart (namely
[[org.apache.pekko.http.scaladsl.Multipart.General.Strict]],
- * [[org.apache.pekko.http.scaladsl.Multipart.FormData.Strict]] and
- * [[org.apache.pekko.http.scaladsl.Multipart.ByteRanges.Strict]]).
+ * <p>The basic modelling classes for these media-types ({@code
+ * org.apache.pekko.http.scaladsl.Multipart.General}, {@code
Multipart.FormData} and {@code
+ * org.apache.pekko.http.scaladsl.Multipart.ByteRanges}, respectively) are
stream-based but each
+ * have a strict counterpart (namely {@code
+ * org.apache.pekko.http.scaladsl.Multipart.General.Strict}, {@code
+ * org.apache.pekko.http.scaladsl.Multipart.FormData.Strict} and {@code
+ * org.apache.pekko.http.scaladsl.Multipart.ByteRanges.Strict}).
*/
public interface Multipart {
diff --git
a/http-core/src/main/java/org/apache/pekko/http/javadsl/model/sse/ServerSentEvent.java
b/http-core/src/main/java/org/apache/pekko/http/javadsl/model/sse/ServerSentEvent.java
index e3d7826e5..7d3d5d6ee 100644
---
a/http-core/src/main/java/org/apache/pekko/http/javadsl/model/sse/ServerSentEvent.java
+++
b/http-core/src/main/java/org/apache/pekko/http/javadsl/model/sse/ServerSentEvent.java
@@ -32,13 +32,13 @@ public abstract class ServerSentEvent {
private static final Option<Object> intNone = OptionalUtil.scalaNone();
- /** Provides a [[ServerSentEvent]] with empty data which can be used as a
heartbeat */
+ /** Provides a {@link ServerSentEvent} with empty data which can be used as
a heartbeat */
public static ServerSentEvent heartbeat() {
return
org.apache.pekko.http.scaladsl.model.sse.ServerSentEvent.heartbeat();
}
/**
- * Creates a [[ServerSentEvent]].
+ * Creates a {@link ServerSentEvent}.
*
* @param data data, may be empty or span multiple lines
*/
@@ -48,7 +48,7 @@ public abstract class ServerSentEvent {
}
/**
- * Creates a [[ServerSentEvent]].
+ * Creates a {@link ServerSentEvent}.
*
* @param data data, may span multiple lines
* @param type type, must not contain \n or \r
@@ -58,7 +58,7 @@ public abstract class ServerSentEvent {
}
/**
- * Creates a [[ServerSentEvent]].
+ * Creates a {@link ServerSentEvent}.
*
* @param data data, may span multiple lines
* @param type type, must not contain \n or \r
@@ -69,7 +69,7 @@ public abstract class ServerSentEvent {
}
/**
- * Creates a [[ServerSentEvent]].
+ * Creates a {@link ServerSentEvent}.
*
* @param data data, may span multiple lines
* @param retry reconnection delay in milliseconds
@@ -79,7 +79,7 @@ public abstract class ServerSentEvent {
}
/**
- * Creates a [[ServerSentEvent]].
+ * Creates a {@link ServerSentEvent}.
*
* @param data data, may span multiple lines
* @param type optional type, must not contain \n or \r
diff --git
a/http-marshallers-java/http-jackson/src/main/java/org/apache/pekko/http/javadsl/marshallers/jackson/Jackson.java
b/http-marshallers-java/http-jackson/src/main/java/org/apache/pekko/http/javadsl/marshallers/jackson/Jackson.java
index f2e5bd55f..149f12700 100644
---
a/http-marshallers-java/http-jackson/src/main/java/org/apache/pekko/http/javadsl/marshallers/jackson/Jackson.java
+++
b/http-marshallers-java/http-jackson/src/main/java/org/apache/pekko/http/javadsl/marshallers/jackson/Jackson.java
@@ -43,6 +43,12 @@ public class Jackson {
/** INTERNAL API */
public static class JacksonUnmarshallingException extends
ExceptionWithErrorInfo {
+ /**
+ * Creates a new JacksonUnmarshallingException.
+ *
+ * @param expectedType the expected type that was being unmarshalled
+ * @param cause the underlying IO exception
+ */
public JacksonUnmarshallingException(Class<?> expectedType, IOException
cause) {
super(
new ErrorInfo(
@@ -51,29 +57,72 @@ public class Jackson {
}
}
+ /**
+ * Returns a marshaller that converts a value of type {@code T} to a JSON
{@link RequestEntity}
+ * using the default {@link ObjectMapper}.
+ *
+ * @param <T> the type of the value to marshal
+ */
public static <T> Marshaller<T, RequestEntity> marshaller() {
return marshaller(defaultObjectMapper);
}
+ /**
+ * Returns a marshaller that converts a value of type {@code T} to a JSON
{@link RequestEntity}
+ * using the given {@link ObjectMapper}.
+ *
+ * @param <T> the type of the value to marshal
+ * @param mapper the ObjectMapper to use for serialization
+ */
public static <T> Marshaller<T, RequestEntity> marshaller(ObjectMapper
mapper) {
return Marshaller.wrapEntity(
u -> toJSON(mapper, u), Marshaller.stringToEntity(),
MediaTypes.APPLICATION_JSON);
}
+ /**
+ * Returns an unmarshaller that converts a JSON {@link ByteString} to a
value of the given type
+ * using the default {@link ObjectMapper}.
+ *
+ * @param <T> the target type
+ * @param expectedType the class of the target type
+ */
public static <T> Unmarshaller<ByteString, T>
byteStringUnmarshaller(Class<T> expectedType) {
return byteStringUnmarshaller(defaultObjectMapper, expectedType);
}
+ /**
+ * Returns an unmarshaller that converts a JSON {@link HttpEntity} to a
value of the given type
+ * using the default {@link ObjectMapper}.
+ *
+ * @param <T> the target type
+ * @param expectedType the class of the target type
+ */
public static <T> Unmarshaller<HttpEntity, T> unmarshaller(Class<T>
expectedType) {
return unmarshaller(defaultObjectMapper, expectedType);
}
+ /**
+ * Returns an unmarshaller that converts a JSON {@link HttpEntity} to a
value of the given type
+ * using the given {@link ObjectMapper}.
+ *
+ * @param <T> the target type
+ * @param mapper the ObjectMapper to use for deserialization
+ * @param expectedType the class of the target type
+ */
public static <T> Unmarshaller<HttpEntity, T> unmarshaller(
ObjectMapper mapper, Class<T> expectedType) {
return Unmarshaller.forMediaType(MediaTypes.APPLICATION_JSON,
Unmarshaller.entityToString())
.thenApply(s -> fromJSON(mapper, s, expectedType));
}
+ /**
+ * Returns an unmarshaller that converts a JSON {@link ByteString} to a
value of the given type
+ * using the given {@link ObjectMapper}.
+ *
+ * @param <T> the target type
+ * @param mapper the ObjectMapper to use for deserialization
+ * @param expectedType the class of the target type
+ */
public static <T> Unmarshaller<ByteString, T> byteStringUnmarshaller(
ObjectMapper mapper, Class<T> expectedType) {
return Unmarshaller.sync(s -> fromJSON(mapper, s.utf8String(),
expectedType));
diff --git
a/http-marshallers-java/http-jackson3/src/main/java/org/apache/pekko/http/javadsl/marshallers/jackson3/Jackson.java
b/http-marshallers-java/http-jackson3/src/main/java/org/apache/pekko/http/javadsl/marshallers/jackson3/Jackson.java
index dbee58222..f23c10870 100644
---
a/http-marshallers-java/http-jackson3/src/main/java/org/apache/pekko/http/javadsl/marshallers/jackson3/Jackson.java
+++
b/http-marshallers-java/http-jackson3/src/main/java/org/apache/pekko/http/javadsl/marshallers/jackson3/Jackson.java
@@ -40,6 +40,12 @@ public class Jackson {
/** INTERNAL API */
public static class JacksonUnmarshallingException extends
ExceptionWithErrorInfo {
+ /**
+ * Creates a new JacksonUnmarshallingException.
+ *
+ * @param expectedType the expected type that was being unmarshalled
+ * @param cause the underlying exception
+ */
public JacksonUnmarshallingException(Class<?> expectedType, Exception
cause) {
super(
new ErrorInfo(
@@ -48,29 +54,72 @@ public class Jackson {
}
}
+ /**
+ * Returns a marshaller that converts a value of type {@code T} to a JSON
{@link RequestEntity}
+ * using the default {@link ObjectMapper}.
+ *
+ * @param <T> the type of the value to marshal
+ */
public static <T> Marshaller<T, RequestEntity> marshaller() {
return marshaller(defaultObjectMapper);
}
+ /**
+ * Returns a marshaller that converts a value of type {@code T} to a JSON
{@link RequestEntity}
+ * using the given {@link ObjectMapper}.
+ *
+ * @param <T> the type of the value to marshal
+ * @param mapper the ObjectMapper to use for serialization
+ */
public static <T> Marshaller<T, RequestEntity> marshaller(ObjectMapper
mapper) {
return Marshaller.wrapEntity(
u -> toJSON(mapper, u), Marshaller.stringToEntity(),
MediaTypes.APPLICATION_JSON);
}
+ /**
+ * Returns an unmarshaller that converts a JSON {@link ByteString} to a
value of the given type
+ * using the default {@link ObjectMapper}.
+ *
+ * @param <T> the target type
+ * @param expectedType the class of the target type
+ */
public static <T> Unmarshaller<ByteString, T>
byteStringUnmarshaller(Class<T> expectedType) {
return byteStringUnmarshaller(defaultObjectMapper, expectedType);
}
+ /**
+ * Returns an unmarshaller that converts a JSON {@link HttpEntity} to a
value of the given type
+ * using the default {@link ObjectMapper}.
+ *
+ * @param <T> the target type
+ * @param expectedType the class of the target type
+ */
public static <T> Unmarshaller<HttpEntity, T> unmarshaller(Class<T>
expectedType) {
return unmarshaller(defaultObjectMapper, expectedType);
}
+ /**
+ * Returns an unmarshaller that converts a JSON {@link HttpEntity} to a
value of the given type
+ * using the given {@link ObjectMapper}.
+ *
+ * @param <T> the target type
+ * @param mapper the ObjectMapper to use for deserialization
+ * @param expectedType the class of the target type
+ */
public static <T> Unmarshaller<HttpEntity, T> unmarshaller(
ObjectMapper mapper, Class<T> expectedType) {
return Unmarshaller.forMediaType(MediaTypes.APPLICATION_JSON,
Unmarshaller.entityToString())
.thenApply(s -> fromJSON(mapper, s, expectedType));
}
+ /**
+ * Returns an unmarshaller that converts a JSON {@link ByteString} to a
value of the given type
+ * using the given {@link ObjectMapper}.
+ *
+ * @param <T> the target type
+ * @param mapper the ObjectMapper to use for deserialization
+ * @param expectedType the class of the target type
+ */
public static <T> Unmarshaller<ByteString, T> byteStringUnmarshaller(
ObjectMapper mapper, Class<T> expectedType) {
return Unmarshaller.sync(s -> fromJSON(mapper, s.utf8String(),
expectedType));
diff --git
a/http-tests/src/main/java/org/apache/pekko/http/javadsl/server/examples/petstore/Pet.java
b/http-tests/src/main/java/org/apache/pekko/http/javadsl/server/examples/petstore/Pet.java
index 90c0e2782..f7ccc29f4 100644
---
a/http-tests/src/main/java/org/apache/pekko/http/javadsl/server/examples/petstore/Pet.java
+++
b/http-tests/src/main/java/org/apache/pekko/http/javadsl/server/examples/petstore/Pet.java
@@ -15,4 +15,5 @@ package
org.apache.pekko.http.javadsl.server.examples.petstore;
import com.fasterxml.jackson.annotation.JsonProperty;
+/** A simple pet record with an id and name. */
public record Pet(@JsonProperty("id") int id, @JsonProperty("name") String
name) {}
diff --git
a/http-tests/src/main/java/org/apache/pekko/http/javadsl/server/examples/petstore/PetStoreController.java
b/http-tests/src/main/java/org/apache/pekko/http/javadsl/server/examples/petstore/PetStoreController.java
index 39c4d5b64..a27954a92 100644
---
a/http-tests/src/main/java/org/apache/pekko/http/javadsl/server/examples/petstore/PetStoreController.java
+++
b/http-tests/src/main/java/org/apache/pekko/http/javadsl/server/examples/petstore/PetStoreController.java
@@ -19,13 +19,25 @@ import java.util.Map;
import org.apache.pekko.http.javadsl.model.StatusCodes;
import org.apache.pekko.http.javadsl.server.Route;
+/** A simple controller for the pet store example. */
public class PetStoreController {
private Map<Integer, Pet> dataStore;
+ /**
+ * Creates a new PetStoreController.
+ *
+ * @param dataStore the backing data store for pets
+ */
public PetStoreController(Map<Integer, Pet> dataStore) {
this.dataStore = dataStore;
}
+ /**
+ * Deletes a pet by its id.
+ *
+ * @param petId the id of the pet to delete
+ * @return a route completing with OK status
+ */
public Route deletePet(int petId) {
dataStore.remove(petId);
return complete(StatusCodes.OK);
diff --git
a/http-tests/src/main/java/org/apache/pekko/http/javadsl/server/examples/petstore/PetStoreExample.java
b/http-tests/src/main/java/org/apache/pekko/http/javadsl/server/examples/petstore/PetStoreExample.java
index 62c0a850b..acfbf7b0e 100644
---
a/http-tests/src/main/java/org/apache/pekko/http/javadsl/server/examples/petstore/PetStoreExample.java
+++
b/http-tests/src/main/java/org/apache/pekko/http/javadsl/server/examples/petstore/PetStoreExample.java
@@ -35,6 +35,7 @@ import static
org.apache.pekko.http.javadsl.unmarshalling.StringUnmarshallers.IN
// #imports
+/** Example application demonstrating pekko-http routing with Jackson
marshalling. */
public class PetStoreExample {
// #marshall
@@ -52,6 +53,12 @@ public class PetStoreExample {
// #marshall
// #unmarshall
+ /**
+ * Creates the route for the pet store application.
+ *
+ * @param pets the data store for pets
+ * @return the application route
+ */
public static Route appRoute(final Map<Integer, Pet> pets) {
PetStoreController controller = new PetStoreController(pets);
@@ -101,6 +108,12 @@ public class PetStoreExample {
// #unmarshall
+ /**
+ * Main entry point that starts the pet store HTTP server.
+ *
+ * @param args command line arguments (not used)
+ * @throws IOException if an I/O error occurs
+ */
public static void main(String[] args) throws IOException {
Map<Integer, Pet> pets = new ConcurrentHashMap<>();
Pet dog = new Pet(0, "dog");
diff --git
a/http-tests/src/main/java/org/apache/pekko/http/javadsl/server/examples/simple/SimpleServerApp.java
b/http-tests/src/main/java/org/apache/pekko/http/javadsl/server/examples/simple/SimpleServerApp.java
index a3835e3cc..1727bc32a 100644
---
a/http-tests/src/main/java/org/apache/pekko/http/javadsl/server/examples/simple/SimpleServerApp.java
+++
b/http-tests/src/main/java/org/apache/pekko/http/javadsl/server/examples/simple/SimpleServerApp.java
@@ -40,18 +40,39 @@ import
org.apache.pekko.http.javadsl.unmarshalling.StringUnmarshallers;
// #https-http-config
+/** Example application demonstrating pekko-http server with HTTP and HTTPS
support. */
public class SimpleServerApp {
// #https-http-app
+ /**
+ * Multiplies two numbers and returns a route with the result.
+ *
+ * @param x the first number
+ * @param y the second number
+ * @return a route completing with the multiplication result
+ */
public Route multiply(int x, int y) {
int result = x * y;
return complete("%d * %d = %d".formatted(x, y, result));
}
+ /**
+ * Asynchronously multiplies two numbers and returns a future route with the
result.
+ *
+ * @param ctx the executor to use for async computation
+ * @param x the first number
+ * @param y the second number
+ * @return a completion stage of the route
+ */
public CompletionStage<Route> multiplyAsync(Executor ctx, int x, int y) {
return CompletableFuture.supplyAsync(() -> multiply(x, y), ctx);
}
+ /**
+ * Creates the main route for the calculator application.
+ *
+ * @return the application route
+ */
public Route createRoute() {
Route addHandler =
parameter(
@@ -104,6 +125,12 @@ public class SimpleServerApp {
// ** STARTING THE SERVER ** //
+ /**
+ * Main entry point that starts the calculator HTTP server.
+ *
+ * @param args command line arguments (not used)
+ * @throws IOException if an I/O error occurs
+ */
public static void main(String[] args) throws IOException {
final ActorSystem system = ActorSystem.create("SimpleServerApp");
@@ -132,6 +159,12 @@ public class SimpleServerApp {
// #https-http-config
// ** CONFIGURING ADDITIONAL SETTINGS ** //
+ /**
+ * Creates an HTTPS connection context using a PKCS12 keystore.
+ *
+ * @param system the actor system
+ * @return the HTTPS connection context
+ */
public static HttpsConnectionContext createHttpsContext(ActorSystem system) {
try {
// initialise the keystore
diff --git
a/http-tests/src/main/java/org/apache/pekko/http/javadsl/server/examples/simple/SimpleServerHttpHttpsApp.java
b/http-tests/src/main/java/org/apache/pekko/http/javadsl/server/examples/simple/SimpleServerHttpHttpsApp.java
index ddff61dba..03cbd6820 100644
---
a/http-tests/src/main/java/org/apache/pekko/http/javadsl/server/examples/simple/SimpleServerHttpHttpsApp.java
+++
b/http-tests/src/main/java/org/apache/pekko/http/javadsl/server/examples/simple/SimpleServerHttpHttpsApp.java
@@ -21,14 +21,26 @@ import org.apache.pekko.http.javadsl.Http;
import org.apache.pekko.http.javadsl.HttpsConnectionContext;
import org.apache.pekko.http.javadsl.server.Route;
+/** Example application demonstrating running both HTTP and HTTPS servers. */
public class SimpleServerHttpHttpsApp {
+ /**
+ * Creates a simple route that responds with "Hello World!".
+ *
+ * @return the application route
+ */
public Route createRoute() {
return get(() -> complete("Hello World!"));
}
// ** STARTING THE SERVER ** //
+ /**
+ * Main entry point that starts both HTTP and HTTPS servers.
+ *
+ * @param args command line arguments (not used)
+ * @throws IOException if an I/O error occurs
+ */
public static void main(String[] args) throws IOException {
final ActorSystem system = ActorSystem.create("SimpleServerHttpHttpsApp");
diff --git
a/http/src/main/java/org/apache/pekko/http/javadsl/server/HttpApp.java
b/http/src/main/java/org/apache/pekko/http/javadsl/server/HttpApp.java
index 58f57451a..336f470a8 100644
--- a/http/src/main/java/org/apache/pekko/http/javadsl/server/HttpApp.java
+++ b/http/src/main/java/org/apache/pekko/http/javadsl/server/HttpApp.java
@@ -52,8 +52,8 @@ public abstract class HttpApp extends AllDirectives {
}
/**
- * Start a server on the specified host and port, using the provided
[[ActorSystem]] Note that
- * this method is blocking.
+ * Start a server on the specified host and port, using the provided {@link
ActorSystem}. Note
+ * that this method is blocking.
*
* @param system ActorSystem to use for starting the app, if null is passed
in a new default
* ActorSystem will be created instead, which will be terminated when
the server is stopped.
@@ -73,8 +73,8 @@ public abstract class HttpApp extends AllDirectives {
}
/**
- * Start a server on the specified host and port, using the provided
settings and [[ActorSystem]].
- * Note that this method is blocking.
+ * Start a server on the specified host and port, using the provided
settings and {@link
+ * ActorSystem}. Note that this method is blocking.
*
* @param system ActorSystem to use for starting the app, if null is passed
in a new default
* ActorSystem will be created instead, which will be terminated when
the server is stopped.
@@ -85,8 +85,8 @@ public abstract class HttpApp extends AllDirectives {
}
/**
- * Start a server on the specified host and port, using the provided
settings and [[ActorSystem]]
- * if present. Note that this method is blocking. This method may throw an
{@link
+ * Start a server on the specified host and port, using the provided
settings and {@link
+ * ActorSystem} if present. Note that this method is blocking. This method
may throw an {@link
* ExecutionException} or {@link InterruptedException} if the future that
signals that the server
* should shutdown is interrupted or cancelled.
*
@@ -155,7 +155,8 @@ public abstract class HttpApp extends AllDirectives {
/**
* Hook that will be called just after the server termination. Override this
method if you want to
* perform some cleanup actions after the server is stopped. The {@code
failure} parameter
- * contains a {@link Throwable} only if there has been a problem shutting
down the server.
+ * contains a {@link java.lang.Throwable} only if there has been a problem
shutting down the
+ * server.
*/
protected void postServerShutdown(Optional<Throwable> failure, ActorSystem
system) {
systemReference.get().log().info("Shutting down the server");
diff --git
a/http/src/main/java/org/apache/pekko/http/javadsl/server/directives/ContentTypeResolver.java
b/http/src/main/java/org/apache/pekko/http/javadsl/server/directives/ContentTypeResolver.java
index 2076b6982..bd03d20ed 100644
---
a/http/src/main/java/org/apache/pekko/http/javadsl/server/directives/ContentTypeResolver.java
+++
b/http/src/main/java/org/apache/pekko/http/javadsl/server/directives/ContentTypeResolver.java
@@ -16,8 +16,8 @@ package org.apache.pekko.http.javadsl.server.directives;
import org.apache.pekko.http.javadsl.model.ContentType;
/**
- * Implement this interface to provide a custom mapping from a file name to a
- * [[org.apache.pekko.http.javadsl.model.ContentType]].
+ * Implement this interface to provide a custom mapping from a file name to a
{@link
+ * org.apache.pekko.http.javadsl.model.ContentType}.
*/
@FunctionalInterface
public interface ContentTypeResolver {
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
