    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}