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 */
017 package org.apache.commons.lang3.exception;
018
019 import java.util.Set;
020
021 /**
022 * Allows the storage and retrieval of contextual information based on label-value
023 * pairs for exceptions.
024 *
025 * @see ContextedException
026 * @see ContextedRuntimeException
027 * @author Apache Software Foundation
028 * @author D. Ashmore
029 * @since 3.0
030 */
031 public interface ExceptionContext {
032
033 /**
034 * Adds a contextual label-value pair into this context.
035 * <p>
036 * This label-value pair provides information useful for debugging. If the
037 * provided label already exists, it depends on the implementation what
038 * happens with the new value.
039 * </p>
040 *
041 * @param label the label of the item to add, null not recommended
042 * @param value the value of item to add, may be null
043 * @return context itself to allow method chaining
044 */
045 public ExceptionContext addValue(String label, Object value);
046
047 /**
048 * Replaces a contextual label-value pair of this context.
049 * <p>
050 * This label-value pair provides information useful for debugging. If the
051 * label does not exist yet, it depends on the implementation what happens
052 * with the provided value.
053 * </p>
054 *
055 * @param label the label of the item to add, null not recommended
056 * @param value the value of item to add, may be null
057 * @return context itself to allow method chaining
058 */
059 public ExceptionContext replaceValue(String label, Object value);
060
061 /**
062 * Retrieves a contextual data value associated with the label.
063 *
064 * @param label the label to get the contextual value for, may be null
065 * @return the contextual value associated with the label, may be null
066 */
067 public Object getValue(String label);
068
069 /**
070 * Retrieves the labels defined in the contextual data.
071 *
072 * @return the set of labels, never null
073 */
074 public Set<String> getLabelSet();
075
076 /**
077 * Implementors provide the given base message with context label/value item
078 * information appended.
079 *
080 * @param baseMessage the base exception message <b>without</b> context information appended
081 * @return the exception message <b>with</b> context information appended, never null
082 */
083 public String getFormattedExceptionMessage(String baseMessage);
084
085 }