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}