Merge pull request #13 from LSafer-Agile/master

Created interface 'Catcher'

Author: LSafer

src/main/java/org/cufy/http/client/wrapper/ClientMessageContext.java

@@ -19,6 +19,7 @@
 import org.cufy.http.Message;
 import org.cufy.http.client.ClientEngine;
 import org.cufy.http.concurrent.wrapper.StrategyContext;
+import org.cufy.http.pipeline.Catcher;
 import org.cufy.http.pipeline.Interceptor;
 import org.cufy.http.pipeline.Next;
 import org.cufy.http.pipeline.Pipe;
@@ -100,8 +101,24 @@ default Self connect() {
 	 * @since 0.3.0 ~2022.01.05
 	 */
 	@NotNull
-	@Contract("_->this")
+	@Contract(value = "_->this", mutates = "this")
 	default Self connected(@NotNull Interceptor<ClientResponseContext<E>> interceptor) {
 		return this.intercept(interceptor);
 	}
+
+	/**
+	 * If the connection fails. Execute the given {@code next} function.
+	 * <br>
+	 * This function is an alias for {@link #handle(Catcher)}.
+	 *
+	 * @param catcher the catcher to be used.
+	 * @return this.
+	 * @throws NullPointerException if the given {@code catcher} is null.
+	 * @since 1.0.0 ~2022.01.09
+	 */
+	@NotNull
+	@Contract(value = "_->this", mutates = "this")
+	default Self failed(@NotNull Catcher<ClientResponseContext<E>> catcher) {
+		return this.handle(catcher);
+	}
 }

src/main/java/org/cufy/http/pipeline/Catcher.java

@@ -0,0 +1,70 @@
+/*
+ *	Copyright 2021-2022 Cufy and ProgSpaceSA
+ *
+ *	Licensed under the Apache License, Version 2.0 (the "License");
+ *	you may not use this file except in compliance with the License.
+ *	You may obtain a copy of the License at
+ *
+ *	    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *	Unless required by applicable law or agreed to in writing, software
+ *	distributed under the License is distributed on an "AS IS" BASIS,
+ *	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *	See the License for the specific language governing permissions and
+ *	limitations under the License.
+ */
+package org.cufy.http.pipeline;
+
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * A catcher is another functional interface form of the interface {@link Next} that only
+ * executes when there is an error.
+ *
+ * @param <T> the type of the parameter the pipe accepts.
+ * @author LSafer
+ * @version 1.0.0
+ * @since 1.0.0 ~2022.01.09
+ */
+@FunctionalInterface
+public interface Catcher<T> extends Next<T> {
+	/**
+	 * Has been overridden to redirect to do nothing. Do not invoke it directly nor
+	 * override it.
+	 * <br>
+	 * {@inheritDoc}
+	 *
+	 * @throws Throwable {@inheritDoc}
+	 */
+	@Override
+	@Deprecated
+	default void invoke() {
+	}
+
+	/**
+	 * Has been overridden to redirect to {@link #handle(Throwable)} if there is an error.
+	 * Do not invoke it directly nor override it. Use/override {@link #handle(Throwable)}
+	 * instead.
+	 * <br>
+	 * {@inheritDoc}
+	 *
+	 * @param error {@inheritDoc}
+	 * @throws Throwable {@inheritDoc}
+	 */
+	@Override
+	@Deprecated
+	default void invoke(@Nullable Throwable error) {
+		if (error != null)
+			this.handle(error);
+	}
+
+	/**
+	 * Handle the given {@code error}.
+	 *
+	 * @param error the error to be handled.
+	 * @throws NullPointerException if the given {@code error} is null.
+	 * @since 1.0.0 ~2022.01.09
+	 */
+	void handle(@NotNull Throwable error);
+}

src/main/java/org/cufy/http/pipeline/wrapper/NextWrapper.java

@@ -15,6 +15,7 @@
  */
 package org.cufy.http.pipeline.wrapper;
 
+import org.cufy.http.pipeline.Catcher;
 import org.cufy.http.pipeline.Next;
 import org.jetbrains.annotations.Contract;
 import org.jetbrains.annotations.NotNull;
