001/**
002 *   Copyright (C) 2011-2012 Typesafe Inc. <http://typesafe.com>
003 */
004package com.typesafe.config;
005
006import java.net.URL;
007import java.util.List;
008
009
010/**
011 * Represents the origin (such as filename and line number) of a
012 * {@link ConfigValue} for use in error messages. Obtain the origin of a value
013 * with {@link ConfigValue#origin}. Exceptions may have an origin, see
014 * {@link ConfigException#origin}, but be careful because
015 * <code>ConfigException.origin()</code> may return null.
016 *
017 * <p>
018 * It's best to use this interface only for debugging; its accuracy is
019 * "best effort" rather than guaranteed, and a potentially-noticeable amount of
020 * memory could probably be saved if origins were not kept around, so in the
021 * future there might be some option to discard origins.
022 *
023 * <p>
024 * <em>Do not implement this interface</em>; it should only be implemented by
025 * the config library. Arbitrary implementations will not work because the
026 * library internals assume a specific concrete implementation. Also, this
027 * interface is likely to grow new methods over time, so third-party
028 * implementations will break.
029 */
030public interface ConfigOrigin {
031    /**
032     * Returns a string describing the origin of a value or exception. This will
033     * never return null.
034     *
035     * @return string describing the origin
036     */
037    public String description();
038
039    /**
040     * Returns a filename describing the origin. This will return null if the
041     * origin was not a file.
042     *
043     * @return filename of the origin or null
044     */
045    public String filename();
046
047    /**
048     * Returns a URL describing the origin. This will return null if the origin
049     * has no meaningful URL.
050     *
051     * @return url of the origin or null
052     */
053    public URL url();
054
055    /**
056     * Returns a classpath resource name describing the origin. This will return
057     * null if the origin was not a classpath resource.
058     *
059     * @return resource name of the origin or null
060     */
061    public String resource();
062
063    /**
064     * Returns a line number where the value or exception originated. This will
065     * return -1 if there's no meaningful line number.
066     *
067     * @return line number or -1 if none is available
068     */
069    public int lineNumber();
070
071    /**
072     * Returns any comments that appeared to "go with" this place in the file.
073     * Often an empty list, but never null. The details of this are subject to
074     * change, but at the moment comments that are immediately before an array
075     * element or object field, with no blank line after the comment, "go with"
076     * that element or field.
077     * 
078     * @return any comments that seemed to "go with" this origin, empty list if
079     *         none
080     */
081    public List<String> comments();
082
083    /**
084     * Returns a {@code ConfigOrigin} based on this one, but with the given
085     * comments. Does not modify this instance or any {@code ConfigValue}s with
086     * this origin (since they are immutable).  To set the returned origin to a
087     * {@code ConfigValue}, use {@link ConfigValue#withOrigin}.
088     *
089     * <p>
090     * Note that when the given comments are equal to the comments on this object,
091     * a new instance may not be created and {@code this} is returned directly.
092     *
093     * @param comments the comments used on the returned origin
094     * @return the ConfigOrigin with the given comments
095     */
096    public ConfigOrigin withComments(List<String> comments);
097
098    /**
099     * Returns a {@code ConfigOrigin} based on this one, but with the given
100     * line number. This origin must be a FILE, URL or RESOURCE. Does not modify
101     * this instance or any {@code ConfigValue}s with this origin (since they are
102     * immutable).  To set the returned origin to a  {@code ConfigValue}, use
103     * {@link ConfigValue#withOrigin}.
104     *
105     * <p>
106     * Note that when the given lineNumber are equal to the lineNumber on this
107     * object, a new instance may not be created and {@code this} is returned
108     * directly.
109     *
110     * @param lineNumber the new line number
111     * @return the created ConfigOrigin
112     */
113    public ConfigOrigin withLineNumber(int lineNumber);
114}