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     * Sets a contextual label-value pair into this context.
053     * <p>
054     * The pair will be added normally, but any existing label-value pair with
055     * the same label is removed from the context.
056     * </p>
057     * 
058     * @param label  the label of the item to add, {@code null} not recommended
059     * @param value  the value of item to add, may be {@code null}
060     * @return {@code this}, for method chaining, not {@code null}
061     */
062    ExceptionContext setContextValue(String label, Object value);
063
064    /**
065     * Retrieves all the contextual data values associated with the label.
066     * 
067     * @param label  the label to get the contextual values for, may be {@code null}
068     * @return the contextual values associated with the label, never {@code null}
069     */
070    List<Object> getContextValues(String label);
071
072    /**
073     * Retrieves the first available contextual data value associated with the label.
074     * 
075     * @param label  the label to get the contextual value for, may be {@code null}
076     * @return the first contextual value associated with the label, may be {@code null}
077     */
078    Object getFirstContextValue(String label);
079
080    /**
081     * Retrieves the full set of labels defined in the contextual data.
082     * 
083     * @return the set of labels, not {@code null}
084     */
085    Set<String> getContextLabels();
086
087    /**
088     * Retrieves the full list of label-value pairs defined in the contextual data.
089     * 
090     * @return the list of pairs, not {@code null}
091     */
092    List<Pair<String, Object>> getContextEntries();
093
094    /**
095     * Gets the contextualized error message based on a base message.
096     * This will add the context label-value pairs to the message.
097     * 
098     * @param baseMessage  the base exception message <b>without</b> context information appended
099     * @return the exception message <b>with</b> context information appended, not {@code null}
100     */
101    String getFormattedExceptionMessage(String baseMessage);
102
103}