UserNotificationWithFeedback.java

  1. /*
  2.  * *********************************************************************************************************************
  3.  *
  4.  * TheseFoolishThings: Miscellaneous utilities
  5.  * http://tidalwave.it/projects/thesefoolishthings
  6.  *
  7.  * Copyright (C) 2009 - 2023 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
  12.  * the License. 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
  17.  * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the
  18.  * specific language governing permissions and limitations under the License.
  19.  *
  20.  * *********************************************************************************************************************
  21.  *
  22.  * git clone https://bitbucket.org/tidalwave/thesefoolishthings-src
  23.  * git clone https://github.com/tidalwave-it/thesefoolishthings-src
  24.  *
  25.  * *********************************************************************************************************************
  26.  */
  27. package it.tidalwave.util.ui;

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

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

  59.         @With
  60.         private final Callback onCancel;

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

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

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

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

  114.     @Getter
  115.     protected final Feedback feedback;

  116.     /*******************************************************************************************************************
  117.      *
  118.      * @param text          the notification text
  119.      * @param caption       the notification caption
  120.      * @param feedback      the feedback
  121.      *
  122.      ******************************************************************************************************************/
  123.     protected UserNotificationWithFeedback (@Nonnull final String text,
  124.                                             @Nonnull final String caption,
  125.                                             @Nonnull final Feedback feedback)
  126.       {
  127.         super(text, caption);
  128.         this.feedback = feedback;
  129.       }

  130.     /*******************************************************************************************************************
  131.      *
  132.      * Creates a notification with empty caption and text.
  133.      *
  134.      * @return               the notification
  135.      *
  136.      ******************************************************************************************************************/
  137.     @Nonnull
  138.     public static UserNotificationWithFeedback notificationWithFeedback()
  139.       {
  140.         return new UserNotificationWithFeedback("", "", feedback());
  141.       }

  142.     /*******************************************************************************************************************
  143.      *
  144.      * Associates a caption to the notification.
  145.      *
  146.      * @param  caption       the caption
  147.      * @return               the notification
  148.      *
  149.      ******************************************************************************************************************/
  150.     @Override @Nonnull
  151.     public UserNotificationWithFeedback withCaption (@Nonnull final String caption)
  152.       {
  153.         return new UserNotificationWithFeedback(text, caption, feedback);
  154.       }

  155.     /*******************************************************************************************************************
  156.      *
  157.      * Associates a caption to the notification, retrieved from a resource bundle.
  158.      *
  159.      * @param  bundleClass   the class where to search the resource bundle from
  160.      * @param  resourceName  the resource name of the caption in the bundle
  161.      * @param  params        some (optional) parameters to the resource
  162.      * @return               the notification
  163.      *
  164.      ******************************************************************************************************************/
  165.     @Override @Nonnull
  166.     public UserNotificationWithFeedback withCaption (@Nonnull final Class<?> bundleClass,
  167.                                                      @Nonnull final String resourceName,
  168.                                                      @Nonnull final Object ... params)
  169.       {
  170.         return new UserNotificationWithFeedback(text, getMessage(bundleClass, resourceName, params), feedback);
  171.       }

  172.     /*******************************************************************************************************************
  173.      *
  174.      * Associates a text to the notification.
  175.      *
  176.      * @param  text          the text
  177.      * @return               the notification
  178.      *
  179.      ******************************************************************************************************************/
  180.     @Override @Nonnull
  181.     public UserNotificationWithFeedback withText (@Nonnull final String text)
  182.       {
  183.         return new UserNotificationWithFeedback(text, caption, feedback);
  184.       }

  185.     /*******************************************************************************************************************
  186.      *
  187.      * Associates a text to the notification, retrieved from a resource bundle.
  188.      *
  189.      * @param  bundleClass   the class where to search the resource bundle from
  190.      * @param  resourceName  the resource name of the text in the bundle
  191.      * @param  params        some (optional) parameters to the resource
  192.      * @return               the notification
  193.      *
  194.      ******************************************************************************************************************/
  195.     @Override @Nonnull
  196.     public UserNotificationWithFeedback withText (@Nonnull final Class<?> bundleClass,
  197.                                                   @Nonnull final String resourceName,
  198.                                                   @Nonnull final Object ... params)
  199.       {
  200.         return new UserNotificationWithFeedback(getMessage(bundleClass, resourceName, params), caption, feedback);
  201.       }

  202.     /*******************************************************************************************************************
  203.      *
  204.      * Associates a {@link Feedback} to the notification.
  205.      *
  206.      * @param  feedback    the {@code Feedback} to associate
  207.      * @return             the notification
  208.      *
  209.      ******************************************************************************************************************/
  210.     @Nonnull
  211.     public UserNotificationWithFeedback withFeedback (@Nonnull final Feedback feedback)
  212.       {
  213.         return new UserNotificationWithFeedback(text, caption, feedback);
  214.       }

  215.     /*******************************************************************************************************************
  216.      *
  217.      * Notifies a confirmation to the user notification.
  218.      *
  219.      * @throws  Exception  in cases of error
  220.      *
  221.      ******************************************************************************************************************/
  222.     public void confirm()
  223.       throws Exception
  224.       {
  225.         feedback.onConfirm();
  226.       }

  227.     /*******************************************************************************************************************
  228.      *
  229.      * Notifies a cancellation to the user notification.
  230.      *
  231.      * @throws  Exception  in cases of error
  232.      *
  233.      ******************************************************************************************************************/
  234.     public void cancel()
  235.       throws Exception
  236.       {
  237.         feedback.onCancel();
  238.       }

  239.     /*******************************************************************************************************************
  240.      *
  241.      * Creates a new {@code Feedback} that does nothing. This method should be chained with {@code withOnConfirm()}
  242.      * and/or {@code withOnCancel(Callback)} to specify the relative callbacks.
  243.      *
  244.      * <pre>
  245.      *   feedback().withOnConfirm(this::doSomething).withOnCancel(this::doSomethingElse);
  246.      * </pre>
  247.      *
  248.      * @return    a feedback that does nothing in any case
  249.      * @since     3.2-ALPHA-1 (was previously on {@code Feedback8}
  250.      *
  251.      ******************************************************************************************************************/
  252.     @Nonnull
  253.     public static Feedback feedback()
  254.       {
  255.         return new Feedback(Callback.EMPTY, Callback.EMPTY);
  256.       }
  257.   }