UserNotificationWithFeedback.java

  1. /*
  2.  * *************************************************************************************************************************************************************
  3.  *
  4.  * SteelBlue: DCI User Interfaces
  5.  * http://tidalwave.it/projects/steelblue
  6.  *
  7.  * Copyright (C) 2015 - 2025 by Tidalwave s.a.s. (http://tidalwave.it)
  8.  *
  9.  * *************************************************************************************************************************************************************
  10.  *
  11.  * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
  12.  * You may obtain a copy of the License at
  13.  *
  14.  *     http://www.apache.org/licenses/LICENSE-2.0
  15.  *
  16.  * 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
  17.  * CONDITIONS OF ANY KIND, either express or implied.  See the License for the specific language governing permissions and limitations under the License.
  18.  *
  19.  * *************************************************************************************************************************************************************
  20.  *
  21.  * git clone https://bitbucket.org/tidalwave/steelblue-src
  22.  * git clone https://github.com/tidalwave-it/steelblue-src
  23.  *
  24.  * *************************************************************************************************************************************************************
  25.  */
  26. package it.tidalwave.ui.core;

  27. import javax.annotation.concurrent.Immutable;
  28. import jakarta.annotation.Nonnull;
  29. import it.tidalwave.util.Callback;
  30. import lombok.AccessLevel;
  31. import lombok.AllArgsConstructor;
  32. import lombok.Getter;
  33. import lombok.SneakyThrows;
  34. import lombok.ToString;
  35. import lombok.With;
  36. import static it.tidalwave.util.BundleUtilities.getMessage;

  37. /***************************************************************************************************************************************************************
  38.  *
  39.  * This class models a notification that will be presented to a user, and a feedback is expected (confirmation or cancellation).
  40.  *
  41.  * @since   2.0-ALPHA-2
  42.  * @author  Fabrizio Giudici
  43.  *
  44.  **************************************************************************************************************************************************************/
  45. @Getter @Immutable
  46. @ToString(callSuper = true)
  47. public class UserNotificationWithFeedback extends UserNotification
  48.   {
  49.     /***********************************************************************************************************************************************************
  50.      * This class provides a few callback methods to notify a choice from the user.
  51.      **********************************************************************************************************************************************************/
  52.     @AllArgsConstructor(access = AccessLevel.PRIVATE)
  53.     public static class Feedback
  54.       {
  55.         @With
  56.         private final Callback onConfirm;

  57.         @With
  58.         private final Callback onCancel;

  59.         /*******************************************************************************************************************************************************
  60.          * {@return {@code true} if the current instance has a callback for confirmation}.
  61.          ******************************************************************************************************************************************************/
  62.         public boolean canConfirm()
  63.           {
  64.             return onConfirm != Callback.EMPTY;
  65.           }

  66.         /*******************************************************************************************************************************************************
  67.          * {@return {@code true} if the current instance has a callback for cancellation}.
  68.          ******************************************************************************************************************************************************/
  69.         public boolean canCancel()
  70.           {
  71.             return onCancel != Callback.EMPTY;
  72.           }

  73.         /*******************************************************************************************************************************************************
  74.          * Callback method invoked when the user confirms an operation.
  75.          * @throws  Exception  in cases of error
  76.          ******************************************************************************************************************************************************/
  77.         @SuppressWarnings("RedundantThrows")
  78.         @SneakyThrows(Throwable.class)
  79.         private void onConfirm()
  80.                 throws Exception
  81.           {
  82.             onConfirm.call();
  83.           }

  84.         /*******************************************************************************************************************************************************
  85.          * Callback method invoked when the user cancels an operation.
  86.          * @throws  Exception  in cases of error
  87.          ******************************************************************************************************************************************************/
  88.         @SuppressWarnings("RedundantThrows")
  89.         @SneakyThrows(Throwable.class)
  90.         private void onCancel()
  91.                 throws Exception
  92.           {
  93.             onCancel.call();
  94.           }
  95.       }

  96.     @Nonnull
  97.     protected final Feedback feedback;

  98.     /***********************************************************************************************************************************************************
  99.      * @param text          the notification text
  100.      * @param caption       the notification caption
  101.      * @param feedback      the feedback
  102.      **********************************************************************************************************************************************************/
  103.     protected UserNotificationWithFeedback (@Nonnull final String text, @Nonnull final String caption, @Nonnull final Feedback feedback)
  104.       {
  105.         super(text, caption);
  106.         this.feedback = feedback;
  107.       }

  108.     /***********************************************************************************************************************************************************
  109.      * {@return a notification with empty caption and text}.
  110.      **********************************************************************************************************************************************************/
  111.     @Nonnull
  112.     public static UserNotificationWithFeedback notificationWithFeedback()
  113.       {
  114.         return new UserNotificationWithFeedback("", "", feedback());
  115.       }

  116.     /***********************************************************************************************************************************************************
  117.      * {@return a notification with a caption}.
  118.      * @param  caption       the caption
  119.      **********************************************************************************************************************************************************/
  120.     @Override @Nonnull
  121.     public UserNotificationWithFeedback withCaption (@Nonnull final String caption)
  122.       {
  123.         return new UserNotificationWithFeedback(text, caption, feedback);
  124.       }

  125.     /***********************************************************************************************************************************************************
  126.      * {@return a notification with a caption from a bundle}.
  127.      * @param  bundleClass   the class where to search the resource bundle from
  128.      * @param  resourceName  the resource name of the caption in the bundle
  129.      * @param  params        some (optional) parameters to the resource
  130.      **********************************************************************************************************************************************************/
  131.     @Override @Nonnull
  132.     public UserNotificationWithFeedback withCaption (@Nonnull final Class<?> bundleClass, @Nonnull final String resourceName, @Nonnull final Object ... params)
  133.       {
  134.         return new UserNotificationWithFeedback(text, getMessage(bundleClass, resourceName, params), feedback);
  135.       }

  136.     /***********************************************************************************************************************************************************
  137.      * {@return a notification with a text}.
  138.      * @param  text          the text
  139.      **********************************************************************************************************************************************************/
  140.     @Override @Nonnull
  141.     public UserNotificationWithFeedback withText (@Nonnull final String text)
  142.       {
  143.         return new UserNotificationWithFeedback(text, caption, feedback);
  144.       }

  145.     /***********************************************************************************************************************************************************
  146.      * {@return a notification with a text from a bundle}.
  147.      * @param  bundleClass   the class where to search the resource bundle from
  148.      * @param  resourceName  the resource name of the text in the bundle
  149.      * @param  params        some (optional) parameters to the resource
  150.      **********************************************************************************************************************************************************/
  151.     @Override @Nonnull
  152.     public UserNotificationWithFeedback withText (@Nonnull final Class<?> bundleClass, @Nonnull final String resourceName, @Nonnull final Object ... params)
  153.       {
  154.         return new UserNotificationWithFeedback(getMessage(bundleClass, resourceName, params), caption, feedback);
  155.       }

  156.     /***********************************************************************************************************************************************************
  157.      * {@return a notification {@link Feedback}}.
  158.      * @param  feedback    the {@code Feedback} to associate
  159.      **********************************************************************************************************************************************************/
  160.     @Nonnull
  161.     public UserNotificationWithFeedback withFeedback (@Nonnull final Feedback feedback)
  162.       {
  163.         return new UserNotificationWithFeedback(text, caption, feedback);
  164.       }

  165.     /***********************************************************************************************************************************************************
  166.      * Notifies a confirmation to the user notification.
  167.      * @throws  Exception  in cases of error
  168.      **********************************************************************************************************************************************************/
  169.     public void confirm()
  170.       throws Exception
  171.       {
  172.         feedback.onConfirm();
  173.       }

  174.     /***********************************************************************************************************************************************************
  175.      * Notifies a cancellation to the user notification.
  176.      * @throws  Exception  in cases of error
  177.      **********************************************************************************************************************************************************/
  178.     public void cancel()
  179.       throws Exception
  180.       {
  181.         feedback.onCancel();
  182.       }

  183.     /***********************************************************************************************************************************************************
  184.      * {@return a new {@code Feedback} that does nothing}. This method should be chained with {@code withOnConfirm()} and/or {@code withOnCancel(Callback)} to
  185.      * specify the relative callbacks.
  186.      * <pre>{@code}
  187.      *   feedback().withOnConfirm(this::doSomething).withOnCancel(this::doSomethingElse);
  188.      * }</pre>
  189.      **********************************************************************************************************************************************************/
  190.     @Nonnull
  191.     public static Feedback feedback()
  192.       {
  193.         return new Feedback(Callback.EMPTY, Callback.EMPTY);
  194.       }
  195.   }