    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     * @since 1.3.0
    094     *
    095     * @param comments the comments used on the returned origin
    096     * @return the ConfigOrigin with the given comments
    097     */
    098    public ConfigOrigin withComments(List<String> comments);
    099
    100    /**
    101     * Returns a {@code ConfigOrigin} based on this one, but with the given
    102     * line number. This origin must be a FILE, URL or RESOURCE. Does not modify
    103     * this instance or any {@code ConfigValue}s with this origin (since they are
    104     * immutable).  To set the returned origin to a  {@code ConfigValue}, use
    105     * {@link ConfigValue#withOrigin}.
    106     *
    107     * <p>
    108     * Note that when the given lineNumber are equal to the lineNumber on this
    109     * object, a new instance may not be created and {@code this} is returned
    110     * directly.
    111     *
    112     * @since 1.3.0
    113     *
    114     * @param lineNumber the new line number
    115     * @return the created ConfigOrigin
    116     */
    117    public ConfigOrigin withLineNumber(int lineNumber);
    118}