You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by ah...@apache.org on 2020/01/13 12:10:49 UTC
[isis] branch master updated: ISIS-2262: sync adoc
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/isis.git
The following commit(s) were added to refs/heads/master by this push:
new d89f8b4 ISIS-2262: sync adoc
d89f8b4 is described below
commit d89f8b4783418c6cf5c6522e905cd09953796794
Author: Andi Huber <ah...@apache.org>
AuthorDate: Mon Jan 13 13:10:41 2020 +0100
ISIS-2262: sync adoc
---
.../services/exceprecog/ExceptionRecognizer.java | 103 ++++++------
.../exceprecog/ExceptionRecognizerAbstract.java | 38 ++---
.../exceprecog/ExceptionRecognizerComposite.java | 178 ---------------------
.../exceprecog/ExceptionRecognizerService.java | 43 +++++
4 files changed, 115 insertions(+), 247 deletions(-)
diff --git a/api/applib/src/main/doc/modules/applib-svc/examples/services/exceprecog/ExceptionRecognizer.java b/api/applib/src/main/doc/modules/applib-svc/examples/services/exceprecog/ExceptionRecognizer.java
index f5bacf1..cd5cb0b 100644
--- a/api/applib/src/main/doc/modules/applib-svc/examples/services/exceprecog/ExceptionRecognizer.java
+++ b/api/applib/src/main/doc/modules/applib-svc/examples/services/exceprecog/ExceptionRecognizer.java
@@ -18,10 +18,17 @@
*/
package org.apache.isis.applib.services.exceprecog;
-import javax.annotation.PostConstruct;
-import javax.annotation.PreDestroy;
+import java.util.Optional;
-import org.apache.isis.applib.annotation.Programmatic;
+import javax.annotation.Nullable;
+
+import org.apache.isis.applib.services.i18n.TranslationService;
+
+import lombok.Getter;
+import lombok.NonNull;
+import lombok.RequiredArgsConstructor;
+import lombok.Value;
+import lombok.val;
/**
@@ -35,8 +42,8 @@ import org.apache.isis.applib.annotation.Programmatic;
*
* <p>
* More than one implementation of {@link ExceptionRecognizer} can
- * be registered; they will all be consulted (in the order specified in
- * <tt>isis.properties</tt>) to determine if they recognize the exception.
+ * be registered; they will all be consulted (in the order as specified by the @Order annotation)
+ * to determine if they recognize the exception.
* The message returned by the first service recognizing the exception is
* used.
*
@@ -55,78 +62,82 @@ public interface ExceptionRecognizer {
/**
* (Attempt to) recognize the exception and return a user-friendly
- * message to render instead.
+ * message to render instead.
*
- * @return user-friendly message to render, or <tt>null</tt> otherwise.
- */
- @Programmatic
- public String recognize(Throwable ex);
-
- /**
- * An extension to {@link #recognize(Throwable)} that allows recognized exceptions
- * to be {@link org.apache.isis.applib.services.exceprecog.ExceptionRecognizer.Category categorize}d.
+ * @return optionally a
+ * {@link org.apache.isis.applib.services.exceprecog.ExceptionRecognizer.Recognition recognition} object,
+ * that describes both the
+ * {@link org.apache.isis.applib.services.exceprecog.ExceptionRecognizer.Category category}
+ * and reason that will be included with the user-friendly message.
*/
- @Programmatic
- Recognition recognize2(Throwable ex);
-
- @Programmatic
- @PostConstruct
- public void init();
-
- @Programmatic
- @PreDestroy
- public void shutdown();
+ public Optional<Recognition> recognize(Throwable ex);
+ @RequiredArgsConstructor
enum Category {
/**
* A violation of some declarative constraint (eg uniqueness or referential integrity) was detected.
*/
- CONSTRAINT_VIOLATION,
+ CONSTRAINT_VIOLATION("violation of some declarative constraint"),
/**
* The object to be acted upon cannot be found (404)
*/
- NOT_FOUND,
+ NOT_FOUND("object not found"),
/**
* A concurrency exception, in other words some other user has changed this object.
*/
- CONCURRENCY,
+ CONCURRENCY("concurrent modification"),
/**
* Recognized, but for some other reason... 40x error
*/
- CLIENT_ERROR,
+ CLIENT_ERROR("client side error"),
/**
* 50x error
*/
- SERVER_ERROR,
+ SERVER_ERROR("server side error"),
/**
* Recognized, but uncategorized (typically: a recognizer of the original ExceptionRecognizer API).
*/
- OTHER
+ OTHER("other")
+ ;
+
+ @Getter private final String friendlyName;
+
}
+ @Value
class Recognition {
/**
- * Returns a recognition of the specified type (assuming a non-null reason); else null.
+ * @return optionally a recognition of the specified type, based on a whether given reason is non-null
*/
- public static Recognition of(final Category category, final String reason) {
- return reason != null? new Recognition(category, reason): null;
+ public static Optional<Recognition> of(
+ @Nullable final Category category,
+ @Nullable final String reason) {
+
+ if(reason==null) {
+ return Optional.empty();
+ }
+
+ val nonNullCategory = category!=null? category: Category.OTHER;
+ return Optional.of(new Recognition(nonNullCategory, reason));
}
- private final Category category;
- private final String reason;
-
- public Recognition(final Category category, final String reason) {
- this.category = category;
- this.reason = reason;
- }
-
- public Category getCategory() {
- return category;
- }
+ @NonNull private final Category category;
+ @NonNull private final String reason;
- public String getReason() {
- return reason;
+ public String toMessage(@Nullable TranslationService translationService) {
+
+ val categoryLiteral = translationService!=null
+ ? translationService.translate(
+ ExceptionRecognizer.Category.class.getName(), getCategory().getFriendlyName())
+ : getCategory().getFriendlyName();
+
+ val reasonLiteral = translationService!=null
+ ? translationService.translate(
+ ExceptionRecognizer.Recognition.class.getName(), getReason())
+ : getReason();
+
+ return String.format("[%s]: %s", categoryLiteral, reasonLiteral);
}
}
}
diff --git a/api/applib/src/main/doc/modules/applib-svc/examples/services/exceprecog/ExceptionRecognizerAbstract.java b/api/applib/src/main/doc/modules/applib-svc/examples/services/exceprecog/ExceptionRecognizerAbstract.java
index 1a2c5dc..77433b4 100644
--- a/api/applib/src/main/doc/modules/applib-svc/examples/services/exceprecog/ExceptionRecognizerAbstract.java
+++ b/api/applib/src/main/doc/modules/applib-svc/examples/services/exceprecog/ExceptionRecognizerAbstract.java
@@ -19,11 +19,10 @@
package org.apache.isis.applib.services.exceprecog;
import java.util.Objects;
+import java.util.Optional;
import java.util.function.Function;
import java.util.function.Predicate;
-import javax.annotation.PostConstruct;
-import javax.annotation.PreDestroy;
import javax.inject.Inject;
import org.apache.isis.applib.annotation.Programmatic;
@@ -32,6 +31,8 @@ import org.apache.isis.applib.services.i18n.TranslationService;
import org.apache.isis.core.commons.internal.base._NullSafe;
import org.apache.isis.core.commons.internal.exceptions._Exceptions;
+import lombok.Getter;
+import lombok.Setter;
import lombok.extern.log4j.Log4j2;
/**
@@ -46,6 +47,10 @@ import lombok.extern.log4j.Log4j2;
*/
@Log4j2
public abstract class ExceptionRecognizerAbstract implements ExceptionRecognizer {
+
+ @Inject protected TranslationService translationService;
+
+ @Getter @Setter private boolean disabled = false;
// /**
// * Normally recognized exceptions are not logged (because they are expected and handled).
@@ -116,24 +121,10 @@ public abstract class ExceptionRecognizerAbstract implements ExceptionRecognizer
this(Category.OTHER, predicate);
}
- @Override
- @PostConstruct
- public void init() {
- //FIXME[2039] IsisConfiguration is not accessible from applib, move this abstract class to config?
- // final String prop = properties.get(KEY_LOG_RECOGNIZED_EXCEPTIONS);
- // this.logRecognizedExceptions = Boolean.parseBoolean(prop);
- }
-
- @Override
- @PreDestroy
- public void shutdown() {
- }
// //////////////////////////////////////
- @Override
- @Programmatic
- public String recognize(Throwable ex) {
+ private Optional<String> recognizeRootCause(Throwable ex) {
return _Exceptions.streamCausalChain(ex)
.filter(predicate)
@@ -155,17 +146,18 @@ public abstract class ExceptionRecognizerAbstract implements ExceptionRecognizer
return parsedMessage;
})
.filter(_NullSafe::isPresent)
- .findFirst()
- .orElse(null);
-
+ .findFirst();
}
@Programmatic
@Override
- public Recognition recognize2(Throwable ex) {
- return Recognition.of(category, recognize(ex));
+ public Optional<Recognition> recognize(Throwable ex) {
+ if(disabled) {
+ return Optional.empty();
+ }
+ return Recognition.of(category, recognizeRootCause(ex).orElse(null));
}
- @Inject protected TranslationService translationService;
+
}
diff --git a/api/applib/src/main/doc/modules/applib-svc/examples/services/exceprecog/ExceptionRecognizerComposite.java b/api/applib/src/main/doc/modules/applib-svc/examples/services/exceprecog/ExceptionRecognizerComposite.java
deleted file mode 100644
index d8ef200..0000000
--- a/api/applib/src/main/doc/modules/applib-svc/examples/services/exceprecog/ExceptionRecognizerComposite.java
+++ /dev/null
@@ -1,178 +0,0 @@
-/*
- * 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 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.apache.isis.applib.services.exceprecog;
-
-import java.util.Arrays;
-import java.util.List;
-import java.util.Map;
-import java.util.stream.Stream;
-
-import javax.annotation.PostConstruct;
-import javax.annotation.PreDestroy;
-import javax.inject.Inject;
-
-import org.apache.isis.applib.annotation.Programmatic;
-import org.apache.isis.applib.services.i18n.TranslationService;
-import org.apache.isis.applib.services.inject.ServiceInjector;
-import org.apache.isis.applib.services.registry.ServiceRegistry;
-import org.apache.isis.core.commons.internal.collections._Lists;
-
-/**
- * Convenience implementation of {@link ExceptionRecognizer} that loops through a list of
- * {@link #add(ExceptionRecognizer) registered} services.
- *
- * <p>
- * Note that the framework <i>does</i> allow multiple {@link ExceptionRecognizer service}s
- * to be registered in <tt>isis.properties</tt>, and each will be consulted in turn. Therefore
- * it is not necessary to use this class to register more than one such service. However,
- * it may be useful to use to treat a group of similar exceptions as a single unit. For example,
- * the <i>JDO object store</i> (in its applib) provides a set of {@link ExceptionRecognizer} to
- * recognize various types of constraint violations. These are grouped together as a single
- * set through the use of this class.
- */
-public class ExceptionRecognizerComposite implements ExceptionRecognizer {
-
- private final List<ExceptionRecognizer> exceptionRecognizers = _Lists.newArrayList();
-
- public ExceptionRecognizerComposite(final ExceptionRecognizer... exceptionRecognizers) {
- this(Arrays.asList(exceptionRecognizers));
- }
-
- public ExceptionRecognizerComposite(final List<? extends ExceptionRecognizer> exceptionRecognizers) {
- for (final ExceptionRecognizer er : exceptionRecognizers) {
- add(er);
- }
- }
-
- public ExceptionRecognizerComposite(final Stream<? extends ExceptionRecognizer> exceptionRecognizers) {
- exceptionRecognizers.forEach(this::add);
- }
-
- /**
- * Register an {@link ExceptionRecognizer} to be consulted when
- * {@link #recognize(Throwable)} is called.
- *
- * <p>
- * The most specific {@link ExceptionRecognizer recognizer}s should be registered
- * before the more general ones. See the <i>JDO object store</i> applib for
- * an example.
- */
- @Programmatic
- public final void add(final ExceptionRecognizer ers) {
- exceptionRecognizers.add(ers);
- }
-
- /**
- * Returns the non-<tt>null</tt> message of the first {@link #add(ExceptionRecognizer) add}ed
- * {@link ExceptionRecognizer service} that recognizes the exception.
- */
- @Override
- @Programmatic
- public final String recognize(final Throwable ex) {
- for (final ExceptionRecognizer ers : exceptionRecognizers) {
- final String message = ers.recognize(ex);
- if(message != null) {
- return message;
- }
- }
- return null;
- }
-
-
- /**
- * Returns the non-<tt>null</tt> recognition of the first {@link #add(ExceptionRecognizer) add}ed
- * {@link org.apache.isis.applib.services.exceprecog.ExceptionRecognizer}.
- *
- * <p>
- * If none recognize the exception, then falls back to using {@link #recognize(Throwable)}, returning a
- * {@link org.apache.isis.applib.services.exceprecog.ExceptionRecognizer.Recognition} with a
- * category of {@link org.apache.isis.applib.services.exceprecog.ExceptionRecognizer.Category#CLIENT_ERROR}.
- * </p>
- */
- @Override
- @Programmatic
- public final Recognition recognize2(final Throwable ex) {
- for (final ExceptionRecognizer ers : exceptionRecognizers) {
- final Recognition recognition = ers.recognize2(ex);
- if(recognition != null) {
- return recognition;
- }
- }
- // backward compatible so far as possible.
- return Recognition.of(Category.OTHER, recognize(ex));
- }
-
- // //////////////////////////////////////
-
- /**
- * For recognizers already {@link #add(ExceptionRecognizer) add}ed, simply {@link #injectServices()} and {@link #initRecognizers(Map) initializes}.
- *
- * <p>
- * Typical usage:
- * </p>
- * <pre>
- * public void init() {
- * add(new ExceptionRecognizerForThisException());
- * add(new ExceptionRecognizerForThatException());
- * add(new ExceptionRecognizerForTheOtherException());
- * super.init();
- * }
- * </pre>
- *
- */
- @PostConstruct
- @Override
- @Programmatic
- public void init() {
- injectServices();
- initRecognizers();
- }
-
- protected void injectServices() {
- if(serviceRegistry != null) {
- for (final ExceptionRecognizer ers : exceptionRecognizers) {
- serviceInjector.injectServicesInto(ers);
- }
- }
- }
-
- protected void initRecognizers() {
- for (final ExceptionRecognizer ers : exceptionRecognizers) {
- ers.init();
- }
- }
-
-
-
- @PreDestroy
- @Override
- @Programmatic
- public void shutdown() {
- for (final ExceptionRecognizer ers : exceptionRecognizers) {
- ers.shutdown();
- }
- }
-
- // //////////////////////////////////////
-
- @Inject ServiceRegistry serviceRegistry;
- @Inject ServiceInjector serviceInjector;
- @Inject TranslationService translationService;
-
-}
diff --git a/api/applib/src/main/doc/modules/applib-svc/examples/services/exceprecog/ExceptionRecognizerService.java b/api/applib/src/main/doc/modules/applib-svc/examples/services/exceprecog/ExceptionRecognizerService.java
new file mode 100644
index 0000000..8c6cf6f
--- /dev/null
+++ b/api/applib/src/main/doc/modules/applib-svc/examples/services/exceprecog/ExceptionRecognizerService.java
@@ -0,0 +1,43 @@
+/*
+ * 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 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.apache.isis.applib.services.exceprecog;
+
+import java.util.Optional;
+
+import org.apache.isis.applib.services.exceprecog.ExceptionRecognizer.Recognition;
+import org.apache.isis.core.commons.collections.Can;
+
+/**
+ *
+ * @since 2.0
+ *
+ */
+public interface ExceptionRecognizerService {
+
+ /**
+ *
+ * @return all ExceptionRecognizer implementations as discovered by the IoC container.
+ */
+ Can<ExceptionRecognizer> getExceptionRecognizers();
+
+ Optional<Recognition> recognize(Exception ex);
+
+ Optional<Recognition> recognize(Exception ex, Can<ExceptionRecognizer> additionalRecognizers);
+
+}