001/*
002 * Configurate
003 * Copyright (C) zml and Configurate contributors
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 *    http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.spongepowered.configurate.loader;
018
019import org.spongepowered.configurate.ConfigurateException;
020import org.spongepowered.configurate.ConfigurationNode;
021import org.spongepowered.configurate.ConfigurationNodeFactory;
022import org.spongepowered.configurate.ConfigurationOptions;
023import org.spongepowered.configurate.reference.ConfigurationReference;
024import org.spongepowered.configurate.reference.WatchServiceListener;
025
026import java.nio.file.Path;
027import java.util.function.Function;
028
029/**
030 * Represents an object which can load and save {@link ConfigurationNode} objects in a specific
031 * configuration format.
032 *
033 * <p>An abstract implementation is provided by {@link AbstractConfigurationLoader}.</p>
034 *
035 * @param <N> the {@link ConfigurationNode} type produced by the loader
036 * @since 4.0.0
037 */
038public interface ConfigurationLoader<N extends ConfigurationNode> extends ConfigurationNodeFactory<N> {
039
040    /**
041     * Attempts to load a {@link ConfigurationNode} using this loader, from the
042     * defined source.
043     *
044     * <p>The resultant node represents the root of the configuration being
045     * loaded.</p>
046     *
047     * <p>The {@link #defaultOptions() default options} will be used to
048     * construct the resultant configuration nodes.</p>
049     *
050     * @return the newly constructed node
051     * @throws ConfigurateException if any sort of error occurs with reading or
052     *                              parsing the configuration
053     * @since 4.0.0
054     */
055    default N load() throws ConfigurateException {
056        return load(defaultOptions());
057    }
058
059    /**
060     * Attempts to load a {@link ConfigurationNode} using this loader, from the defined source.
061     *
062     * <p>The resultant node represents the root of the configuration being
063     * loaded.</p>
064     *
065     * @param options the options to load with
066     * @return the newly constructed node
067     * @throws ConfigurateException if any sort of error occurs with reading or
068     *                              parsing the configuration
069     * @since 4.0.0
070     */
071    N load(ConfigurationOptions options) throws ConfigurateException;
072
073    /**
074     * Attempts to load data from the defined source into a {@link ConfigurationReference}.
075     * The returned reference will not reload automatically.
076     *
077     * @return the created reference
078     * @throws ConfigurateException when an error occurs within the loader
079     * @see WatchServiceListener#listenToConfiguration(Function, Path) to
080     *      create an auto-reloading configuration.
081     * @since 4.0.0
082     */
083    ConfigurationReference<N> loadToReference() throws ConfigurateException;
084
085    /**
086     * Attempts to save a {@link ConfigurationNode} using this loader, to the defined sink.
087     *
088     * @param node the node to save
089     * @throws ConfigurateException if any sort of error occurs with writing or
090     *                     generating the configuration
091     * @since 4.0.0
092     */
093    void save(ConfigurationNode node) throws ConfigurateException;
094
095    /**
096     * Gets if this loader is capable of loading configurations.
097     *
098     * @return if this loader can load
099     * @since 4.0.0
100     */
101    default boolean canLoad() {
102        return true;
103    }
104
105    /**
106     * Gets if this loader is capable of saving configurations.
107     *
108     * @return if this loader can save
109     * @since 4.0.0
110     */
111    default boolean canSave() {
112        return true;
113    }
114
115}