001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.console.widgets;
018
019import java.util.*;
020import java.util.stream.*;
021
022/**
023 * The one closed status-tone palette shared by every surface that paints a semantic status colour:
024 * {@code info} / {@code success} / {@code warning} / {@code error} / {@code neutral}.
025 *
026 * <p>
027 * Exactly five values, and no synonyms.  Server-side checks accept a {@link #wire()} token from
028 * {@link #WIRE_TOKENS} and reject anything else; the client-side painters (the pill, the QuickStats tiles and the
029 * dialog-bar badge) silently ignore an off-palette token and apply no tone class.  The same five names therefore mean
030 * the same five things in Java, in the emitted {@code is-<tone>} CSS class, and in the {@code juneau-renders.js} tone
031 * map.
032 *
033 * <p>
034 * {@link Badge#tone} uses this same enum and serializes it as the enum name.
035 *
036 * <h5 class='section'>Example:</h5>
037 * <p class='bjava'>
038 *    <jk>boolean</jk> <jv>ok</jv> = StatusTone.<jsm>isValid</jsm>(<js>"warning"</js>);  <jc>// true</jc>
039 *    String <jv>token</jv> = StatusTone.<jsf>WARNING</jsf>.wire();  <jc>// "warning"</jc>
040 * </p>
041 *
042 * @since 10.0.0
043 */
044public enum StatusTone {
045
046   /** Informational (neither good nor bad); maps to {@code is-info}. */
047   INFO,
048
049   /** Healthy / completed; maps to {@code is-success}. */
050   SUCCESS,
051
052   /** Approaching a limit or needing attention; maps to {@code is-warning}. */
053   WARNING,
054
055   /** Failed / over a hard limit; maps to {@code is-error}. */
056   ERROR,
057
058   /** No semantic colour; inherits the surrounding text colour and emits no tone class. */
059   NEUTRAL;
060
061   /**
062    * The five legal wire tokens, in declaration order.
063    *
064    * <p>
065    * The single source of truth every server-side tone check reads, so no caller can hand-roll a fourth or sixth
066    * value.
067    */
068   @SuppressWarnings({
069      "java:S2386" // Public for adopters and tests; the value is an unmodifiable set, so it cannot be mutated despite the Set type.
070   })
071   public static final Set<String> WIRE_TOKENS = wireTokens();
072
073   private static Set<String> wireTokens() {
074      Set<String> s = Arrays.stream(values()).map(StatusTone::wire).collect(Collectors.toCollection(LinkedHashSet<String>::new));
075      return Collections.unmodifiableSet(s);
076   }
077
078   /**
079    * Returns the lowercase wire token for this tone.
080    *
081    * @return The wire token (e.g. <c>"warning"</c>).
082    */
083   public String wire() {
084      return name().toLowerCase(Locale.ROOT);
085   }
086
087   /**
088    * Returns <jk>true</jk> if the specified token is one of the five legal tones.
089    *
090    * @param token The candidate wire token.  Can be <jk>null</jk>.
091    * @return <jk>true</jk> if the token is a legal tone; <jk>false</jk> for <jk>null</jk>, blank, differently-cased,
092    *    or off-palette values.
093    */
094   public static boolean isValid(String token) {
095      return token != null && WIRE_TOKENS.contains(token);
096   }
097}