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.commons.lang3.exception;
018
019import java.util.List;
020import java.util.Set;
021
022import org.apache.commons.lang3.tuple.Pair;
023
024/**
025 * Allows the storage and retrieval of contextual information based on label-value
026 * pairs for exceptions.
027 * <p>
028 * Implementations are expected to manage the pairs in a list-style collection
029 * that keeps the pairs in the sequence of their addition.
030 * </p>
031 *
032 * @see ContextedException
033 * @see ContextedRuntimeException
034 * @since 3.0
035 */
036public interface ExceptionContext {
037
038    /**
039     * Adds a contextual label-value pair into this context.
040     * <p>
041     * The pair will be added to the context, independently of an already
042     * existing pair with the same label.
043     * </p>
044     *
045     * @param label  the label of the item to add, {@code null} not recommended
046     * @param value  the value of item to add, may be {@code null}
047     * @return {@code this}, for method chaining, not {@code null}
048     */
049    ExceptionContext addContextValue(String label, Object value);
050
051    /**
052     * Retrieves the full list of label-value pairs defined in the contextual data.
053     *
054     * @return the list of pairs, not {@code null}
055     */
056    List<Pair<String, Object>> getContextEntries();
057
058    /**
059     * Retrieves the full set of labels defined in the contextual data.
060     *
061     * @return the set of labels, not {@code null}
062     */
063    Set<String> getContextLabels();
064
065    /**
066     * Retrieves all the contextual data values associated with the label.
067     *
068     * @param label  the label to get the contextual values for, may be {@code null}
069     * @return the contextual values associated with the label, never {@code null}
070     */
071    List<Object> getContextValues(String label);
072
073    /**
074     * Retrieves the first available contextual data value associated with the label.
075     *
076     * @param label  the label to get the contextual value for, may be {@code null}
077     * @return the first contextual value associated with the label, may be {@code null}
078     */
079    Object getFirstContextValue(String label);
080
081    /**
082     * Gets the contextualized error message based on a base message.
083     * This will add the context label-value pairs to the message.
084     *
085     * @param baseMessage  the base exception message <b>without</b> context information appended
086     * @return the exception message <b>with</b> context information appended, not {@code null}
087     */
088    String getFormattedExceptionMessage(String baseMessage);
089
090    /**
091     * Sets a contextual label-value pair into this context.
092     * <p>
093     * The pair will be added normally, but any existing label-value pair with
094     * the same label is removed from the context.
095     * </p>
096     *
097     * @param label  the label of the item to add, {@code null} not recommended
098     * @param value  the value of item to add, may be {@code null}
099     * @return {@code this}, for method chaining, not {@code null}
100     */
101    ExceptionContext setContextValue(String label, Object value);
102
103}