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}