001/** 002 * Copyright (C) 2011-2012 Typesafe Inc. <http://typesafe.com> 003 */ 004package com.typesafe.config; 005 006/** 007 * Implement this interface and provide an instance to 008 * {@link ConfigParseOptions#setIncluder ConfigParseOptions.setIncluder()} to 009 * customize handling of {@code include} statements in config files. You may 010 * also want to implement {@link ConfigIncluderClasspath}, 011 * {@link ConfigIncluderFile}, and {@link ConfigIncluderURL}, or not. 012 */ 013public interface ConfigIncluder { 014 /** 015 * Returns a new includer that falls back to the given includer. This is how 016 * you can obtain the default includer; it will be provided as a fallback. 017 * It's up to your includer to chain to it if you want to. You might want to 018 * merge any files found by the fallback includer with any objects you load 019 * yourself. 020 * 021 * It's important to handle the case where you already have the fallback 022 * with a "return this", i.e. this method should not create a new object if 023 * the fallback is the same one you already have. The same fallback may be 024 * added repeatedly. 025 * 026 * @param fallback the previous includer for chaining 027 * @return a new includer 028 */ 029 ConfigIncluder withFallback(ConfigIncluder fallback); 030 031 /** 032 * Parses another item to be included. The returned object typically would 033 * not have substitutions resolved. You can throw a ConfigException here to 034 * abort parsing, or return an empty object, but may not return null. 035 * 036 * This method is used for a "heuristic" include statement that does not 037 * specify file, URL, or classpath resource. If the include statement does 038 * specify, then the same class implementing {@link ConfigIncluder} must 039 * also implement {@link ConfigIncluderClasspath}, 040 * {@link ConfigIncluderFile}, or {@link ConfigIncluderURL} as needed, or a 041 * default includer will be used. 042 * 043 * @param context 044 * some info about the include context 045 * @param what 046 * the include statement's argument 047 * @return a non-null ConfigObject 048 */ 049 ConfigObject include(ConfigIncludeContext context, String what); 050}