UserNotificationWithFeedback.java

  1. /*
  2.  * *************************************************************************************************************************************************************
  3.  *
  4.  * TheseFoolishThings: Miscellaneous utilities
  5.  * http://tidalwave.it/projects/thesefoolishthings
  6.  *
  7.  * Copyright (C) 2009 - 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/thesefoolishthings-src
  22.  * git clone https://github.com/tidalwave-it/thesefoolishthings-src
  23.  *
  24.  * *************************************************************************************************************************************************************
  25.  */
  26. package it.tidalwave.util.ui;

  27. import javax.annotation.Nonnull;
  28. import javax.annotation.concurrent.Immutable;
  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 user notification where a feedback is expected (confirmation or cancellation).
  40.  *
  41.  * @author  Fabrizio Giudici
  42.  *
  43.  **************************************************************************************************************************************************************/
  44. @Getter @Immutable
  45. @ToString(callSuper = true)
  46. public class UserNotificationWithFeedback extends UserNotification
  47.   {
  48.     /***********************************************************************************************************************************************************
  49.      * This class provides a few callback methods to notify a choice from the user.
  50.      **********************************************************************************************************************************************************/
  51.     @AllArgsConstructor(access = AccessLevel.PRIVATE)
  52.     public static class Feedback
  53.       {
  54.         @With
  55.         private final Callback onConfirm;

  56.         @With
  57.         private final Callback onCancel;

  58.         /***************************************************************************************************************
  59.          *
  60.          * Checks whether the current instance has a callback for confirmation.
  61.          *
  62.          * @return  {@code true} if the instance has the callback
  63.          * @since   3.2-ALPHA-1
  64.          *
  65.          **************************************************************************************************************/
  66.         public boolean canConfirm()
  67.           {
  68.             return onConfirm != Callback.EMPTY;
  69.           }

  70.         /***************************************************************************************************************
  71.          *
  72.          * Checks whether the current instance has a callback for cancellation.
  73.          *
  74.          * @return  {@code true} if the instance has the callback
  75.          * @since   3.2-ALPHA-1
  76.          *
  77.          **************************************************************************************************************/
  78.         public boolean canCancel()
  79.           {
  80.             return onCancel != Callback.EMPTY;
  81.           }

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

  96.         /***************************************************************************************************************
  97.          *
  98.          * Callback method invoked when the user cancels an operation.
  99.          *
  100.          * @throws  Exception  in cases of error
  101.          *
  102.          **************************************************************************************************************/
  103.         @SuppressWarnings("RedundantThrows")
  104.         @SneakyThrows(Throwable.class)
  105.         private void onCancel()
  106.                 throws Exception
  107.           {
  108.             onCancel.call();
  109.           }
  110.       }

  111.     protected final Feedback feedback;

  112.     /***********************************************************************************************************************************************************
  113.      * @param text          the notification text
  114.      * @param caption       the notification caption
  115.      * @param feedback      the feedback
  116.      **********************************************************************************************************************************************************/
  117.     protected UserNotificationWithFeedback (@Nonnull final String text,
  118.                                             @Nonnull final String caption,
  119.                                             @Nonnull final Feedback feedback)
  120.       {
  121.         super(text, caption);
  122.         this.feedback = feedback;
  123.       }

  124.     /***********************************************************************************************************************************************************
  125.      * Creates a notification with empty caption and text.
  126.      *
  127.      * @return               the notification
  128.      **********************************************************************************************************************************************************/
  129.     @Nonnull
  130.     public static UserNotificationWithFeedback notificationWithFeedback()
  131.       {
  132.         return new UserNotificationWithFeedback("", "", feedback());
  133.       }

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

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

  160.     /***********************************************************************************************************************************************************
  161.      * Associates a text to the notification.
  162.      *
  163.      * @param  text          the text
  164.      * @return               the notification
  165.      **********************************************************************************************************************************************************/
  166.     @Override @Nonnull
  167.     public UserNotificationWithFeedback withText (@Nonnull final String text)
  168.       {
  169.         return new UserNotificationWithFeedback(text, caption, feedback);
  170.       }

  171.     /***********************************************************************************************************************************************************
  172.      * Associates a text to the notification, retrieved from a resource bundle.
  173.      *
  174.      * @param  bundleClass   the class where to search the resource bundle from
  175.      * @param  resourceName  the resource name of the text in the bundle
  176.      * @param  params        some (optional) parameters to the resource
  177.      * @return               the notification
  178.      **********************************************************************************************************************************************************/
  179.     @Override @Nonnull
  180.     public UserNotificationWithFeedback withText (@Nonnull final Class<?> bundleClass,
  181.                                                   @Nonnull final String resourceName,
  182.                                                   @Nonnull final Object ... params)
  183.       {
  184.         return new UserNotificationWithFeedback(getMessage(bundleClass, resourceName, params), caption, feedback);
  185.       }

  186.     /***********************************************************************************************************************************************************
  187.      * Associates a {@link Feedback} to the notification.
  188.      *
  189.      * @param  feedback    the {@code Feedback} to associate
  190.      * @return             the notification
  191.      **********************************************************************************************************************************************************/
  192.     @Nonnull
  193.     public UserNotificationWithFeedback withFeedback (@Nonnull final Feedback feedback)
  194.       {
  195.         return new UserNotificationWithFeedback(text, caption, feedback);
  196.       }

  197.     /***********************************************************************************************************************************************************
  198.      * Notifies a confirmation to the user notification.
  199.      *
  200.      * @throws  Exception  in cases of error
  201.      **********************************************************************************************************************************************************/
  202.     public void confirm()
  203.       throws Exception
  204.       {
  205.         feedback.onConfirm();
  206.       }

  207.     /***********************************************************************************************************************************************************
  208.      * Notifies a cancellation to the user notification.
  209.      *
  210.      * @throws  Exception  in cases of error
  211.      **********************************************************************************************************************************************************/
  212.     public void cancel()
  213.       throws Exception
  214.       {
  215.         feedback.onCancel();
  216.       }

  217.     /***********************************************************************************************************************************************************
  218.      * Creates a new {@code Feedback} that does nothing. This method should be chained with {@code withOnConfirm()}
  219.      * and/or {@code withOnCancel(Callback)} to specify the relative callbacks.
  220.      *
  221.      * <pre>
  222.      *   feedback().withOnConfirm(this::doSomething).withOnCancel(this::doSomethingElse);
  223.      * </pre>
  224.      *
  225.      * @return    a feedback that does nothing in any case
  226.      * @since     3.2-ALPHA-1 (was previously on {@code Feedback8}
  227.      **********************************************************************************************************************************************************/
  228.     @Nonnull
  229.     public static Feedback feedback()
  230.       {
  231.         return new Feedback(Callback.EMPTY, Callback.EMPTY);
  232.       }
  233.   }