com.jsunsoft.http.ResponseHandler Maven / Gradle / Ivy
Show all versions of http-request Show documentation
/*
* Copyright (c) 2021. Benik Arakelyan
*
* 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 com.jsunsoft.http;
import com.jsunsoft.http.annotations.Beta;
import org.apache.hc.core5.http.ContentType;
import org.apache.hc.core5.http.Header;
import java.net.URI;
import java.util.NoSuchElementException;
import java.util.Optional;
import java.util.function.Consumer;
import java.util.function.Function;
import java.util.function.Predicate;
import java.util.function.Supplier;
/**
* ResponseHandler objects are immutable they can be shared.
*
* The instance which contains converted response content and provide a lot of methods to manipulation and checking.
*
* @param Type of converted content from response
*/
public interface ResponseHandler {
/**
* @return {@code true} If content is present else {@code false}
*/
boolean hasContent();
/**
* @return {@code true} If hasn't content else {@code false}
*/
default boolean hasNotContent() {
return !hasContent();
}
/**
* @return the status code
*
* @deprecated use {@link #getCode()} instead.
*/
@Deprecated
default int getStatusCode() {
return getCode();
}
/**
* Obtains the code of this response message.
*
* @return the status code
*/
int getCode();
/**
* @param defaultValue value to return if content isn't present
*
* @return Deserialized Content from response. If content isn't present returns defaultValue.
*
* @throws UnsupportedOperationException if generic type is a Void
*/
T orElse(T defaultValue);
/**
* @param defaultValue value to return if status code is success and hasn't body
*
* @return Deserialized Content from response. If hasn't body returns defaultValue.
*
* @throws UnexpectedStatusCodeException If status code is not success
* @throws UnsupportedOperationException if generic type is a Void
*/
T orElseThrow(T defaultValue);
/**
* @param exceptionFunction Instance of type {@link Function} by parameter this which returns exception to throw if status code isn't success.
* @param Type of the exception to be thrown
*
* @return Deserialized content from response. If hasn't body returns {@code null}.
*
* @throws X If status code isn't success.
*/
T orThrow(Function, X> exceptionFunction) throws X;
/**
* @param defaultValue Value to return if content is {@code null}
* @param exceptionFunction Instance of type {@link Function} by parameter this which returns exception to throw if status code isn't success.
* @param Type of the exception to be thrown
*
* @return Deserialized content from response. If hasn't body returns {@code defaultValue}.
*
* @throws X If status code isn't success.
*/
T orThrow(T defaultValue, Function, X> exceptionFunction) throws X;
/**
* @param exceptionSupplier Instance of type {@link Supplier} which returns exception to throw if status code isn't success.
* @param Type of the exception to be thrown
*
* @return Deserialized content from response. If hasn't body returns {@code null}.
*
* @throws X If status code isn't success.
*/
T getOrThrow(Supplier exceptionSupplier) throws X;
/**
* @param defaultValue Value to return if content is {@code null}
* @param exceptionSupplier Instance of type {@link Supplier} which returns exception to throw if status code isn't success.
* @param Type of the exception to be thrown
*
* @return Deserialized content from response. If hasn't body returns {@code defaultValue}.
*
* @throws X If status code isn't success.
*/
T getOrThrow(T defaultValue, Supplier exceptionSupplier) throws X;
/**
* @return Content from response. Returns null if hasn't body
*
* @throws UnexpectedStatusCodeException If response code is not success
* @throws UnsupportedOperationException if generic type is a Void
*/
T orElseThrow();
/**
* Strongly recommend call get method after check content is present.
* For example
*
* if(responseHandler.hasContent()){
* responseHandler.get()
* }
*
*
* @return Deserialized content from response.
*
* @throws NoSuchContentException If content is not present
* @throws UnsupportedOperationException if generic type is a Void
* @see ResponseHandler#orElse(Object)
* @see ResponseHandler#getAsOptional()
* @see ResponseHandler#ifHasContent(Consumer)
*/
T get();
/**
* @return Deserialized Content from response as {@link Optional} instance. If content isn't present returns empty {@link Optional} instance.
*
* @throws UnsupportedOperationException if generic type is a Void
*/
Optional getAsOptional();
/**
* @return Deserialized Content from response as {@link Optional}. If content isn't present returns empty {@link Optional}.
*
* @throws UnsupportedOperationException if generic type is a Void
* @throws UnexpectedStatusCodeException If response code is not success
*/
Optional getAsOptionalOrThrow();
/**
* @return Returns the error text if the connection failed but the server sent useful data nonetheless.
*
* @throws NoSuchElementException If error text is not present
* @throws UnsupportedOperationException if generic type is a Void
*/
String getErrorText();
/**
* @return Returns the connection URI
*/
URI getURI();
/**
* @return Content type of response
*/
ContentType getContentType();
/**
* @return Returns true if status code contains [200, 300) else false
*/
boolean isSuccess();
/**
* @return Returns true if status code isn't contains [200, 300) else false
*/
default boolean isNonSuccess() {
return !isSuccess();
}
/**
* If has a content, invoke the specified consumer with the content, otherwise do nothing.
*
* @param consumer block to be executed if has a content
*
* @throws IllegalArgumentException if {@code consumer} is null
*/
void ifHasContent(Consumer consumer);
/**
* If status code is success , invoke the specified consumer with the responseHandler and returns {@code OtherwiseSupport} with ignore else {@code OtherwiseSupport} with not ignore.
*
* @param consumer block to be executed if status code is success.
*
* @return OtherwiseSupport instance to support action otherwise.
*
* @see OtherwiseSupport#otherwise(Consumer)
*/
OtherwiseSupport ifSuccess(Consumer> consumer);
/**
* If status code is not success , invoke the specified consumer with the responseHandler.
*
* @param consumer block to be executed if status code is not success.
*/
void ifNotSuccess(Consumer> consumer);
FilterSupport filter(Predicate> predicate);
boolean containsHeader(String name);
Header[] getHeaders(String name);
Header getFirstHeader(String name);
Header getLastHeader(String name);
/**
* @return all headers
*/
Header[] getHeaders();
@Beta
default String getFirstHeaderValue(String name) {
Header header = getFirstHeader(name);
return header == null ? null : header.getValue();
}
@Beta
default String getLastHeaderValue(String name) {
Header header = getLastHeader(name);
return header == null ? null : header.getValue();
}
}