@@ -34,6 +35,21 @@
 public interface NextWrapper<T, Self extends NextWrapper<T, Self>> {
 	// Next
 
+	/**
+	 * Set the next function to the given {@code catcher}.
+	 *
+	 * @param catcher the catcher to be set.
+	 * @return this.
+	 * @throws NullPointerException if the given {@code catcher} is null.
+	 * @since 1.0.0 ~2022.01.09
+	 */
+	@NotNull
+	@Contract(value = "_->this", mutates = "this")
+	default Self catcher(@NotNull Catcher<T> catcher) {
+		Objects.requireNonNull(catcher, "catcher");
+		return this.next(catcher);
+	}
+
 	/**
 	 * Replace the next function to the result of invoking the given {@code operator} with
 	 * the argument being the previous next function.

src/main/java/org/cufy/http/pipeline/wrapper/PipelineContext.java

@@ -15,10 +15,7 @@
  */
 package org.cufy.http.pipeline.wrapper;
 
-import org.cufy.http.pipeline.Interceptor;
-import org.cufy.http.pipeline.Middleware;
-import org.cufy.http.pipeline.Next;
-import org.cufy.http.pipeline.Pipe;
+import org.cufy.http.pipeline.*;
 import org.jetbrains.annotations.Contract;
 import org.jetbrains.annotations.NotNull;
 
@@ -35,6 +32,33 @@
  */
 public interface PipelineContext<T, Self extends PipelineContext<T, Self>> extends
 		NextWrapper<T, Self>, PipeWrapper<T, Self> {
+	/**
+	 * <h3>After Pipeline</h3>
+	 * Replace the current next function with a new next function from combining the
+	 * current next function and the given {@code catcher} function.
+	 * <br>
+	 * Unlike the pipe, the next function is always the last thing been executed (after
+	 * the pipeline finishes executing). The provided catcher function will be combined
+	 * with the current next function (the current next function first then the function
+	 * provided). When combining two next functions, each function cannot interrupt the
+	 * other (unless an exception is thrown). So, be careful. The next function is
+	 * intended to be for cleanup purposes and exception handling. Do not handle the
+	 * request/response itself in it.
+	 *
+	 * @param catcher the catcher function to be used.
+	 * @return this.
+	 * @throws NullPointerException if the given {@code catcher} is null.
+	 * @since 1.0.0 ~2022.01.09
+	 */
+	@NotNull
+	@Contract(value = "_->this", mutates = "this")
+	default Self handle(@NotNull Catcher<T> catcher) {
+		Objects.requireNonNull(catcher, "catcher");
+		return this.next(n -> {
+			return Next.combine(n, catcher);
+		});
+	}
+
 	/**
 	 * <h3>Right away</h3>
 	 * Inject the given {@code middleware} to this.

src/test/kotlin/org/cufy/http/endpoint/EndpointTest.kt

@@ -58,17 +58,17 @@ object PostUser : Endpoint {
 
     var Req<PostUser>.firstName: String
         get() = json("firstName")?.asString()?.value()
-            ?: error("PostUser.firstName is missing")
+                ?: error("PostUser.firstName is missing")
         set(v) = run { json("firstName", v.toJson()) }
 
     var Req<PostUser>.lastName: String
         get() = json("lastName")?.asString()?.value()
-            ?: error("PostUser.lastName is missing")
+                ?: error("PostUser.lastName is missing")
         set(v) = run { json("lastName", v.toJson()) }
 
     var Req<PostUser>.email: String
         get() = json("email")?.asString()?.value()
-            ?: error("PostUser.email is missing")
+                ?: error("PostUser.email is missing")
         set(v) = run { json("email", v.toJson()) }
 
     // Res
@@ -224,9 +224,11 @@ class EndpointTest {
                     println(deleteRes.body)
                 }
             }
-            .then { error ->
+            .failed {
+                it.printStackTrace()
+            }
+            .then {
                 println("[Finally]")
-                error?.printStackTrace()
             }
             .connect()
     }