001/*
002 * CDDL HEADER START
003 *
004 * The contents of this file are subject to the terms of the
005 * Common Development and Distribution License, Version 1.0 only
006 * (the "License").  You may not use this file except in compliance
007 * with the License.
008 *
009 * You can obtain a copy of the license at
010 * docs/licenses/cddl.txt
011 * or http://www.opensource.org/licenses/cddl1.php.
012 * See the License for the specific language governing permissions
013 * and limitations under the License.
014 *
015 * When distributing Covered Code, include this CDDL HEADER in each
016 * file and include the License file at
017 * docs/licenses/cddl.txt.  If applicable,
018 * add the following below this CDDL HEADER, with the fields enclosed
019 * by brackets "[]" replaced with your own identifying information:
020 *      Portions Copyright [yyyy] [name of copyright owner]
021 *
022 * CDDL HEADER END
023 *
024 *
025 *      Copyright 2010-2021 Ping Identity Corporation
026 */
027package com.unboundid.directory.sdk.proxy.types;
028
029
030
031import java.io.Serializable;
032import java.util.Comparator;
033import java.util.List;
034
035import com.unboundid.util.NotExtensible;
036import com.unboundid.util.ThreadSafety;
037import com.unboundid.util.ThreadSafetyLevel;
038
039
040
041/**
042 * This interface defines a set of methods that may be used to assess the health
043 * of an LDAP external server.  A health check result consists of both a state
044 * (AVAILABLE, DEGRADED, or UNAVAILABLE) and a numeric score that may be used to
045 * help differentiate servers with the same health check state.
046 */
047@NotExtensible()
048@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_NOT_THREADSAFE)
049public interface HealthCheckResult
050       extends Comparable<HealthCheckResult>, Comparator<HealthCheckResult>,
051               Serializable
052{
053  /**
054   * Retrieves the health check state for the associated server.
055   *
056   * @return  The health check state for the associated server.
057   */
058  HealthCheckState getState();
059
060
061
062  /**
063   * Retrieves the numeric score for the associated server, which may be used to
064   * help differentiate the server from other servers with the same state.  The
065   * value returned will be an integer between 10 (the most healthy) and 1 (the
066   * least healthy) for a state of AVAILABLE or DEGRADED, or zero for a state
067   * of UNAVAILABLE.
068   *
069   * @return  The numeric score for the associated server.
070   */
071  int getScore();
072
073
074
075  /**
076   * Retrieves a list of messages providing additional information about the
077   * reason for the associated state and score.
078   *
079   * @return  A list of messages providing additional information about the
080   *          reason for the associated state and score, or an empty list if
081   *          no messages are available.
082   */
083  List<String> getMessages();
084
085
086
087  /**
088   * Retrieves the time that this health check result was created.  The value
089   * returned will be an offset in milliseconds since 12:00 a.m. on January 1,
090   * 1970.
091   *
092   * @return  The time that this health check result was created.
093   */
094  long getTime();
095
096
097
098  /**
099   * Retrieves a hash code for this health check result.
100   *
101   * @return  A hash code for this health check result.
102   */
103  int hashCode();
104
105
106
107  /**
108   * Indicates whether the provided object may be considered equal to this
109   * health check result.
110   *
111   * @param  o  The object for which to make the determination.
112   *
113   * @return  {@code true} if the provided object may be considered equal to
114   *          this health check result, or {@code false} if not.
115   */
116  boolean equals(final Object o);
117
118
119
120  /**
121   * Compares the provided health check result with this health check result to
122   * determine their relative order in a sorted list.  The ordering will be
123   * based primarily on the health check state, and the score will be used to
124   * differentiate between servers with the same state.
125   *
126   * @param  r  The health check result to be compared with this health check
127   *            result.  It must not be {@code null}.
128   *
129   * @return  A negative value if this health check result should be ordered
130   *          before the provided result, a positive value if this health check
131   *          result should be ordered after the provided result, or zero if
132   *          they are logically equivalent.
133   */
134  int compareTo(final HealthCheckResult r);
135
136
137
138  /**
139   * Compares the provided health check results to determine their relative
140   * order in a sorted list.  The ordering will be based primarily on the health
141   * check state, and the score will be used to differentiate between servers
142   * with the same state.
143   *
144   * @param  r1  The first health check result to be compared.  It must not be
145   *             {@code null}.
146   * @param  r2  The second health check result to be compared.  It must not be
147   *             {@code null}.
148   *
149   * @return  A negative value if the first health check result should be
150   *          ordered before the second, a positive value if the first health
151   *          check result should be ordered after the second, or zero if they
152   *          are logically equivalent.
153   */
154  int compare(final HealthCheckResult r1, final HealthCheckResult r2);
155
156
157
158  /**
159   * Indicates whether this health check result is considered better than the
160   * provided result.
161   *
162   * @param  r  The result for which to make the determination.  It must not be
163   *            {@code null}.
164   *
165   * @return  {@code true} if this health check result is considered better than
166   *          the provided result, or {@code false} if this health check result
167   *          is worse than or equivalent to the provided result.
168   */
169  boolean betterThan(final HealthCheckResult r);
170
171
172
173  /**
174   * Indicates whether this health check result is considered worse than the
175   * provided result.
176   *
177   * @param  r  The result for which to make the determination.  It must not be
178   *            {@code null}.
179   *
180   * @return  {@code true} if this health check result is considered worse than
181   *          the provided result, or {@code false} if this health check result
182   *          is better than or equivalent to the provided result.
183   */
184  boolean worseThan(final HealthCheckResult r);
185
186
187
188  /**
189   * Retrieves a string representation of this health check result.
190   *
191   * @return  A string representation of this health check result.
192   */
193  String toString();
194}