001/*
002 * Licensed under the Apache License, Version 2.0 (the "License");
003 * you may not use this file except in compliance with the License.
004 * You may obtain a copy of the License at
005 *
006 *     http://www.apache.org/licenses/LICENSE-2.0
007 *
008 * Unless required by applicable law or agreed to in writing, software
009 * distributed under the License is distributed on an "AS IS" BASIS,
010 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
011 * See the License for the specific language governing permissions and
012 * limitations under the License.
013 */
014package org.gbif.common.parsers.core;
015
016import java.util.List;
017
018import org.apache.commons.lang3.builder.ToStringBuilder;
019import org.apache.commons.lang3.builder.ToStringStyle;
020
021/**
022 * This represents the response of a generic parse operation.
023 */
024public class ParseResult<T> {
025
026  // the result code of the parse operation
027  public enum STATUS {
028    SUCCESS, FAIL, ERROR
029  }
030
031  // the confidence of the result, applicable if status=SUCCESS
032  public enum CONFIDENCE {
033    DEFINITE,
034    PROBABLE,
035    POSSIBLE;
036
037    public static CONFIDENCE lowerOf(CONFIDENCE c1, CONFIDENCE c2) {
038      if (c1 == null) {
039        return c2;
040      }
041
042      if (c2 == null) {
043        return c1;
044      }
045
046      if (c1.compareTo(c2) > 0) {
047        // Higher enum value is lower confidence
048        return c1;
049      } else {
050        return c2;
051      }
052    }
053  }
054
055  // the details of the response
056  protected final STATUS status;
057  protected final CONFIDENCE confidence;
058  protected final T payload;
059  protected final List<T> alternativePayloads;
060  protected final Throwable error;
061
062  /**
063   * @param <T1>       The generic type of the payload
064   * @param confidence The confidence in the result
065   * @param payload    The payload of the parse result
066   *
067   * @return The new ParseResult which has no error and status of SUCCESS
068   */
069  public static <T1> ParseResult<T1> success(CONFIDENCE confidence, T1 payload) {
070    return new ParseResult<T1>(STATUS.SUCCESS, confidence, payload, null, null);
071  }
072
073  /**
074   * @return A new parse response with only the status set to FAIL
075   */
076  public static <T1> ParseResult<T1> fail() {
077    return new ParseResult<T1>(STATUS.FAIL, null, null, null, null);
078  }
079
080  /**
081   * @return A new parse response configured to indicate an error
082   */
083  public static <T1> ParseResult<T1> error() {
084    return new ParseResult<T1>(STATUS.ERROR, null, null, null, null);
085  }
086
087  /**
088   * @param cause The cause of the error
089   *
090   * @return A new parse response configured with error and the cause
091   */
092  public static <T1> ParseResult<T1> error(Throwable cause) {
093    return new ParseResult<T1>(STATUS.ERROR, null, null, null, cause);
094  }
095
096  /**
097   * Forces all fields to be provided
098   *
099   * @param status     The status of the response
100   * @param confidence The confidence in the result
101   * @param payload    The payload of the response
102   * @param error      The error in the response
103   */
104  public ParseResult(STATUS status, CONFIDENCE confidence, T payload, List<T> alternativePayloads, Throwable error) {
105    this.status = status;
106    this.confidence = confidence;
107    this.alternativePayloads = alternativePayloads;
108    this.payload = payload;
109    this.error = error;
110  }
111
112  public STATUS getStatus() {
113    return status;
114  }
115
116  public CONFIDENCE getConfidence() {
117    return confidence;
118  }
119
120  public T getPayload() {
121    return payload;
122  }
123
124  public List<T> getAlternativePayloads() {
125    return alternativePayloads;
126  }
127
128  public Throwable getError() {
129    return error;
130  }
131
132  /**
133   * Returns true if {@link #getStatus()} returns SUCCESS.
134   *
135   * @return true if the parse operation was successful.
136   */
137  public boolean isSuccessful() {
138    return status == STATUS.SUCCESS;
139  }
140
141  @Override
142  public String toString() {
143    return new ToStringBuilder(this, ToStringStyle.SHORT_PREFIX_STYLE)
144      .append("status", getStatus())
145      .append("confidence", getConfidence())
146      .append("payload", getPayload())
147      .append("alternativePayloads", getAlternativePayloads())
148      .append("error", getError()).toString();
149  }
150}