You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@causeway.apache.org by ah...@apache.org on 2023/02/28 10:10:52 UTC
[causeway] branch master updated: CAUSEWAY-3222: regen. ref. index
This is an automated email from the ASF dual-hosted git repository.
ahuber pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/causeway.git
The following commit(s) were added to refs/heads/master by this push:
new 9aec521493 CAUSEWAY-3222: regen. ref. index
9aec521493 is described below
commit 9aec521493cf132bb73231c293a6fac06de7b6df
Author: Andi Huber <ah...@apache.org>
AuthorDate: Tue Feb 28 11:10:47 2023 +0100
CAUSEWAY-3222: regen. ref. index
---
.../services/iactnlayer/InteractionService.adoc | 2 +-
.../commons/pages/index/functional/Railway.adoc | 64 +++----
.../pages/index/functional/ThrowingConsumer.adoc | 100 ++++++++++
.../pages/index/functional/ThrowingRunnable.adoc} | 13 +-
.../pages/index/functional/ThrowingSupplier.adoc | 100 ++++++++++
.../commons/pages/index/functional/Try.adoc | 173 +++++++++++++----
.../pages/index/io/DataPeer.adoc} | 12 +-
.../modules/commons/pages/index/io/DataSink.adoc | 37 +++-
.../modules/commons/pages/index/io/DataSource.adoc | 205 +++++++++++++++++++--
.../modules/commons/pages/index/io/FileUtils.adoc | 161 ++++++++++++++++
.../modules/commons/pages/index/io/JaxbUtils.adoc | 33 ----
.../applib/dtos/ScalarValueDtoV2.adoc | 3 +
.../client/ActionParameterListBuilder.adoc | 13 ++
.../index/restfulobjects/client/RestfulClient.adoc | 11 ++
...ntentNegotiationServiceOrgApacheCausewayV2.adoc | 1 -
core/adoc/modules/_overview/pages/about.adoc | 4 +-
16 files changed, 793 insertions(+), 139 deletions(-)
diff --git a/antora/components/refguide-index/modules/applib/pages/index/services/iactnlayer/InteractionService.adoc b/antora/components/refguide-index/modules/applib/pages/index/services/iactnlayer/InteractionService.adoc
index 40ceabc530..f069bd7dd0 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/services/iactnlayer/InteractionService.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/services/iactnlayer/InteractionService.adoc
@@ -7,7 +7,7 @@ This service is used internally by the framework itself, for example when a view
You could think of this as analogous to an `HttpRequest` , or a JPA `EntityManager` or JDO `PersistenceManager` .
-There are two main APIs exposed. One is to _#openInteraction(InteractionContext) open_ a new xref:refguide:applib:index/services/iactnlayer/InteractionLayer.adoc[InteractionLayer] , to be _#closeInteractionLayers() closed later_ . The other is to execute a _Callable_ or _ThrowingRunnable runnable_ within the duration of an xref:refguide:applib:index/services/iactnlayer/InteractionLayer.adoc[InteractionLayer] , wrapping up automatically. This is what is used by _org.apache.causeway.applib [...]
+There are two main APIs exposed. One is to _#openInteraction(InteractionContext) open_ a new xref:refguide:applib:index/services/iactnlayer/InteractionLayer.adoc[InteractionLayer] , to be _#closeInteractionLayers() closed later_ . The other is to execute a _Callable_ or xref:refguide:commons:index/functional/ThrowingRunnable.adoc[ThrowingRunnable] within the duration of an xref:refguide:applib:index/services/iactnlayer/InteractionLayer.adoc[InteractionLayer] , wrapping up automatically. [...]
== API
diff --git a/antora/components/refguide-index/modules/commons/pages/index/functional/Railway.adoc b/antora/components/refguide-index/modules/commons/pages/index/functional/Railway.adoc
index 9aa4d80166..8cb64311ef 100644
--- a/antora/components/refguide-index/modules/commons/pages/index/functional/Railway.adoc
+++ b/antora/components/refguide-index/modules/commons/pages/index/functional/Railway.adoc
@@ -20,12 +20,12 @@ interface Railway<F, S> {
S getSuccessElseFail(Function<F, ? extends Throwable> toThrowable)
Optional<F> getFailure() // <.>
F getFailureElseFail()
- Railway<F, S> ifSuccess(Consumer<S> successConsumer) // <.>
- Railway<F, S> ifFailure(Consumer<F> failureConsumer) // <.>
- Railway<F, R> mapSuccess(Function<S, R> successMapper) // <.>
- Railway<R, S> mapFailure(Function<F, R> failureMapper) // <.>
- R fold(Function<F, R> failureMapper, Function<S, R> successMapper) // <.>
- Railway<F, S> chain(Function<S, Railway<F, S>> chainingFunction) // <.>
+ Railway<F, S> ifSuccess(ThrowingConsumer<S> successConsumer) // <.>
+ Railway<F, S> ifFailure(ThrowingConsumer<F> failureConsumer) // <.>
+ Railway<F, R> mapSuccess(ThrowingFunction<S, R> successMapper) // <.>
+ Railway<R, S> mapFailure(ThrowingFunction<F, R> failureMapper) // <.>
+ R fold(ThrowingFunction<F, R> failureMapper, ThrowingFunction<S, R> successMapper) // <.>
+ Railway<F, S> chain(ThrowingFunction<S, Railway<F, S>> chainingFunction) // <.>
}
----
@@ -39,32 +39,32 @@ Optionally returns the contained _value_ based on presence, that is, if this is
--
Optionally returns the contained _failure_ based on presence, that is, if this is a _Failure_ .
--
-<.> xref:#ifSuccess_Consumer[ifSuccess(Consumer)]
+<.> xref:#ifSuccess_ThrowingConsumer[ifSuccess(ThrowingConsumer)]
+
--
-Peeks into the contained _success_ if this is a _Success_ .
+If this is a _Success_ , peeks into the contained _success_ .
--
-<.> xref:#ifFailure_Consumer[ifFailure(Consumer)]
+<.> xref:#ifFailure_ThrowingConsumer[ifFailure(ThrowingConsumer)]
+
--
-Peeks into the contained _failure_ if this is a _Failure_ .
+If this is a _Failure_ , peeks into the contained _failure_ .
--
-<.> xref:#mapSuccess_Function[mapSuccess(Function)]
+<.> xref:#mapSuccess_ThrowingFunction[mapSuccess(ThrowingFunction)]
+
--
-Maps this xref:refguide:commons:index/functional/Railway.adoc[Railway] to another if this is a _Success_ . Otherwise if this is a _Failure_ acts as identity operator.
+If this is a _Success_ , maps this xref:refguide:commons:index/functional/Railway.adoc[Railway] to another (success). Otherwise if this is a _Failure_ acts as identity operator.
--
-<.> xref:#mapFailure_Function[mapFailure(Function)]
+<.> xref:#mapFailure_ThrowingFunction[mapFailure(ThrowingFunction)]
+
--
Maps this xref:refguide:commons:index/functional/Railway.adoc[Railway] to another if this is a _Failure_ . Otherwise if this is a _Success_ acts as identity operator.
--
-<.> xref:#fold_Function_Function[fold(Function, Function)]
+<.> xref:#fold_ThrowingFunction_ThrowingFunction[fold(ThrowingFunction, ThrowingFunction)]
+
--
-Maps the contained _success_ or _failure_ to a new value of type _R_ using according mapping function _successMapper_ or _failureMapper_ .
+Maps the contained _failure_ or _success_ to a new value of type _R_ using according mapping function _failureMapper_ or _successMapper_ .
--
-<.> xref:#chain_Function[chain(Function)]
+<.> xref:#chain_ThrowingFunction[chain(ThrowingFunction)]
+
--
*Railway Pattern* If this is a _Success_ , returns a new xref:refguide:commons:index/functional/Railway.adoc[Railway] as produced by the chainingFunction, that receives the current success value as input. Otherwise if this is a _Failure_ acts as identity operator and the chainingFunction is not executed.
@@ -82,33 +82,33 @@ Optionally returns the contained _value_ based on presence, that is, if this is
Optionally returns the contained _failure_ based on presence, that is, if this is a _Failure_ .
-[#ifSuccess_Consumer]
-=== ifSuccess(Consumer)
+[#ifSuccess_ThrowingConsumer]
+=== ifSuccess(ThrowingConsumer)
-Peeks into the contained _success_ if this is a _Success_ .
+If this is a _Success_ , peeks into the contained _success_ .
-[#ifFailure_Consumer]
-=== ifFailure(Consumer)
+[#ifFailure_ThrowingConsumer]
+=== ifFailure(ThrowingConsumer)
-Peeks into the contained _failure_ if this is a _Failure_ .
+If this is a _Failure_ , peeks into the contained _failure_ .
-[#mapSuccess_Function]
-=== mapSuccess(Function)
+[#mapSuccess_ThrowingFunction]
+=== mapSuccess(ThrowingFunction)
-Maps this xref:refguide:commons:index/functional/Railway.adoc[Railway] to another if this is a _Success_ . Otherwise if this is a _Failure_ acts as identity operator.
+If this is a _Success_ , maps this xref:refguide:commons:index/functional/Railway.adoc[Railway] to another (success). Otherwise if this is a _Failure_ acts as identity operator.
-[#mapFailure_Function]
-=== mapFailure(Function)
+[#mapFailure_ThrowingFunction]
+=== mapFailure(ThrowingFunction)
Maps this xref:refguide:commons:index/functional/Railway.adoc[Railway] to another if this is a _Failure_ . Otherwise if this is a _Success_ acts as identity operator.
-[#fold_Function_Function]
-=== fold(Function, Function)
+[#fold_ThrowingFunction_ThrowingFunction]
+=== fold(ThrowingFunction, ThrowingFunction)
-Maps the contained _success_ or _failure_ to a new value of type _R_ using according mapping function _successMapper_ or _failureMapper_ .
+Maps the contained _failure_ or _success_ to a new value of type _R_ using according mapping function _failureMapper_ or _successMapper_ .
-[#chain_Function]
-=== chain(Function)
+[#chain_ThrowingFunction]
+=== chain(ThrowingFunction)
*Railway Pattern* If this is a _Success_ , returns a new xref:refguide:commons:index/functional/Railway.adoc[Railway] as produced by the chainingFunction, that receives the current success value as input. Otherwise if this is a _Failure_ acts as identity operator and the chainingFunction is not executed.
diff --git a/antora/components/refguide-index/modules/commons/pages/index/functional/ThrowingConsumer.adoc b/antora/components/refguide-index/modules/commons/pages/index/functional/ThrowingConsumer.adoc
new file mode 100644
index 0000000000..d1470655c9
--- /dev/null
+++ b/antora/components/refguide-index/modules/commons/pages/index/functional/ThrowingConsumer.adoc
@@ -0,0 +1,100 @@
+= ThrowingConsumer
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you 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 ag [...]
+
+A _Consumer_ that allows invocation of code that throws a checked _Exception_ .
+
+== API
+
+[source,java]
+.ThrowingConsumer.java
+----
+interface ThrowingConsumer<T> {
+ void acceptWithException(T t) // <.>
+ void accept(T t) // <.>
+ void accept(T t, BiFunction<String, Exception, RuntimeException> exceptionWrapper) // <.>
+ ThrowingConsumer<T> throwing(BiFunction<String, Exception, RuntimeException> exceptionWrapper) // <.>
+ ThrowingConsumer<T> of(ThrowingConsumer<T> consumer) // <.>
+ ThrowingConsumer<T> of(ThrowingConsumer<T> consumer, BiFunction<String, Exception, RuntimeException> exceptionWrapper) // <.>
+}
+----
+
+<.> xref:#acceptWithException_T[acceptWithException(T)]
++
+--
+Performs this operation on the given argument, possibly throwing a checked exception.
+--
+<.> xref:#accept_T[accept(T)]
++
+--
+Default _Consumer#accept(Object)_ that wraps any thrown checked exceptions (by default in a _RuntimeException_ ).
+--
+<.> xref:#accept_T_BiFunction[accept(T, BiFunction)]
++
+--
+Performs this operation on the given argument, wrapping any thrown checked exceptions using the given _exceptionWrapper_ .
+--
+<.> xref:#throwing_BiFunction[throwing(BiFunction)]
++
+--
+Return a new xref:refguide:commons:index/functional/ThrowingConsumer.adoc[ThrowingConsumer] where the _#accept(Object)_ method wraps any thrown checked exceptions using the given _exceptionWrapper_ .
+--
+<.> xref:#of_ThrowingConsumer[of(ThrowingConsumer)]
++
+--
+Lambda friendly convenience method that can be used to create a xref:refguide:commons:index/functional/ThrowingConsumer.adoc[ThrowingConsumer] where the _#accept(Object)_ method wraps any checked exception thrown by the supplied lambda expression or method reference.
+--
+<.> xref:#of_ThrowingConsumer_BiFunction[of(ThrowingConsumer, BiFunction)]
++
+--
+Lambda friendly convenience method that can be used to create a xref:refguide:commons:index/functional/ThrowingConsumer.adoc[ThrowingConsumer] where the _#accept(Object)_ method wraps any thrown checked exceptions using the given _exceptionWrapper_ .
+--
+
+== Members
+
+[#acceptWithException_T]
+=== acceptWithException(T)
+
+Performs this operation on the given argument, possibly throwing a checked exception.
+
+[#accept_T]
+=== accept(T)
+
+Default _Consumer#accept(Object)_ that wraps any thrown checked exceptions (by default in a _RuntimeException_ ).
+
+[#accept_T_BiFunction]
+=== accept(T, BiFunction)
+
+Performs this operation on the given argument, wrapping any thrown checked exceptions using the given _exceptionWrapper_ .
+
+[#throwing_BiFunction]
+=== throwing(BiFunction)
+
+Return a new xref:refguide:commons:index/functional/ThrowingConsumer.adoc[ThrowingConsumer] where the _#accept(Object)_ method wraps any thrown checked exceptions using the given _exceptionWrapper_ .
+
+[#of_ThrowingConsumer]
+=== of(ThrowingConsumer)
+
+Lambda friendly convenience method that can be used to create a xref:refguide:commons:index/functional/ThrowingConsumer.adoc[ThrowingConsumer] where the _#accept(Object)_ method wraps any checked exception thrown by the supplied lambda expression or method reference.
+
+This method can be especially useful when working with method references. It allows you to easily convert a method that throws a checked exception into an instance compatible with a regular _Consumer_ .
+
+For example:
+
+----
+
+list.forEach(ThrowingConsumer.of(Example::methodThatCanThrowCheckedException));
+----
+
+[#of_ThrowingConsumer_BiFunction]
+=== of(ThrowingConsumer, BiFunction)
+
+Lambda friendly convenience method that can be used to create a xref:refguide:commons:index/functional/ThrowingConsumer.adoc[ThrowingConsumer] where the _#accept(Object)_ method wraps any thrown checked exceptions using the given _exceptionWrapper_ .
+
+This method can be especially useful when working with method references. It allows you to easily convert a method that throws a checked exception into an instance compatible with a regular _Consumer_ .
+
+For example:
+
+----
+
+list.forEach(ThrowingConsumer.of(Example::methodThatCanThrowCheckedException, IllegalStateException::new));
+----
diff --git a/antora/components/refguide-index/modules/applib/pages/index/util/JaxbUtil.adoc b/antora/components/refguide-index/modules/commons/pages/index/functional/ThrowingRunnable.adoc
similarity index 74%
copy from antora/components/refguide-index/modules/applib/pages/index/util/JaxbUtil.adoc
copy to antora/components/refguide-index/modules/commons/pages/index/functional/ThrowingRunnable.adoc
index 4031649c47..169c5ff24c 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/util/JaxbUtil.adoc
+++ b/antora/components/refguide-index/modules/commons/pages/index/functional/ThrowingRunnable.adoc
@@ -1,16 +1,17 @@
-= JaxbUtil
+= ThrowingRunnable
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you 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 ag [...]
-Helper methods for converting _javax.xml.bind.annotation.XmlRootElement_ -annotated class to-and-from XML.
-
-For example usage, seeCauseway addons' publishmq module(non-ASF)
+Similar to a _Runnable_ , except that it can also throw a checked _Exception_ .
== API
[source,java]
-.JaxbUtil.java
+.ThrowingRunnable.java
----
-class JaxbUtil {
+interface ThrowingRunnable {
+ void run()
+ Callable<Void> toCallable(ThrowingRunnable runnable)
+ Try<Void> resultOf(ThrowingRunnable runnable)
}
----
diff --git a/antora/components/refguide-index/modules/commons/pages/index/functional/ThrowingSupplier.adoc b/antora/components/refguide-index/modules/commons/pages/index/functional/ThrowingSupplier.adoc
new file mode 100644
index 0000000000..53d69dc489
--- /dev/null
+++ b/antora/components/refguide-index/modules/commons/pages/index/functional/ThrowingSupplier.adoc
@@ -0,0 +1,100 @@
+= ThrowingSupplier
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you 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 ag [...]
+
+A _Supplier_ that allows invocation of code that throws a checked exception.
+
+== API
+
+[source,java]
+.ThrowingSupplier.java
+----
+interface ThrowingSupplier<T> {
+ T getWithException() // <.>
+ T get() // <.>
+ T get(BiFunction<String, Exception, RuntimeException> exceptionWrapper) // <.>
+ ThrowingSupplier<T> throwing(BiFunction<String, Exception, RuntimeException> exceptionWrapper) // <.>
+ ThrowingSupplier<T> of(ThrowingSupplier<T> supplier) // <.>
+ ThrowingSupplier<T> of(ThrowingSupplier<T> supplier, BiFunction<String, Exception, RuntimeException> exceptionWrapper) // <.>
+}
+----
+
+<.> xref:#getWithException_[getWithException()]
++
+--
+Gets a result, possibly throwing a checked exception.
+--
+<.> xref:#get_[get()]
++
+--
+Default _Supplier#get()_ that wraps any thrown checked exceptions (by default in a _RuntimeException_ ).
+--
+<.> xref:#get_BiFunction[get(BiFunction)]
++
+--
+Gets a result, wrapping any thrown checked exceptions using the given _exceptionWrapper_ .
+--
+<.> xref:#throwing_BiFunction[throwing(BiFunction)]
++
+--
+Return a new xref:refguide:commons:index/functional/ThrowingSupplier.adoc[ThrowingSupplier] where the _#get()_ method wraps any thrown checked exceptions using the given _exceptionWrapper_ .
+--
+<.> xref:#of_ThrowingSupplier[of(ThrowingSupplier)]
++
+--
+Lambda friendly convenience method that can be used to create a xref:refguide:commons:index/functional/ThrowingSupplier.adoc[ThrowingSupplier] where the _#get()_ method wraps any checked exception thrown by the supplied lambda expression or method reference.
+--
+<.> xref:#of_ThrowingSupplier_BiFunction[of(ThrowingSupplier, BiFunction)]
++
+--
+Lambda friendly convenience method that can be used to create xref:refguide:commons:index/functional/ThrowingSupplier.adoc[ThrowingSupplier] where the _#get()_ method wraps any thrown checked exceptions using the given _exceptionWrapper_ .
+--
+
+== Members
+
+[#getWithException_]
+=== getWithException()
+
+Gets a result, possibly throwing a checked exception.
+
+[#get_]
+=== get()
+
+Default _Supplier#get()_ that wraps any thrown checked exceptions (by default in a _RuntimeException_ ).
+
+[#get_BiFunction]
+=== get(BiFunction)
+
+Gets a result, wrapping any thrown checked exceptions using the given _exceptionWrapper_ .
+
+[#throwing_BiFunction]
+=== throwing(BiFunction)
+
+Return a new xref:refguide:commons:index/functional/ThrowingSupplier.adoc[ThrowingSupplier] where the _#get()_ method wraps any thrown checked exceptions using the given _exceptionWrapper_ .
+
+[#of_ThrowingSupplier]
+=== of(ThrowingSupplier)
+
+Lambda friendly convenience method that can be used to create a xref:refguide:commons:index/functional/ThrowingSupplier.adoc[ThrowingSupplier] where the _#get()_ method wraps any checked exception thrown by the supplied lambda expression or method reference.
+
+This method can be especially useful when working with method references. It allows you to easily convert a method that throws a checked exception into an instance compatible with a regular _Supplier_ .
+
+For example:
+
+----
+
+optional.orElseGet(ThrowingSupplier.of(Example::methodThatCanThrowCheckedException));
+----
+
+[#of_ThrowingSupplier_BiFunction]
+=== of(ThrowingSupplier, BiFunction)
+
+Lambda friendly convenience method that can be used to create xref:refguide:commons:index/functional/ThrowingSupplier.adoc[ThrowingSupplier] where the _#get()_ method wraps any thrown checked exceptions using the given _exceptionWrapper_ .
+
+This method can be especially useful when working with method references. It allows you to easily convert a method that throws a checked exception into an instance compatible with a regular _Supplier_ .
+
+For example:
+
+----
+
+optional.orElseGet(ThrowingSupplier.of(Example::methodThatCanThrowCheckedException, IllegalStateException::new));
+----
diff --git a/antora/components/refguide-index/modules/commons/pages/index/functional/Try.adoc b/antora/components/refguide-index/modules/commons/pages/index/functional/Try.adoc
index 4521064253..0190d74975 100644
--- a/antora/components/refguide-index/modules/commons/pages/index/functional/Try.adoc
+++ b/antora/components/refguide-index/modules/commons/pages/index/functional/Try.adoc
@@ -22,18 +22,25 @@ interface Try<T> {
boolean isFailure()
Optional<T> getValue() // <.>
Optional<Throwable> getFailure() // <.>
- Try<T> ifSuccess(Consumer<Optional<T>> valueConsumer) // <.>
- Try<T> ifFailure(Consumer<Throwable> exceptionConsumer) // <.>
+ Try<T> ifSuccess(ThrowingConsumer<Optional<T>> valueConsumer) // <.>
+ Try<T> ifSuccessAsNullable(ThrowingConsumer<T> valueConsumer) // <.>
+ Try<T> ifFailure(ThrowingConsumer<Throwable> exceptionConsumer) // <.>
Try<T> ifFailureFail() // <.>
Try<T> ifAbsentFail() // <.>
- Try<R> mapSuccess(Function<T, R> successMapper) // <.>
- Try<T> mapFailure(UnaryOperator<Throwable> failureMapper) // <.>
+ Try<R> mapSuccess(ThrowingFunction<Optional<T>, R> successMapper) // <.>
+ Try<R> mapSuccessAsNullable(ThrowingFunction<T, R> successMapper) // <.>
+ Try<T> mapFailure(ThrowingFunction<Throwable, Throwable> failureMapper) // <.>
+ Try<T> mapFailureToSuccess(ThrowingFunction<Throwable, T> recoveryMapper) // <.>
Try<T> mapEmptyToFailure() // <.>
- Either<L, R> map(Function<Throwable, L> failureMapper, Function<Optional<T>, R> successMapper) // <.>
- void accept(Consumer<Throwable> failureConsumer, Consumer<Optional<T>> successConsumer) // <.>
- R fold(Function<Throwable, R> failureMapper, Function<Optional<T>, R> successMapper) // <.>
+ Either<L, R> mapToEither(ThrowingFunction<Throwable, L> failureMapper, ThrowingFunction<Optional<T>, R> successMapper) // <.>
+ Try<T> accept(ThrowingConsumer<Throwable> failureConsumer, ThrowingConsumer<Optional<T>> successConsumer) // <.>
+ R fold(ThrowingFunction<Throwable, R> failureMapper, ThrowingFunction<Optional<T>, R> successMapper) // <.>
Try<R> thenCall(Callable<R> callable) // <.>
Try<Void> thenRun(ThrowingRunnable runnable) // <.>
+ Try<R> then(Callable<? extends Try<R>> next) // <.>
+ Try<T> orCall(Callable<T> fallback) // <.>
+ T valueAsNullableElseFail() // <.>
+ T valueAsNonNullElseFail() // <.>
}
----
@@ -52,15 +59,20 @@ Optionally returns the contained _value_ based on presence, that is, if this is
--
Optionally returns the contained _failure_ based on presence, that is, if this is a _Failure_ .
--
-<.> xref:#ifSuccess_Consumer[ifSuccess(Consumer)]
+<.> xref:#ifSuccess_ThrowingConsumer[ifSuccess(ThrowingConsumer)]
+
--
-Peeks into the _value_ if this is a _Success_ .
+If this is a _Success_ , peeks into the _value_ wrapped in an _Optional_ .
--
-<.> xref:#ifFailure_Consumer[ifFailure(Consumer)]
+<.> xref:#ifSuccessAsNullable_ThrowingConsumer[ifSuccessAsNullable(ThrowingConsumer)]
+
--
-Peeks into the _failure_ if this is a _Failure_ .
+If this is a _Success_ peeks into the (null-able) _value_ .
+--
+<.> xref:#ifFailure_ThrowingConsumer[ifFailure(ThrowingConsumer)]
++
+--
+If this is a _Failure_ , peeks into the _failure_ .
--
<.> xref:#ifFailureFail_[ifFailureFail()]
+
@@ -72,32 +84,42 @@ Throws the contained failure if any.
--
Throws _NoSuchElementException_ if _value_ is _null_ .
--
-<.> xref:#mapSuccess_Function[mapSuccess(Function)]
+<.> xref:#mapSuccess_ThrowingFunction[mapSuccess(ThrowingFunction)]
++
+--
+Maps this xref:refguide:commons:index/functional/Try.adoc[Try] to another if this is a _Success_ , passing the _value_ wrapped in an _Optional_ . Otherwise if this is a _Failure_ acts as identity operator.
+--
+<.> xref:#mapSuccessAsNullable_ThrowingFunction[mapSuccessAsNullable(ThrowingFunction)]
+
--
Maps this xref:refguide:commons:index/functional/Try.adoc[Try] to another if this is a _Success_ . Otherwise if this is a _Failure_ acts as identity operator.
--
-<.> xref:#mapFailure_UnaryOperator[mapFailure(UnaryOperator)]
+<.> xref:#mapFailure_ThrowingFunction[mapFailure(ThrowingFunction)]
+
--
-Maps this xref:refguide:commons:index/functional/Try.adoc[Try] to another if its a _Failure_ . Otherwise if this is a _Success_ acts as identity operator.
+Maps this xref:refguide:commons:index/functional/Try.adoc[Try] to another if this is a _Failure_ . Otherwise if this is a _Success_ acts as identity operator.
+--
+<.> xref:#mapFailureToSuccess_ThrowingFunction[mapFailureToSuccess(ThrowingFunction)]
++
+--
+Recovers from a failed xref:refguide:commons:index/functional/Try.adoc[Try] if its a _Failure_ . Otherwise if this is a _Success_ acts as identity operator.
--
<.> xref:#mapEmptyToFailure_[mapEmptyToFailure()]
+
--
Maps this xref:refguide:commons:index/functional/Try.adoc[Try] to _Failure_ if this is a _Success_ with an empty _value_ . Otherwise acts as identity operator.
--
-<.> xref:#map_Function_Function[map(Function, Function)]
+<.> xref:#mapToEither_ThrowingFunction_ThrowingFunction[mapToEither(ThrowingFunction, ThrowingFunction)]
+
--
Maps this xref:refguide:commons:index/functional/Try.adoc[Try] to xref:refguide:commons:index/functional/Either.adoc[Either] using according mapping function _successMapper_ or _failureMapper_ .
--
-<.> xref:#accept_Consumer_Consumer[accept(Consumer, Consumer)]
+<.> xref:#accept_ThrowingConsumer_ThrowingConsumer[accept(ThrowingConsumer, ThrowingConsumer)]
+
--
Either consumes the success or the failure.
--
-<.> xref:#fold_Function_Function[fold(Function, Function)]
+<.> xref:#fold_ThrowingFunction_ThrowingFunction[fold(ThrowingFunction, ThrowingFunction)]
+
--
Maps the contained _value_ or _failure_ to a new value of type _R_ using according mapping function _successMapper_ or _failureMapper_ .
@@ -105,12 +127,32 @@ Maps the contained _value_ or _failure_ to a new value of type _R_ using accordi
<.> xref:#thenCall_Callable[thenCall(Callable)]
+
--
-If this is a _Success_ , maps it to a new xref:refguide:commons:index/functional/Try.adoc[Try] based on given _Callable_ . Otherwise if its a _Failure_ acts as identity operator.
+If this is a _Success_ , maps it to a new xref:refguide:commons:index/functional/Try.adoc[Try] based on given _Callable_ . Otherwise if its a _Failure_ , acts as identity operator.
--
<.> xref:#thenRun_ThrowingRunnable[thenRun(ThrowingRunnable)]
+
--
-If this is a _Success_ , maps it to new xref:refguide:commons:index/functional/Try.adoc[Try] based on given _ThrowingRunnable_ . Otherwise if its a _Failure_ acts as identity operator.
+If this is a _Success_ , maps it to a new xref:refguide:commons:index/functional/Try.adoc[Try] based on given xref:refguide:commons:index/functional/ThrowingRunnable.adoc[ThrowingRunnable] . Otherwise if this is a _Failure_ , acts as identity operator.
+--
+<.> xref:#then_Callable[then(Callable)]
++
+--
+If this is a _Success_ , maps it to a new xref:refguide:commons:index/functional/Try.adoc[Try] based on given _Supplier_ . Otherwise if this is a _Failure_ , acts as identity operator.
+--
+<.> xref:#orCall_Callable[orCall(Callable)]
++
+--
+If this is a _Failure_ , maps it to a new xref:refguide:commons:index/functional/Try.adoc[Try] based on given _Callable_ . Otherwise if this is a _Success_ , acts as identity operator.
+--
+<.> xref:#valueAsNullableElseFail_[valueAsNullableElseFail()]
++
+--
+If this is a _Failure_ throws the contained failure, otherwise if this is a _Success_ , returns the success value as null-able.
+--
+<.> xref:#valueAsNonNullElseFail_[valueAsNonNullElseFail()]
++
+--
+If this is a _Failure_ throws the contained failure, otherwise if this is a _Success_ , either returns the success value if it is NOT `null` or throws a _NoSuchElementException_ .
--
== Members
@@ -130,15 +172,26 @@ Optionally returns the contained _value_ based on presence, that is, if this is
Optionally returns the contained _failure_ based on presence, that is, if this is a _Failure_ .
-[#ifSuccess_Consumer]
-=== ifSuccess(Consumer)
+[#ifSuccess_ThrowingConsumer]
+=== ifSuccess(ThrowingConsumer)
+
+If this is a _Success_ , peeks into the _value_ wrapped in an _Optional_ .
+
+If given valueConsumer throws an exception, a failed xref:refguide:commons:index/functional/Try.adoc[Try] is returned.
-Peeks into the _value_ if this is a _Success_ .
+[#ifSuccessAsNullable_ThrowingConsumer]
+=== ifSuccessAsNullable(ThrowingConsumer)
-[#ifFailure_Consumer]
-=== ifFailure(Consumer)
+If this is a _Success_ peeks into the (null-able) _value_ .
-Peeks into the _failure_ if this is a _Failure_ .
+If given valueConsumer throws an exception, a failed xref:refguide:commons:index/functional/Try.adoc[Try] is returned.
+
+[#ifFailure_ThrowingConsumer]
+=== ifFailure(ThrowingConsumer)
+
+If this is a _Failure_ , peeks into the _failure_ .
+
+If given exceptionConsumer throws an exception, a failed xref:refguide:commons:index/functional/Try.adoc[Try] is returned.
[#ifFailureFail_]
=== ifFailureFail()
@@ -150,42 +203,86 @@ Throws the contained failure if any.
Throws _NoSuchElementException_ if _value_ is _null_ .
-[#mapSuccess_Function]
-=== mapSuccess(Function)
+[#mapSuccess_ThrowingFunction]
+=== mapSuccess(ThrowingFunction)
+
+Maps this xref:refguide:commons:index/functional/Try.adoc[Try] to another if this is a _Success_ , passing the _value_ wrapped in an _Optional_ . Otherwise if this is a _Failure_ acts as identity operator.
+
+If given successMapper throws an exception, a failed xref:refguide:commons:index/functional/Try.adoc[Try] is returned.
+
+[#mapSuccessAsNullable_ThrowingFunction]
+=== mapSuccessAsNullable(ThrowingFunction)
Maps this xref:refguide:commons:index/functional/Try.adoc[Try] to another if this is a _Success_ . Otherwise if this is a _Failure_ acts as identity operator.
-[#mapFailure_UnaryOperator]
-=== mapFailure(UnaryOperator)
+If given successMapper throws an exception, a failed xref:refguide:commons:index/functional/Try.adoc[Try] is returned.
+
+[#mapFailure_ThrowingFunction]
+=== mapFailure(ThrowingFunction)
+
+Maps this xref:refguide:commons:index/functional/Try.adoc[Try] to another if this is a _Failure_ . Otherwise if this is a _Success_ acts as identity operator.
+
+If given failureMapper throws an exception, a failed xref:refguide:commons:index/functional/Try.adoc[Try] is returned (hiding the original failure).
+
+[#mapFailureToSuccess_ThrowingFunction]
+=== mapFailureToSuccess(ThrowingFunction)
+
+Recovers from a failed xref:refguide:commons:index/functional/Try.adoc[Try] if its a _Failure_ . Otherwise if this is a _Success_ acts as identity operator.
-Maps this xref:refguide:commons:index/functional/Try.adoc[Try] to another if its a _Failure_ . Otherwise if this is a _Success_ acts as identity operator.
+If given recoveryMapper throws an exception, a failed xref:refguide:commons:index/functional/Try.adoc[Try] is returned.
[#mapEmptyToFailure_]
=== mapEmptyToFailure()
Maps this xref:refguide:commons:index/functional/Try.adoc[Try] to _Failure_ if this is a _Success_ with an empty _value_ . Otherwise acts as identity operator.
-[#map_Function_Function]
-=== map(Function, Function)
+[#mapToEither_ThrowingFunction_ThrowingFunction]
+=== mapToEither(ThrowingFunction, ThrowingFunction)
Maps this xref:refguide:commons:index/functional/Try.adoc[Try] to xref:refguide:commons:index/functional/Either.adoc[Either] using according mapping function _successMapper_ or _failureMapper_ .
-[#accept_Consumer_Consumer]
-=== accept(Consumer, Consumer)
+Any exceptions thrown by given failureMapper or successMapper are propagated without catching.
+
+[#accept_ThrowingConsumer_ThrowingConsumer]
+=== accept(ThrowingConsumer, ThrowingConsumer)
Either consumes the success or the failure.
-[#fold_Function_Function]
-=== fold(Function, Function)
+However, if any of given failureConsumer or successConsumer throws an exception, a failed xref:refguide:commons:index/functional/Try.adoc[Try] is returned.
+
+[#fold_ThrowingFunction_ThrowingFunction]
+=== fold(ThrowingFunction, ThrowingFunction)
Maps the contained _value_ or _failure_ to a new value of type _R_ using according mapping function _successMapper_ or _failureMapper_ .
+Any exceptions thrown by given failureMapper or successMapper are propagated without catching.
+
[#thenCall_Callable]
=== thenCall(Callable)
-If this is a _Success_ , maps it to a new xref:refguide:commons:index/functional/Try.adoc[Try] based on given _Callable_ . Otherwise if its a _Failure_ acts as identity operator.
+If this is a _Success_ , maps it to a new xref:refguide:commons:index/functional/Try.adoc[Try] based on given _Callable_ . Otherwise if its a _Failure_ , acts as identity operator.
[#thenRun_ThrowingRunnable]
=== thenRun(ThrowingRunnable)
-If this is a _Success_ , maps it to new xref:refguide:commons:index/functional/Try.adoc[Try] based on given _ThrowingRunnable_ . Otherwise if its a _Failure_ acts as identity operator.
+If this is a _Success_ , maps it to a new xref:refguide:commons:index/functional/Try.adoc[Try] based on given xref:refguide:commons:index/functional/ThrowingRunnable.adoc[ThrowingRunnable] . Otherwise if this is a _Failure_ , acts as identity operator.
+
+[#then_Callable]
+=== then(Callable)
+
+If this is a _Success_ , maps it to a new xref:refguide:commons:index/functional/Try.adoc[Try] based on given _Supplier_ . Otherwise if this is a _Failure_ , acts as identity operator.
+
+[#orCall_Callable]
+=== orCall(Callable)
+
+If this is a _Failure_ , maps it to a new xref:refguide:commons:index/functional/Try.adoc[Try] based on given _Callable_ . Otherwise if this is a _Success_ , acts as identity operator.
+
+[#valueAsNullableElseFail_]
+=== valueAsNullableElseFail()
+
+If this is a _Failure_ throws the contained failure, otherwise if this is a _Success_ , returns the success value as null-able.
+
+[#valueAsNonNullElseFail_]
+=== valueAsNonNullElseFail()
+
+If this is a _Failure_ throws the contained failure, otherwise if this is a _Success_ , either returns the success value if it is NOT `null` or throws a _NoSuchElementException_ .
diff --git a/antora/components/refguide-index/modules/applib/pages/index/util/JaxbUtil.adoc b/antora/components/refguide-index/modules/commons/pages/index/io/DataPeer.adoc
similarity index 78%
rename from antora/components/refguide-index/modules/applib/pages/index/util/JaxbUtil.adoc
rename to antora/components/refguide-index/modules/commons/pages/index/io/DataPeer.adoc
index 4031649c47..3f42db5516 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/util/JaxbUtil.adoc
+++ b/antora/components/refguide-index/modules/commons/pages/index/io/DataPeer.adoc
@@ -1,16 +1,16 @@
-= JaxbUtil
+= DataPeer
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you 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 ag [...]
-Helper methods for converting _javax.xml.bind.annotation.XmlRootElement_ -annotated class to-and-from XML.
-
-For example usage, seeCauseway addons' publishmq module(non-ASF)
+General purpose byte data peer that acts as source and sink at the same time.
== API
[source,java]
-.JaxbUtil.java
+.DataPeer.java
----
-class JaxbUtil {
+interface DataPeer {
+ DataPeer inMemory()
+ DataPeer inMemory(int initialBufferSize)
}
----
diff --git a/antora/components/refguide-index/modules/commons/pages/index/io/DataSink.adoc b/antora/components/refguide-index/modules/commons/pages/index/io/DataSink.adoc
index bfa475ca3c..f54fa8efe7 100644
--- a/antora/components/refguide-index/modules/commons/pages/index/io/DataSink.adoc
+++ b/antora/components/refguide-index/modules/commons/pages/index/io/DataSink.adoc
@@ -9,37 +9,56 @@ General purpose writable byte data sink.
.DataSink.java
----
interface DataSink {
- void writeAll(Function<OutputStream, Try<Void>> producingMapper) // <.>
+ void writeAll(ThrowingConsumer<OutputStream> outputStreamConsumer) // <.>
DataSink none() // <.>
- DataSink ofOutputStreamSupplier(Supplier<OutputStream> outputStreamSupplier)
+ DataSink ofOutputStreamSupplier(ThrowingSupplier<OutputStream> outputStreamSupplier)
+ DataSink ofByteArrayConsumer(ThrowingConsumer<byte[]> byteArrayConsumer, int initalBufferSize)
+ DataSink ofByteArrayConsumer(ThrowingConsumer<byte[]> byteArrayConsumer)
DataSink ofFile(File file)
- DataSink ofByteArrayConsumer(Consumer<byte[]> byteArrayConsumer)
DataSink ofStringConsumer(Consumer<String> stringConsumer, Charset charset)
DataSink ofStringUtf8Consumer(Consumer<String> stringUtf8Consumer)
DataSink ofStringConsumer(StringBuilder stringConsumer, Charset charset)
- DataSink ofStringUtf8Consumer(StringBuilder stringUtf8Consumer)
+ DataSink ofStringUtf8Consumer(StringBuilder stringUtf8Consumer) // <.>
}
----
-<.> xref:#writeAll_Function[writeAll(Function)]
+<.> xref:#writeAll_ThrowingConsumer[writeAll(ThrowingConsumer)]
+
--
-Re-throws any _Exception_ from the mapped xref:refguide:commons:index/functional/Try.adoc[Try] , when the Try is a failure case.
+Offers this xref:refguide:commons:index/io/DataSink.adoc[DataSink] 's _OutputStream_ to the caller, so it can write data to it.
--
<.> xref:#none_[none()]
+
--
Acts as a no-op.
--
+<.> xref:#ofStringUtf8Consumer_StringBuilder[ofStringUtf8Consumer(StringBuilder)]
++
+--
+Example:
+--
== Members
-[#writeAll_Function]
-=== writeAll(Function)
+[#writeAll_ThrowingConsumer]
+=== writeAll(ThrowingConsumer)
-Re-throws any _Exception_ from the mapped xref:refguide:commons:index/functional/Try.adoc[Try] , when the Try is a failure case.
+Offers this xref:refguide:commons:index/io/DataSink.adoc[DataSink] 's _OutputStream_ to the caller, so it can write data to it.
[#none_]
=== none()
Acts as a no-op.
+
+[#ofStringUtf8Consumer_StringBuilder]
+=== ofStringUtf8Consumer(StringBuilder)
+
+Example:
+
+----
+
+var sb = new StringBuffer();
+var dataSink = DataSink.ofStringUtf8Consumer(sb);
+//... write to dataSink
+String result = sb.toString(); // read the buffer
+----
diff --git a/antora/components/refguide-index/modules/commons/pages/index/io/DataSource.adoc b/antora/components/refguide-index/modules/commons/pages/index/io/DataSource.adoc
index 48d9626d24..8ba2d04e6e 100644
--- a/antora/components/refguide-index/modules/commons/pages/index/io/DataSource.adoc
+++ b/antora/components/refguide-index/modules/commons/pages/index/io/DataSource.adoc
@@ -9,26 +9,209 @@ General purpose readable byte data source.
.DataSource.java
----
interface DataSource {
- Try<T> readAll(Function<InputStream, Try<T>> consumingMapper)
- DataSource none() // <.>
- DataSource ofInputStreamSupplier(Supplier<InputStream> inputStreamSupplier)
- DataSource ofResource(Class<?> cls, String resourcePath)
- DataSource ofFile(File file)
- DataSource ofString(String string, Charset charset)
- DataSource ofStringUtf8(String string)
- DataSource ofBytes(byte[] bytes)
+ Try<T> tryReadAll(Function<InputStream, Try<T>> consumingMapper)
+ Try<T> tryReadAndApply(ThrowingFunction<InputStream, T> inputStreamMapper) // <.>
+ Try<Void> tryReadAndAccept(ThrowingConsumer<InputStream> inputStreamConsumer) // <.>
+ Try<byte[]> tryReadAsBytes() // <.>
+ byte[] bytes() // <.>
+ Try<String> tryReadAsString(Charset charset) // <.>
+ Try<String> tryReadAsStringUtf8() // <.>
+ Try<Can<String>> tryReadAsLines(Charset charset) // <.>
+ Try<Can<String>> tryReadAsLinesUtf8() // <.>
+ Try<BufferedImage> tryReadAsImage()
+ Try<Void> tryReadAndWrite(DataSink dataSink, int bufferSize) // <.>
+ void pipe(DataSink dataSink, int bufferSize) // <.>
+ DataSource empty() // <.>
+ DataSource ofInputStreamSupplier(ThrowingSupplier<InputStream> inputStreamSupplier) // <.>
+ DataSource ofResource(Class<?> cls, String resourcePath) // <.>
+ DataSource ofFile(File file) // <.>
+ DataSource ofString(String string, Charset charset) // <.>
+ DataSource ofStringUtf8(String string) // <.>
+ DataSource ofBytes(byte[] bytes) // <.>
}
----
-<.> xref:#none_[none()]
+<.> xref:#tryReadAndApply_ThrowingFunction[tryReadAndApply(ThrowingFunction)]
++
+--
+Passes an _InputStream_ to given _Function_ for application.
+--
+<.> xref:#tryReadAndAccept_ThrowingConsumer[tryReadAndAccept(ThrowingConsumer)]
++
+--
+Passes an _InputStream_ to given _Consumer_ for consumption.
+--
+<.> xref:#tryReadAsBytes_[tryReadAsBytes()]
++
+--
+Reads from this DataSource into a String using given charset encoding.
+--
+<.> xref:#bytes_[bytes()]
++
+--
+Shortcut for _tryReadAsBytes().valueAsNonNullElseFail()_ .
+--
+<.> xref:#tryReadAsString_Charset[tryReadAsString(Charset)]
++
+--
+Reads from this DataSource into a String using given charset encoding.
+--
+<.> xref:#tryReadAsStringUtf8_[tryReadAsStringUtf8()]
++
+--
+Reads from this DataSource into a String using UTF-8 encoding.
+--
+<.> xref:#tryReadAsLines_Charset[tryReadAsLines(Charset)]
++
+--
+Reads from this DataSource all lines using given charset encoding.
+--
+<.> xref:#tryReadAsLinesUtf8_[tryReadAsLinesUtf8()]
++
+--
+Reads from this DataSource all lines using UTF-8 encoding.
+--
+<.> xref:#tryReadAndWrite_DataSink_int[tryReadAndWrite(DataSink, int)]
++
+--
+Acts as a pipe, reading from this xref:refguide:commons:index/io/DataSource.adoc[DataSource] and writing to given xref:refguide:commons:index/io/DataSink.adoc[DataSink] , using given bufferSize for the underlying byte data junks.
+--
+<.> xref:#pipe_DataSink_int[pipe(DataSink, int)]
++
+--
+Acts as a pipe, reading from this xref:refguide:commons:index/io/DataSource.adoc[DataSource] and writing to given xref:refguide:commons:index/io/DataSink.adoc[DataSink] , using given bufferSize for the underlying byte data junks.
+--
+<.> xref:#empty_[empty()]
+
--
Acts as a no-op.
--
+<.> xref:#ofInputStreamSupplier_ThrowingSupplier[ofInputStreamSupplier(ThrowingSupplier)]
++
+--
+Creates a xref:refguide:commons:index/io/DataSource.adoc[DataSource] for given InputStream Supplier.
+--
+<.> xref:#ofResource_Class_String[ofResource(Class, String)]
++
+--
+Creates a xref:refguide:commons:index/io/DataSource.adoc[DataSource] for given resource path relative to _Class_ .
+--
+<.> xref:#ofFile_File[ofFile(File)]
++
+--
+Creates a xref:refguide:commons:index/io/DataSource.adoc[DataSource] for given _File_ . If `null` , an 'empty' DataSource is returned.
+--
+<.> xref:#ofString_String_Charset[ofString(String, Charset)]
++
+--
+Creates a xref:refguide:commons:index/io/DataSource.adoc[DataSource] for given _String_ . If `null` or empty, an 'empty' DataSource is returned.
+--
+<.> xref:#ofStringUtf8_String[ofStringUtf8(String)]
++
+--
+Creates a xref:refguide:commons:index/io/DataSource.adoc[DataSource] for given _String_ . If `null` or empty, an 'empty' DataSource is returned.
+--
+<.> xref:#ofBytes_byte[ofBytes(byte)]
++
+--
+Creates a xref:refguide:commons:index/io/DataSource.adoc[DataSource] for given byte array. If `null` or empty, an 'empty' DataSource is returned.
+--
== Members
-[#none_]
-=== none()
+[#tryReadAndApply_ThrowingFunction]
+=== tryReadAndApply(ThrowingFunction)
+
+Passes an _InputStream_ to given _Function_ for application.
+
+[#tryReadAndAccept_ThrowingConsumer]
+=== tryReadAndAccept(ThrowingConsumer)
+
+Passes an _InputStream_ to given _Consumer_ for consumption.
+
+[#tryReadAsBytes_]
+=== tryReadAsBytes()
+
+Reads from this DataSource into a String using given charset encoding.
+
+If the underlying _InputStream_ is null a success xref:refguide:commons:index/functional/Try.adoc[Try] is returned, containing a null value.
+
+[#bytes_]
+=== bytes()
+
+Shortcut for _tryReadAsBytes().valueAsNonNullElseFail()_ .
+
+[#tryReadAsString_Charset]
+=== tryReadAsString(Charset)
+
+Reads from this DataSource into a String using given charset encoding.
+
+If the underlying _InputStream_ is null a success xref:refguide:commons:index/functional/Try.adoc[Try] is returned, containing a null value.
+
+[#tryReadAsStringUtf8_]
+=== tryReadAsStringUtf8()
+
+Reads from this DataSource into a String using UTF-8 encoding.
+
+If the underlying _InputStream_ is null a success xref:refguide:commons:index/functional/Try.adoc[Try] is returned, containing a null value.
+
+[#tryReadAsLines_Charset]
+=== tryReadAsLines(Charset)
+
+Reads from this DataSource all lines using given charset encoding.
+
+If the underlying _InputStream_ is null a success xref:refguide:commons:index/functional/Try.adoc[Try] is returned, containing a null value.
+
+[#tryReadAsLinesUtf8_]
+=== tryReadAsLinesUtf8()
+
+Reads from this DataSource all lines using UTF-8 encoding.
+
+If the underlying _InputStream_ is null a success xref:refguide:commons:index/functional/Try.adoc[Try] is returned, containing a null value.
+
+[#tryReadAndWrite_DataSink_int]
+=== tryReadAndWrite(DataSink, int)
+
+Acts as a pipe, reading from this xref:refguide:commons:index/io/DataSource.adoc[DataSource] and writing to given xref:refguide:commons:index/io/DataSink.adoc[DataSink] , using given bufferSize for the underlying byte data junks.
+
+[#pipe_DataSink_int]
+=== pipe(DataSink, int)
+
+Acts as a pipe, reading from this xref:refguide:commons:index/io/DataSource.adoc[DataSource] and writing to given xref:refguide:commons:index/io/DataSink.adoc[DataSink] , using given bufferSize for the underlying byte data junks.
+
+Throws if the write failed.
+
+[#empty_]
+=== empty()
Acts as a no-op.
+
+[#ofInputStreamSupplier_ThrowingSupplier]
+=== ofInputStreamSupplier(ThrowingSupplier)
+
+Creates a xref:refguide:commons:index/io/DataSource.adoc[DataSource] for given InputStream Supplier.
+
+[#ofResource_Class_String]
+=== ofResource(Class, String)
+
+Creates a xref:refguide:commons:index/io/DataSource.adoc[DataSource] for given resource path relative to _Class_ .
+
+[#ofFile_File]
+=== ofFile(File)
+
+Creates a xref:refguide:commons:index/io/DataSource.adoc[DataSource] for given _File_ . If `null` , an 'empty' DataSource is returned.
+
+[#ofString_String_Charset]
+=== ofString(String, Charset)
+
+Creates a xref:refguide:commons:index/io/DataSource.adoc[DataSource] for given _String_ . If `null` or empty, an 'empty' DataSource is returned.
+
+[#ofStringUtf8_String]
+=== ofStringUtf8(String)
+
+Creates a xref:refguide:commons:index/io/DataSource.adoc[DataSource] for given _String_ . If `null` or empty, an 'empty' DataSource is returned.
+
+[#ofBytes_byte]
+=== ofBytes(byte)
+
+Creates a xref:refguide:commons:index/io/DataSource.adoc[DataSource] for given byte array. If `null` or empty, an 'empty' DataSource is returned.
diff --git a/antora/components/refguide-index/modules/commons/pages/index/io/FileUtils.adoc b/antora/components/refguide-index/modules/commons/pages/index/io/FileUtils.adoc
new file mode 100644
index 0000000000..01dcd5d47e
--- /dev/null
+++ b/antora/components/refguide-index/modules/commons/pages/index/io/FileUtils.adoc
@@ -0,0 +1,161 @@
+= FileUtils
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you 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 ag [...]
+
+Utilities related to the _Java_ _File_ type.
+
+== API
+
+[source,java]
+.FileUtils.java
+----
+class FileUtils {
+ Try<T> tryReadAndApply(File file, ThrowingFunction<InputStream, T> inputStreamMapper) // <.>
+ Try<Void> tryReadAndAccept(File file, ThrowingConsumer<InputStream> inputStreamConsumer) // <.>
+ Set<File> searchFiles(File dir, Predicate<File> dirFilter, Predicate<File> fileFilter) // <.>
+ void searchFiles(File dir, Predicate<File> dirFilter, Predicate<File> fileFilter, Consumer<File> onFileFound) // <.>
+ Optional<String> canonicalPath(File file) // <.>
+ String toRelativePath(String commonPath, String absolutePath) // <.>
+ void deleteFile(File file) // <.>
+ boolean deleteDirectory(File directoryToBeDeleted)
+ File tempDir(String name) // <.>
+ String realtiveFileName(File root, File file)
+ Function<File, String> realtiveFileName(File root)
+ File makeDir(File directory) // <.>
+ Optional<File> existingFile(File file) // <.>
+ File existingFileElseFail(File file) // <.>
+ Optional<File> existingDirectory(File file) // <.>
+ File existingDirectoryElseFail(File file) // <.>
+ void copy(File from, File to) // <.>
+}
+----
+
+<.> xref:#tryReadAndApply_File_ThrowingFunction[tryReadAndApply(File, ThrowingFunction)]
++
+--
+Opens an _InputStream_ for give _File_ and passes it to given _Function_ for application, then finally closes it.
+--
+<.> xref:#tryReadAndAccept_File_ThrowingConsumer[tryReadAndAccept(File, ThrowingConsumer)]
++
+--
+Opens an _InputStream_ for give _File_ and passes it to given _Consumer_ for consumption, then finally closes it.
+--
+<.> xref:#searchFiles_File_Predicate_Predicate[searchFiles(File, Predicate, Predicate)]
++
+--
+Recursive file search, starting at _dir_ , going deeper based on predicate _dirFilter_ , collecting files (not directories) based on predicate _fileFilter_ .
+--
+<.> xref:#searchFiles_File_Predicate_Predicate_Consumer[searchFiles(File, Predicate, Predicate, Consumer)]
++
+--
+Recursive file search, starting at _dir_ , going deeper based on predicate _dirFilter_ , consuming files (not directories) based on predicate _fileFilter_ .
+--
+<.> xref:#canonicalPath_File[canonicalPath(File)]
+<.> xref:#toRelativePath_String_String[toRelativePath(String, String)]
+<.> xref:#deleteFile_File[deleteFile(File)]
++
+--
+Deletes given _File_ . This operation is ignored if the file is a directory or does not exist.
+--
+<.> xref:#tempDir_String[tempDir(String)]
++
+--
+Returns a temp directory with delete-on-exit policy.
+--
+<.> xref:#makeDir_File[makeDir(File)]
++
+--
+Creates the given directory if it does not already exist. If directory is null acts as a no-op.
+--
+<.> xref:#existingFile_File[existingFile(File)]
++
+--
+Optionally given file, based on whether non-null and exists and is a file (not a directory).
+--
+<.> xref:#existingFileElseFail_File[existingFileElseFail(File)]
++
+--
+Guard given file against null, non-existence and not representing a file.
+--
+<.> xref:#existingDirectory_File[existingDirectory(File)]
++
+--
+Optionally given file, based on whether non-null and exists and is a directory (not a file).
+--
+<.> xref:#existingDirectoryElseFail_File[existingDirectoryElseFail(File)]
++
+--
+Guard given file against null, non-existence and not representing a directory (not a file).
+--
+<.> xref:#copy_File_File[copy(File, File)]
++
+--
+Copy _from_ file _to_ file, replacing existing.
+--
+
+== Members
+
+[#tryReadAndApply_File_ThrowingFunction]
+=== tryReadAndApply(File, ThrowingFunction)
+
+Opens an _InputStream_ for give _File_ and passes it to given _Function_ for application, then finally closes it.
+
+[#tryReadAndAccept_File_ThrowingConsumer]
+=== tryReadAndAccept(File, ThrowingConsumer)
+
+Opens an _InputStream_ for give _File_ and passes it to given _Consumer_ for consumption, then finally closes it.
+
+[#searchFiles_File_Predicate_Predicate]
+=== searchFiles(File, Predicate, Predicate)
+
+Recursive file search, starting at _dir_ , going deeper based on predicate _dirFilter_ , collecting files (not directories) based on predicate _fileFilter_ .
+
+[#searchFiles_File_Predicate_Predicate_Consumer]
+=== searchFiles(File, Predicate, Predicate, Consumer)
+
+Recursive file search, starting at _dir_ , going deeper based on predicate _dirFilter_ , consuming files (not directories) based on predicate _fileFilter_ .
+
+[#canonicalPath_File]
+=== canonicalPath(File)
+
+[#toRelativePath_String_String]
+=== toRelativePath(String, String)
+
+[#deleteFile_File]
+=== deleteFile(File)
+
+Deletes given _File_ . This operation is ignored if the file is a directory or does not exist.
+
+[#tempDir_String]
+=== tempDir(String)
+
+Returns a temp directory with delete-on-exit policy.
+
+[#makeDir_File]
+=== makeDir(File)
+
+Creates the given directory if it does not already exist. If directory is null acts as a no-op.
+
+[#existingFile_File]
+=== existingFile(File)
+
+Optionally given file, based on whether non-null and exists and is a file (not a directory).
+
+[#existingFileElseFail_File]
+=== existingFileElseFail(File)
+
+Guard given file against null, non-existence and not representing a file.
+
+[#existingDirectory_File]
+=== existingDirectory(File)
+
+Optionally given file, based on whether non-null and exists and is a directory (not a file).
+
+[#existingDirectoryElseFail_File]
+=== existingDirectoryElseFail(File)
+
+Guard given file against null, non-existence and not representing a directory (not a file).
+
+[#copy_File_File]
+=== copy(File, File)
+
+Copy _from_ file _to_ file, replacing existing.
diff --git a/antora/components/refguide-index/modules/commons/pages/index/io/JaxbUtils.adoc b/antora/components/refguide-index/modules/commons/pages/index/io/JaxbUtils.adoc
index 882202c84b..8225069359 100644
--- a/antora/components/refguide-index/modules/commons/pages/index/io/JaxbUtils.adoc
+++ b/antora/components/refguide-index/modules/commons/pages/index/io/JaxbUtils.adoc
@@ -9,9 +9,6 @@ Utilities to convert from and to JAXB-XML format.
.JaxbUtils.java
----
class JaxbUtils {
- void setDefaultJAXBContextFactory(Class<?> jaxbContextFactoryClass, boolean force) // <.>
- void useMoxy() // <.>
- void usePlatformDefault() // <.>
DtoMapper<T> mapperFor(Class<T> mappedType, JaxbUtils.JaxbCustomizer... customizers)
Try<T> tryRead(Class<T> mappedType, String stringUtf8, JaxbUtils.JaxbCustomizer... customizers) // <.>
Try<T> tryRead(Class<T> mappedType, DataSource source, JaxbUtils.JaxbCustomizer... customizers) // <.>
@@ -22,21 +19,6 @@ class JaxbUtils {
}
----
-<.> xref:#setDefaultJAXBContextFactory_Class_boolean[setDefaultJAXBContextFactory(Class, boolean)]
-+
---
-uses given factory as default
---
-<.> xref:#useMoxy_[useMoxy()]
-+
---
-uses MOXy
---
-<.> xref:#usePlatformDefault_[usePlatformDefault()]
-+
---
-clears the system property override
---
<.> xref:#tryRead_Class_String_JaxbUtils_JaxbCustomizer[tryRead(Class, String, JaxbUtils_JaxbCustomizer)]
+
--
@@ -65,21 +47,6 @@ not cached
== Members
-[#setDefaultJAXBContextFactory_Class_boolean]
-=== setDefaultJAXBContextFactory(Class, boolean)
-
-uses given factory as default
-
-[#useMoxy_]
-=== useMoxy()
-
-uses MOXy
-
-[#usePlatformDefault_]
-=== usePlatformDefault()
-
-clears the system property override
-
[#tryRead_Class_String_JaxbUtils_JaxbCustomizer]
=== tryRead(Class, String, JaxbUtils_JaxbCustomizer)
diff --git a/antora/components/refguide-index/modules/viewer/pages/index/restfulobjects/applib/dtos/ScalarValueDtoV2.adoc b/antora/components/refguide-index/modules/viewer/pages/index/restfulobjects/applib/dtos/ScalarValueDtoV2.adoc
index 6ef2b364a4..457d004c5e 100644
--- a/antora/components/refguide-index/modules/viewer/pages/index/restfulobjects/applib/dtos/ScalarValueDtoV2.adoc
+++ b/antora/components/refguide-index/modules/viewer/pages/index/restfulobjects/applib/dtos/ScalarValueDtoV2.adoc
@@ -11,7 +11,10 @@ Represents a nullable scalar value, as used by ContentNegotiationServiceOrgApach
class ScalarValueDtoV2 {
ScalarValueDtoV2 forNull(Class<?> type)
ScalarValueDtoV2 forValue(Object value)
+ ScalarValueDtoV2 forValue(T value, ValueSemanticsProvider<T> valueSemantics)
boolean isNull()
+ boolean isValueDecomposition()
+ T getValueAs(Class<T> entityType)
}
----
diff --git a/antora/components/refguide-index/modules/viewer/pages/index/restfulobjects/client/ActionParameterListBuilder.adoc b/antora/components/refguide-index/modules/viewer/pages/index/restfulobjects/client/ActionParameterListBuilder.adoc
index 35e233d875..ed9ed08e35 100644
--- a/antora/components/refguide-index/modules/viewer/pages/index/restfulobjects/client/ActionParameterListBuilder.adoc
+++ b/antora/components/refguide-index/modules/viewer/pages/index/restfulobjects/client/ActionParameterListBuilder.adoc
@@ -15,7 +15,20 @@ class ActionParameterListBuilder {
ActionParameterListBuilder addActionParameter(String parameterName, double parameterValue)
ActionParameterListBuilder addActionParameter(String parameterName, float parameterValue)
ActionParameterListBuilder addActionParameter(String parameterName, boolean parameterValue)
+ ActionParameterListBuilder addActionParameter(String parameterName, ValueDecomposition decomposition) // <.>
Entity<String> build()
}
----
+<.> xref:#addActionParameter_String_ValueDecomposition[addActionParameter(String, ValueDecomposition)]
++
+--
+For transport of _ValueDecomposition_ over REST.
+--
+
+== Members
+
+[#addActionParameter_String_ValueDecomposition]
+=== addActionParameter(String, ValueDecomposition)
+
+For transport of _ValueDecomposition_ over REST.
diff --git a/antora/components/refguide-index/modules/viewer/pages/index/restfulobjects/client/RestfulClient.adoc b/antora/components/refguide-index/modules/viewer/pages/index/restfulobjects/client/RestfulClient.adoc
index a4d4509560..98d7352f0d 100644
--- a/antora/components/refguide-index/modules/viewer/pages/index/restfulobjects/client/RestfulClient.adoc
+++ b/antora/components/refguide-index/modules/viewer/pages/index/restfulobjects/client/RestfulClient.adoc
@@ -52,10 +52,16 @@ class RestfulClient {
ActionParameterListBuilder arguments()
Try<T> digest(Response response, Class<T> entityType)
Try<Can<T>> digestList(Response response, Class<T> entityType, GenericType<List<T>> genericType)
+ Try<T> digestValue(Response response, ValueSemanticsProvider<T> valSemantics) // <.>
URI uri(String path) // <.>
}
----
+<.> xref:#digestValue_Response_ValueSemanticsProvider[digestValue(Response, ValueSemanticsProvider)]
++
+--
+For transport of _ValueDecomposition_ over REST.
+--
<.> xref:#uri_String[uri(String)]
+
--
@@ -64,6 +70,11 @@ Returns an _URI_ constructed from this client's base path plus given relative _p
== Members
+[#digestValue_Response_ValueSemanticsProvider]
+=== digestValue(Response, ValueSemanticsProvider)
+
+For transport of _ValueDecomposition_ over REST.
+
[#uri_String]
=== uri(String)
diff --git a/antora/components/refguide-index/modules/viewer/pages/index/restfulobjects/rendering/service/conneg/ContentNegotiationServiceOrgApacheCausewayV2.adoc b/antora/components/refguide-index/modules/viewer/pages/index/restfulobjects/rendering/service/conneg/ContentNegotiationServiceOrgApacheCausewayV2.adoc
index 3752272516..5b5ca74a94 100644
--- a/antora/components/refguide-index/modules/viewer/pages/index/restfulobjects/rendering/service/conneg/ContentNegotiationServiceOrgApacheCausewayV2.adoc
+++ b/antora/components/refguide-index/modules/viewer/pages/index/restfulobjects/rendering/service/conneg/ContentNegotiationServiceOrgApacheCausewayV2.adoc
@@ -8,7 +8,6 @@
----
class ContentNegotiationServiceOrgApacheCausewayV2 {
public static final String ACCEPT_PROFILE; // <.>
- ContentNegotiationServiceOrgApacheCausewayV2(ContentNegotiationServiceForRestfulObjectsV1_0 restfulObjectsV1_0)
Response.ResponseBuilder buildResponse(IResourceContext resourceContext, ManagedObject objectAdapter) // <.>
Response.ResponseBuilder buildResponse(IResourceContext resourceContext, ManagedProperty objectAndProperty) // <.>
Response.ResponseBuilder buildResponse(IResourceContext resourceContext, ManagedCollection managedCollection) // <.>
diff --git a/core/adoc/modules/_overview/pages/about.adoc b/core/adoc/modules/_overview/pages/about.adoc
index 41155a156c..72ac67d750 100644
--- a/core/adoc/modules/_overview/pages/about.adoc
+++ b/core/adoc/modules/_overview/pages/about.adoc
@@ -1366,7 +1366,7 @@ org.yaml:snakeyaml:jar:<managed> +
.Document Index Entries
****
-xref:refguide:commons:index/collections/Can.adoc[Can], xref:refguide:commons:index/collections/Cardinality.adoc[Cardinality], xref:refguide:commons:index/functional/Either.adoc[Either], xref:refguide:commons:index/functional/Railway.adoc[Railway], xref:refguide:commons:index/functional/Try.adoc[Try], xref:refguide:commons:index/io/DataSink.adoc[DataSink], xref:refguide:commons:index/io/DataSource.adoc[DataSource], xref:refguide:commons:index/io/JaxbUtils.adoc[JaxbUtils], xref:refguide:co [...]
+xref:refguide:commons:index/collections/Can.adoc[Can], xref:refguide:commons:index/collections/Cardinality.adoc[Cardinality], xref:refguide:commons:index/functional/Either.adoc[Either], xref:refguide:commons:index/functional/Railway.adoc[Railway], xref:refguide:commons:index/functional/ThrowingConsumer.adoc[ThrowingConsumer], xref:refguide:commons:index/functional/ThrowingRunnable.adoc[ThrowingRunnable], xref:refguide:commons:index/functional/ThrowingSupplier.adoc[ThrowingSupplier], xref [...]
****
|===
@@ -1558,7 +1558,7 @@ org.apache.causeway.core:causeway-schema:jar:<managed> +
.Document Index Entries
****
-xref:refguide:applib:index/CausewayModuleApplib.adoc[CausewayModuleApplib], xref:refguide:applib:index/CausewayModuleApplibChangeAndExecutionLoggers.adoc[CausewayModuleApplibChangeAndExecutionLoggers], xref:refguide:applib:index/CausewayModuleApplibMixins.adoc[CausewayModuleApplibMixins], xref:refguide:applib:index/Identifier.adoc[Identifier], xref:refguide:applib:index/ViewModel.adoc[ViewModel], xref:refguide:applib:index/annotation/Action.adoc[Action], xref:refguide:applib:index/annota [...]
+xref:refguide:applib:index/CausewayModuleApplib.adoc[CausewayModuleApplib], xref:refguide:applib:index/CausewayModuleApplibChangeAndExecutionLoggers.adoc[CausewayModuleApplibChangeAndExecutionLoggers], xref:refguide:applib:index/CausewayModuleApplibMixins.adoc[CausewayModuleApplibMixins], xref:refguide:applib:index/Identifier.adoc[Identifier], xref:refguide:applib:index/ViewModel.adoc[ViewModel], xref:refguide:applib:index/annotation/Action.adoc[Action], xref:refguide:applib:index/annota [...]
****
|Apache Causeway Core - Code Gen (ByteBuddy)