38 normalize exceptions (#39)

* Change inheritances of exceptions to base one.

* Modify HTTP method names, document throws.

* Fix Jspecify annotations

* Improve documentation

* Change HTTP call methods on services

* Improve error handling doc on interfaces

---------

Co-authored-by: J.C <73438877+1hiking@users.noreply.github.com>

Author: hikingc

src/main/java/io/github/hikingc/matrixsdk/api/Event.java

@@ -20,6 +20,10 @@
 /// All operations in this interface are blocking. Implementations must ensure thread safety and
 /// avoid synchronization blocks that cause carrier thread pinning during network I/O.
 ///
+/// Unless otherwise noted, every method in this interface throws [MatrixIOException] if the request
+/// or response payload cannot be processed, and [MatrixNetworkException] if the server's response
+/// status is not successful.
+///
 /// @see <a href="https://spec.matrix.org/v1.19/client-server-api/#events">Matrix Client-Server API
 ///   Specification for Events</a>
 public interface Event {
@@ -29,12 +33,16 @@ public interface Event {
   /// @param roomId the room ID where the event is.
   /// @param eventId the event ID to retrieve.
   /// @return the full event.
+  /// @throws MatrixIOException when the payload cannot be processed.
+  /// @throws MatrixNetworkException when the response status is not successful.
   ClientEvent getEvent(RoomID roomId, String eventId);
 
   /// Returns currently-joined members
   ///
   /// @param roomId the room ID to fetch data from.
   /// @return a list of room members.
+  /// @throws MatrixIOException when the payload cannot be processed.
+  /// @throws MatrixNetworkException when the response status is not successful.
   RoomMembers getJoinedMembers(RoomID roomId);
 
   /// Returns a filterable list of members and their current membership state in a room.
@@ -47,14 +55,18 @@ public interface Event {
   /// @param notMembership the kind of membership to exclude from the results. Defaults to no
   ///   filtering if unspecified.
   /// @return a list of [ClientEvent]s with the membership information of room members.
+  /// @throws MatrixIOException when the payload cannot be processed.
+  /// @throws MatrixNetworkException when the response status is not successful.
   List<RoomMemberEvent> getMembers(
       RoomID roomId, String at, Membership membership, Membership notMembership);
 
   /// Get the state events for the current state of a room.
   ///
   /// @param roomId the room ID to fetch data from.
-  /// @return the current state of the room
-  List<ClientEvent<?>> getStateEvents(RoomID roomId);
+  /// @return the current state of the room.
+  /// @throws MatrixIOException when the payload cannot be processed.
+  /// @throws MatrixNetworkException when the response status is not successful.
+  List<StateEvent<?>> getStateEvents(RoomID roomId);
 
   /// Looks up the contents of a state event in a room. If the user is joined to the room then the
   /// state is taken from the current state of the room. If the user has left the room then the
@@ -64,6 +76,8 @@ List<RoomMemberEvent> getMembers(
   /// @param eventType the type of state to look up.
   /// @param stateKey the room to look up the state in.
   /// @return the content of the event, including all additional metadata fields.
+  /// @throws MatrixIOException when the payload cannot be processed.
+  /// @throws MatrixNetworkException when the response status is not successful.
   @SuppressWarnings("java:S1452")
   // Caller doesn't know content type ahead of time; polymorphic dispatch via @JsonTypeInfo resolves
   // it
@@ -78,6 +92,7 @@ List<RoomMemberEvent> getMembers(
   /// @param dir the [ChronologicalDirection] in which to search
   /// @return [Messages] with available data.
   /// @throws MatrixIOException when the payload cannot be processed.
+  /// @throws MatrixNetworkException when the response status is not successful.
   /// @throws NullPointerException when the roomId is null.
   Messages getMessages(RoomID roomId, ChronologicalDirection dir, QueryParametersMessages params);
 
@@ -88,6 +103,8 @@ List<RoomMemberEvent> getMembers(
   /// @param dir the [ChronologicalDirection] in which to search
   /// @param timestamp the timestamp to search from, as given in milliseconds since the Unix epoch.
   /// @return [EventMetadata] if an event was found.
+  /// @throws MatrixIOException when the payload cannot be processed.
+  /// @throws MatrixNetworkException when the response status is not successful.
   EventMetadata getEventClosestToTimestamp(
       RoomID roomId, ChronologicalDirection dir, int timestamp);
 
@@ -96,6 +113,8 @@ EventMetadata getEventClosestToTimestamp(
   ///
   /// @param roomId the room ID to fetch data from.
   /// @return [RoomInfo] with current state of the room.
+  /// @throws MatrixIOException when the payload cannot be processed.
+  /// @throws MatrixNetworkException when the response status is not successful.
   RoomInfo getInitialSync(RoomID roomId);
 
   /// Sends a state event.
@@ -106,15 +125,19 @@ EventMetadata getEventClosestToTimestamp(
   /// @return a [String] representing a unique identifier of the event.
   /// @throws MatrixIOException when the payload cannot be processed.
   /// @throws MatrixNetworkException when the response status is not successful.
+  /// @throws MatrixIOException when the payload cannot be processed.
+  /// @throws MatrixNetworkException when the response status is not successful.
   String sendStateEvent(RoomID roomId, String stateKey, StateEventContent content);
 
   /// Sends a message event.
   ///
-  /// @param roomId  the room ID where to send the event.
-  /// @param txnId   for this event. Clients should generate an ID unique across requests with the
+  /// @param roomId the room ID where to send the event.
+  /// @param txnId for this event. Clients should generate an ID unique across requests with the
   ///   same access token; it will be used by the server to ensure idempotency of requests.
   /// @param content of any type of message event.
   /// @return a [String] representing a unique identifier of the event.
+  /// @throws MatrixIOException when the payload cannot be processed.
+  /// @throws MatrixNetworkException when the response status is not successful.
   String sendMessageEvent(RoomID roomId, String txnId, MessageEventContent content);
 
   /// Strips all information out of an event which isn’t critical to the integrity of the

src/main/java/io/github/hikingc/matrixsdk/api/Filter.java

@@ -2,12 +2,18 @@
 
 import io.github.hikingc.matrixsdk.api.filters.FilterDefinition;
 import io.github.hikingc.matrixsdk.api.identifiers.UserID;
+import io.github.hikingc.matrixsdk.exceptions.MatrixIOException;
+import io.github.hikingc.matrixsdk.exceptions.MatrixNetworkException;
 
 /// Core interface for executing protocol operations for filtering.
 ///
 /// All operations in this interface are blocking. Implementations must ensure thread safety and
 /// avoid synchronization blocks that cause carrier thread pinning during network I/O.
 ///
+/// Unless otherwise noted, every method in this interface throws [MatrixIOException] if the request
+/// or response payload cannot be processed, and [MatrixNetworkException] if the server's response
+/// status is not successful.
+///
 /// @see <a href="https://spec.matrix.org/v1.19/client-server-api/#filtering>Matrix Client-Server
 ///   API Specification for Filters</a>
 public interface Filter {
@@ -18,12 +24,16 @@ public interface Filter {
   /// @param userId the [UserID] of whoever is uploading the server.
   /// @param filter the definition of the filter.
   /// @return an ID of the filter definition, usable in supported endpoints.
+  /// @throws MatrixIOException when the payload cannot be processed.
+  /// @throws MatrixNetworkException when the response status is not successful.
   String publishFilter(UserID userId, FilterDefinition filter);
 
   /// Retrieve a [FilterDefinition] from the homeserver.
   ///
   /// @param userId the [UserID] to download a filter for.
   /// @param filterId the filter ID to download.
   /// @return a [FilterDefinition] with all uploaded data.
+  /// @throws MatrixIOException when the payload cannot be processed.
+  /// @throws MatrixNetworkException when the response status is not successful.
   FilterDefinition getFilter(UserID userId, String filterId);
 }

src/main/java/io/github/hikingc/matrixsdk/api/Room.java

@@ -17,15 +17,19 @@
 /// All operations in this interface are blocking. Implementations must ensure thread safety and
 /// avoid synchronization blocks that cause carrier thread pinning during network I/O.
 ///
+/// Unless otherwise noted, every method in this interface throws [MatrixIOException] if the request
+/// or response payload cannot be processed, and [MatrixNetworkException] if the server's response
+/// status is not successful.
+///
 /// @see <a href="https://spec.matrix.org/v1.19/client-server-api/#rooms">Matrix Client-Server API
 ///   Specification for Rooms</a>
 public interface Room {
   /// Creates a room based on the received [InitialRoomConfiguration].
   ///
   /// @param configuration of the room.
   /// @return the created room’s ID.
-  /// @throws MatrixIOException when the payload cannot be processed
-  /// @throws MatrixNetworkException when the response status is not successful
+  /// @throws MatrixIOException when the payload cannot be processed.
+  /// @throws MatrixNetworkException when the response status is not successful.
   String create(InitialRoomConfiguration configuration);
 
   /// Requests the server to resolve a room alias if not possible, the server will use the
@@ -34,18 +38,24 @@ public interface Room {
   /// @param roomAlias the room alias.
   /// @return a [ResolvedAlias] containing the room ids for the requested alias and which servers
   ///   are aware of it.
+  /// @throws MatrixIOException when the payload cannot be processed.
+  /// @throws MatrixNetworkException when the response status is not successful.
   ResolvedAlias resolveAlias(RoomAlias roomAlias);
 
   /// Sets a room alias to a room.
   ///
   /// @param roomAlias a [RoomAlias].
   /// @param roomId the [RoomID] to receive the alias.
+  /// @throws MatrixIOException when the payload cannot be processed.
+  /// @throws MatrixNetworkException when the response status is not successful.
   void setAlias(RoomAlias roomAlias, RoomID roomId);
 
   /// Requests the server to remove a mapping of a room alias to a room id. On success, servers
   /// might modify `m.room.canonical_alias`
   ///
   /// @param roomAlias the [RoomAlias] to remove.
+  /// @throws MatrixIOException when the payload cannot be processed.
+  /// @throws MatrixNetworkException when the response status is not successful.
   void deleteAlias(RoomAlias roomAlias);
 
   /// Requests a list of aliases maintained by the local server for the given room, requires to be
@@ -56,12 +66,16 @@ public interface Room {
   ///
   /// @param roomId the [RoomID] to find local aliases of.
   /// @return a [List] of Room aliases.
+  /// @throws MatrixIOException when the payload cannot be processed.
+  /// @throws MatrixNetworkException when the response status is not successful.
   List<String> getAliasesOfARoom(RoomID roomId);
 
   /// Requests the server to retrieve a list of the user's current rooms (in simple terms whoever
   /// calls this method).
   ///
   /// @return a [List] of the rooms.
+  /// @throws MatrixIOException when the payload cannot be processed.
+  /// @throws MatrixNetworkException when the response status is not successful.
   List<String> getJoinedRooms();
 
   /// Send an invitation to a user to participate in a room, this endpoint requires the caller to be
@@ -80,7 +94,10 @@ public interface Room {
   /// @param request a [JoinRoomRequest] where additional information can be passed.
   /// @param via the servers to attempt to join the room through. One of the servers must be
   ///   participating in the room.
-  /// @return the room ID
+  /// @return the room ID.
+  /// @throws MatrixIOException when the payload cannot be processed.
+  /// @throws MatrixNetworkException when the response status is not successful.
+  /// @throws IllegalArgumentException when using an incorrect [Validator].
   String joinByRoomIdOrAliasIfAllowed(
       Validator roomIdOrAlias, JoinRoomRequest request, List<String> via);
 
@@ -90,7 +107,9 @@ String joinByRoomIdOrAliasIfAllowed(
   /// @param request a [JoinRoomRequest] where additional information can be passed.
   /// @param via the servers to attempt to join the room through. One of the servers must be
   ///   participating in the room.
-  /// @return the room ID
+  /// @return the room ID.
+  /// @throws MatrixIOException when the payload cannot be processed.
+  /// @throws MatrixNetworkException when the response status is not successful.
   String joinByRoomIdIfAllowed(RoomID roomId, JoinRoomRequest request, List<String> via);
 
   /// Knock on a room to ask for permission to join. Acceptance of this request happens out of band.
@@ -100,6 +119,8 @@ String joinByRoomIdOrAliasIfAllowed(
   /// @param via the servers to attempt to join the room through. One of the servers must be
   ///   participating in the room.
   /// @return the room ID of the knocked room.
+  /// @throws MatrixIOException when the payload cannot be processed.
+  /// @throws MatrixNetworkException when the response status is not successful.
   String knockOn(Validator roomIdOrAlias, String reason, List<String> via);
 
   /// Sends a request to leave the room, upon success, you will forget all messages from this room.
@@ -171,8 +192,7 @@ String joinByRoomIdOrAliasIfAllowed(
   /// @param since a pagination token from a previous request, allowing you to get the next or
   ///   previous batch of rooms. The direction of pagination is specified by which token is
   ///   supplied.
-  /// @return a [PublicRoomDirectory] containing [io.github.hikingc.matrixsdk.api.rooms.models.PublishedRoomsChunk] records of the published
-  ///   rooms on the server.
+  /// @return a [PublicRoomDirectory] containing records of the published rooms on the server.
   /// @throws MatrixIOException when the payload cannot be processed.
   /// @throws NullPointerException when the roomId is null.
   /// @see #getPublishedRoomDirectory(PublicRoomRequest)
@@ -182,18 +202,21 @@ String joinByRoomIdOrAliasIfAllowed(
   /// Lists a server’s published room directory.
   ///
   /// @param request a [PublicRoomRequest] with additional filters for the request.
-  /// @return a [PublicRoomDirectory] containing [io.github.hikingc.matrixsdk.api.rooms.models.PublishedRoomsChunk] records of the published
-  ///   rooms on the server.
+  /// @return a [PublicRoomDirectory] containing records of the published rooms on the server.
+  /// @throws MatrixIOException when the payload cannot be processed.
+  /// @throws MatrixNetworkException when the response status is not successful.
   PublicRoomDirectory getPublishedRoomDirectory(PublicRoomRequest request);
 
   /// Retrieves a summary for a room. The response data might yield outdated, partial or even with
   /// no data.
   ///
-  /// @param roomIdOrAlias a [RoomID] or [RoomAlias] of the room to target
+  /// @param roomIdOrAlias a [RoomID] or [RoomAlias] of the room to target.
   /// @param via the servers to attempt to request the summary from when the local server cannot
-  ///   generate it
+  ///   generate it.
   /// @return a [RoomSummary] containing all the information about the room.
   /// @throws MatrixIOException when the payload cannot be processed.
   /// @throws NullPointerException when the roomId is null.
+  /// @throws MatrixIOException when the payload cannot be processed.
+  /// @throws MatrixNetworkException when the response status is not successful.
   RoomSummary getRoomSummary(Validator roomIdOrAlias, List<String> via);
 }

src/main/java/io/github/hikingc/matrixsdk/api/UserData.java

@@ -3,12 +3,18 @@
 import io.github.hikingc.matrixsdk.api.identifiers.UserID;
 import io.github.hikingc.matrixsdk.api.userdata.UserProfile;
 import io.github.hikingc.matrixsdk.api.userdata.UsersFound;
+import io.github.hikingc.matrixsdk.exceptions.MatrixIOException;
+import io.github.hikingc.matrixsdk.exceptions.MatrixNetworkException;
 
 /// Core interface for executing protocol operations against User data.
 ///
 /// All operations in this interface are blocking. Implementations must ensure thread safety and
 /// avoid synchronization blocks that cause carrier thread pinning during network I/O.
 ///
+/// Unless otherwise noted, every method in this interface throws [MatrixIOException] if the request
+/// or response payload cannot be processed, and [MatrixNetworkException] if the server's response
+/// status is not successful.
+///
 /// @see <a href="https://spec.matrix.org/v1.18/client-server-api/#user-data">Matrix Client-Server
 ///   API Specification for User Data</a>
 public interface UserData {
@@ -22,32 +28,42 @@ public interface UserData {
   /// @param limit the maximum number of results.
   /// @param searchTerm the term to search for.
   /// @return all the [UsersFound] by the server.
+  /// @throws MatrixIOException when the payload cannot be processed.
+  /// @throws MatrixNetworkException when the response status is not successful.
   UsersFound searchUsersByTerm(Integer limit, String searchTerm);
 
   /// Get the profile of a user
   ///
-  /// @param userId the [UserID] to profile.
-  /// @return the corresponding [UserProfile].
+  /// @param userId the [UserID] to target.
+  /// @return its [UserProfile].
+  /// @throws MatrixIOException when the payload cannot be processed.
+  /// @throws MatrixNetworkException when the response status is not successful.
   UserProfile getUserProfile(UserID userId);
 
   /// Get the value of a profile field for a user
   ///
-  /// @param userId the [UserID] to profile.
-  /// @param keyName a property field
-  /// @return the value of the key property.
+  /// @param userId the [UserID] to target.
+  /// @param keyName the key name.
+  /// @return the corresponding value of the pair.
+  /// @throws MatrixIOException when the payload cannot be processed.
+  /// @throws MatrixNetworkException when the response status is not successful.
   String getUserProfileByProperty(
       UserID userId, String keyName); // only 1 property allowed so no Map
 
   /// Set or update a profile field for a user.
   ///
-  /// @param userId the [UserID] that'll receive the K-V.
-  /// @param keyName the key to insert in the profile.
-  /// @param valueName the value for the key.
+  /// @param userId the [UserID] to target.
+  /// @param keyName the key name.
+  /// @param valueName the value name.
+  /// @throws MatrixIOException when the payload cannot be processed.
+  /// @throws MatrixNetworkException when the response status is not successful.
   void setUserProfileProperty(UserID userId, String keyName, String valueName);
 
   /// Remove a specific field from a user’s profile.
   ///
-  /// @param userId the [UserID] that'll have his K-V deleted.
-  /// @param keyName the key to be deleted.
+  /// @param userId the [UserID] that'll have a key-value pair removed from its profile.
+  /// @param keyName the key name.
+  /// @throws MatrixIOException when the payload cannot be processed.
+  /// @throws MatrixNetworkException when the response status is not successful.
   void deleteUserProfileProperty(UserID userId, String keyName);
 }

src/main/java/io/github/hikingc/matrixsdk/exceptions/MatrixIOException.java

@@ -1,7 +1,7 @@
 package io.github.hikingc.matrixsdk.exceptions;
 
 /// Thrown to indicate that the code has attempted to process an I/O event to which it has failed.
-public class MatrixIOException extends RuntimeException {
+public class MatrixIOException extends MatrixException {
   /// Constructs a [MatrixIOException] with a message.
   ///
   /// @param message The detail message. The detail message is saved for later retrieval by the

src/main/java/io/github/hikingc/matrixsdk/exceptions/MatrixNetworkException.java

@@ -1,7 +1,7 @@
 package io.github.hikingc.matrixsdk.exceptions;
 
 /// Thrown to indicate that the code has not received a successful HTTP status code.
-public class MatrixNetworkException extends RuntimeException {
+public class MatrixNetworkException extends MatrixException {
   /// Constructs a [MatrixNetworkException] with a message.
   ///
   /// @param message The detail message. The detail message is saved for later retrieval by the