org.simpleyaml.configuration.file

Class YamlFile

java.lang.Object

org.simpleyaml.configuration.MemorySection

org.simpleyaml.configuration.MemoryConfiguration

org.simpleyaml.configuration.file.FileConfiguration

org.simpleyaml.configuration.file.YamlConfiguration

org.simpleyaml.configuration.file.YamlFile

All Implemented Interfaces:

org.simpleyaml.configuration.comments.Commentable, org.simpleyaml.configuration.Configuration, org.simpleyaml.configuration.ConfigurationSection, org.simpleyaml.configuration.LoadableConfiguration

public class YamlFile
extends YamlConfiguration
implements org.simpleyaml.configuration.comments.Commentable

An extension of YamlConfiguration which saves all data in Yaml to a configuration file with the added possibility to save and manage comments. Note that this implementation is not synchronized.

Author:

Carlos Lázaro Costa

Field Summary

Fields inherited from class org.simpleyaml.configuration.file.YamlConfiguration

yamlImplementation

Fields inherited from class org.simpleyaml.configuration.MemoryConfiguration

defaults, options

Fields inherited from class org.simpleyaml.configuration.MemorySection

map

Constructor Summary

Constructors

Constructor and Description
YamlFile() Builds this YamlFile without any configuration file.
YamlFile(File file) Builds this FileConfiguration with a source file.
YamlFile(String path) Builds this FileConfiguration with the file specified by path.
YamlFile(URI uri) Builds this FileConfiguration with the file specified by uri.
YamlFile(URL url) Builds this FileConfiguration with the file specified by url.
YamlFile(YamlImplementation yamlImplementation) Builds this YamlFile without any configuration file.

Method Summary

Modifier and Type	Method and Description
void	copyTo(File file) Copy this configuration file to another file, without deleting configuration file.
File	copyTo(String path) Copy this configuration file to another path, without deleting configuration file.
void	createNewFile() Creates a new empty file atomically for this configuration file if and only if it does not already exist.
void	createNewFile(boolean overwrite) Creates a new empty file atomically for this configuration file.
void	createOrLoad() If this configuration file does not exist then it is created along with missing parent directories.
void	createOrLoadWithComments() If this configuration file does not exist then it is created along with missing parent directories.
void	deleteFile() Deletes this configuration file from disk.
boolean	exists() Tests whether this configuration file exists.
String	fileToString() Returns a representation of the already saved configuration file.
String	getComment(String path) Retrieve the block comment of the section or value selected by path.
String	getComment(String path, org.simpleyaml.configuration.comments.CommentType type) Retrieve the comment of the section or value selected by path.
String	getComment(String path, org.simpleyaml.configuration.comments.CommentType type, YamlCommentFormat yamlCommentFormat) Retrieve the comment of the section or value selected by path.
String	getComment(String path, org.simpleyaml.configuration.comments.CommentType type, YamlCommentFormatter yamlCommentFormatter) Retrieve the comment of the section or value selected by path.
String	getComment(String path, YamlCommentFormat yamlCommentFormat) Retrieve the block comment of the section or value selected by path.
String	getComment(String path, YamlCommentFormatter yamlCommentFormatter) Retrieve the block comment of the section or value selected by path.
YamlCommentMapper	getCommentMapper() Get the comment mapper.
File	getConfigurationFile() Returns this configuration file where data is located.
String	getFilePath() Returns the absolute pathname string of this configuration file.
String	getFooter() Gets the footer of this configuration file.
String	getHeader() Gets the header of this configuration file.
long	getSize() Returns the size of this configuration file.
void	load() Loads configurations from this configuration file.
void	load(org.simpleyaml.utils.SupplierIO.Reader readerSupplier) Loads this YamlFile from the specified reader.
static YamlFile	loadConfiguration(File file) Creates a new YamlFile, loading from the given file (without comments).
static YamlFile	loadConfiguration(File file, boolean withComments) Creates a new YamlFile, loading from the given file.
static YamlFile	loadConfiguration(InputStream stream) Deprecated. this method loads the entire file into memory, for larger files please use loadConfiguration(SupplierIO.InputStream)
static YamlFile	loadConfiguration(InputStream stream, boolean withComments) Deprecated. this method loads the entire file into memory, for larger files please use loadConfiguration(SupplierIO.InputStream, boolean)
static YamlFile	loadConfiguration(Reader reader) Deprecated. this method loads the entire file into memory, for larger files please use loadConfiguration(SupplierIO.Reader)
static YamlFile	loadConfiguration(Reader reader, boolean withComments) Deprecated. this method loads the entire file into memory, for larger files please use loadConfiguration(SupplierIO.Reader, boolean)
static YamlFile	loadConfiguration(org.simpleyaml.utils.SupplierIO.InputStream streamSupplier) Creates a new YamlFile, loading from the given stream (without comments).
static YamlFile	loadConfiguration(org.simpleyaml.utils.SupplierIO.InputStream streamSupplier, boolean withComments) Creates a new YamlFile, loading from the given stream.
static YamlFile	loadConfiguration(org.simpleyaml.utils.SupplierIO.Reader readerSupplier) Creates a new YamlFile, loading from the given reader (without comments).
static YamlFile	loadConfiguration(org.simpleyaml.utils.SupplierIO.Reader readerSupplier, boolean withComments) Creates a new YamlFile, loading from the given reader.
static YamlFile	loadConfigurationFromString(String contents) Creates a new YamlFile, loading from the specified string contents (without comments).
static YamlFile	loadConfigurationFromString(String contents, boolean withComments) Creates a new YamlFile, loading from the specified string contents.
void	loadWithComments() Loads configurations from this configuration file including comments.
YamlFileWrapper	path(String path) Get a wrapper builder to set a value to the given path and optionally set comments.
void	save() Saves this FileConfiguration to the configuration file location.
String	saveToString() Saves this YamlFile to a string and returns it.
void	set(String path, Object value) Sets the specified path to the given value.
void	setBlankLine(String path) Set a blank line at the beginning of the block comment.
void	setComment(String path, String comment) Set a block comment above the section or value selected by path.
void	setComment(String path, String comment, org.simpleyaml.configuration.comments.CommentType type) Set a comment to the section or value selected by path.
void	setComment(String path, String comment, org.simpleyaml.configuration.comments.CommentType type, YamlCommentFormat yamlCommentFormat) Set a comment to the section or value selected by path.
void	setComment(String path, String comment, org.simpleyaml.configuration.comments.CommentType type, YamlCommentFormatter yamlCommentFormatter) Set a comment to the section or value selected by path.
void	setComment(String path, String comment, YamlCommentFormat yamlCommentFormat) Set a block comment to the section or value selected by path.
void	setComment(String path, String comment, YamlCommentFormatter yamlCommentFormatter) Set a block comment to the section or value selected by path.
void	setCommentFormat(YamlCommentFormat yamlCommentFormat) Change the comment formatter to one of the defaults provided by YamlCommentFormat.
void	setCommentFormat(YamlCommentFormatter yamlCommentFormatter) Change the comment formatter for parsing and dumping comments.
void	setConfigurationFile(File file) Rebuilds this FileConfiguration with a source file.
void	setConfigurationFile(String path) Rebuilds this FileConfiguration with the file specified by path.
void	setConfigurationFile(URI uri) Rebuilds this FileConfiguration with the file specified by uri.
void	setFooter(String footer) Sets the footer of this configuration file.
void	setHeader(String header) Sets the header that will be applied to the top of the saved output.
protected void	setListNode(Collection<?> value, org.simpleyaml.configuration.comments.KeyTree.Node node)
String	toString() Returns a representation of this configuration file.

Methods inherited from class org.simpleyaml.configuration.file.YamlConfiguration

dump, dump, get, getImplementation, load, load, load, load, loadFromString, loadHeader, options, save, set, setImplementation

Methods inherited from class org.simpleyaml.configuration.file.FileConfiguration

buildHeader, load, save, save

Methods inherited from class org.simpleyaml.configuration.MemoryConfiguration

addDefault, addDefaults, addDefaults, getDefaults, getParent, setDefaults

Methods inherited from class org.simpleyaml.configuration.MemorySection

contains, createPath, createPath, createSection, createSection, get, getBoolean, getBoolean, getBooleanList, getByteList, getCharacterList, getConfigurationSection, getCurrentPath, getDefault, getDefaultSection, getDouble, getDouble, getDoubleList, getFloatList, getInt, getInt, getIntegerList, getKeys, getList, getList, getLong, getLong, getLongList, getMapList, getMapValues, getName, getRoot, getShortList, getString, getString, getStringList, getValues, isBoolean, isConfigurationSection, isDouble, isEmpty, isInt, isList, isLong, isPrimitiveWrapper, isSet, isString, mapChildrenKeys, mapChildrenValues, size

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.simpleyaml.configuration.ConfigurationSection

contains, createSection, createSection, get, getBoolean, getBoolean, getBooleanList, getByteList, getCharacterList, getConfigurationSection, getCurrentPath, getDefaultSection, getDouble, getDouble, getDoubleList, getFloatList, getInt, getInt, getIntegerList, getKeys, getList, getList, getLong, getLong, getLongList, getMapList, getMapValues, getName, getRoot, getShortList, getString, getString, getStringList, getValues, isBoolean, isConfigurationSection, isDouble, isEmpty, isInt, isList, isLong, isSet, isString, remove, size

Constructor Detail

YamlFile

public YamlFile()

Builds this YamlFile without any configuration file.

In order to save changes you will have to use one of these methods before:
- setConfigurationFile(File)
- setConfigurationFile(String)
Or set the file when saving changes with FileConfiguration.save(File)

YamlFile

public YamlFile(YamlImplementation yamlImplementation)

Builds this YamlFile without any configuration file.

In order to save changes you will have to use one of these methods before:
- setConfigurationFile(File)
- setConfigurationFile(String)
Or set the file when saving changes with FileConfiguration.save(File)

Parameters:

yamlImplementation - the implementation to use. Default is SimpleYamlImplementation, but you can provide other like SnakeYamlImplementation or a custom implementation.

YamlFile

public YamlFile(String path)
         throws IllegalArgumentException

Builds this FileConfiguration with the file specified by path.

Parameters:

path - location for the configuration file

Throws:

IllegalArgumentException - if path is null or is a directory.
Note that if IllegalArgumentException is thrown then this configuration file will be null.

YamlFile

public YamlFile(File file)
         throws IllegalArgumentException

Builds this FileConfiguration with a source file.

Parameters:

file - the configuration file

Throws:

IllegalArgumentException - if file is null or is a directory.
Note that if IllegalArgumentException is thrown then this configuration file will be null.

YamlFile

public YamlFile(URI uri)
         throws IllegalArgumentException

Builds this FileConfiguration with the file specified by uri.

Parameters:

uri - of the configuration file

Throws:

IllegalArgumentException - if file is null or is a directory.
Note that if IllegalArgumentException is thrown then this configuration file will be null.

YamlFile

public YamlFile(URL url)
         throws IllegalArgumentException,
                URISyntaxException

Builds this FileConfiguration with the file specified by url.

Parameters:

url - of the configuration file

Throws:

URISyntaxException - if this URL is not formatted strictly according to RFC2396 and cannot be converted to a URI.

IllegalArgumentException - if file is null or is a directory.
Note that if IllegalArgumentException is thrown then this configuration file will be null.

Method Detail

save

public void save()
          throws IOException

Saves this FileConfiguration to the configuration file location.

If the file does not exist, it will be created. If already exists, it will be overwritten. If it cannot be overwritten or created, an exception will be thrown.

Comments copied will be those loaded with loadWithComments() and those added with setComment(String, String) or setComment(String, String, CommentType).

This method will use the YamlConfiguration.options() charset encoding, which defaults to UTF8.

Throws:

IOException - if it hasn't been possible to save configuration file

IllegalArgumentException - if the configuration file is not set

saveToString

public String saveToString()
                    throws IOException

Saves this YamlFile to a string and returns it.

Comments copied will be those loaded with loadWithComments() and those added with setComment(String, String) or setComment(String, String, CommentType).

Specified by:

saveToString in interface org.simpleyaml.configuration.LoadableConfiguration

Overrides:

saveToString in class YamlConfiguration

Returns:

String containing this configuration with comments.

Throws:

IOException - if it hasn't been possible to save configuration file

setComment

public void setComment(String path,
                       String comment,
                       org.simpleyaml.configuration.comments.CommentType type)

Set a comment to the section or value selected by path. Comment will be indented automatically. Multi-line comments can be provided using \n character.

Comment format will follow the rules of YamlConfiguration.options() YamlConfigurationOptions.commentFormatter().

Specified by:

setComment in interface org.simpleyaml.configuration.comments.Commentable

Parameters:

path - path of desired section or key

comment - the comment to add, # prefix is not needed

type - either above (BLOCK) or SIDE

setComment

public void setComment(String path,
                       String comment)

Set a block comment above the section or value selected by path. Comment will be indented automatically. Multi-line comments can be provided using \n character.

Comment format will follow the rules of YamlConfiguration.options() YamlConfigurationOptions.commentFormatter().

Specified by:

setComment in interface org.simpleyaml.configuration.comments.Commentable

Parameters:

path - path of desired section or key

comment - the block comment to add, # character is not needed

setComment

public void setComment(String path,
                       String comment,
                       org.simpleyaml.configuration.comments.CommentType type,
                       YamlCommentFormatter yamlCommentFormatter)

Set a comment to the section or value selected by path. Comment will be indented automatically. Multi-line comments can be provided using \n character.

Comment format will follow the rules of the provided YamlCommentFormatter.

Parameters:

path - path of desired section or key

comment - the comment to add, # prefix is not needed

type - either above (BLOCK) or SIDE

yamlCommentFormatter - the comment formatter to use

setComment

public void setComment(String path,
                       String comment,
                       org.simpleyaml.configuration.comments.CommentType type,
                       YamlCommentFormat yamlCommentFormat)

Set a comment to the section or value selected by path. Comment will be indented automatically. Multi-line comments can be provided using \n character.

Comment format will follow the rules of the provided YamlCommentFormat.

Parameters:

path - path of desired section or key

comment - the comment to add, # prefix is not needed

type - either above (BLOCK) or SIDE

yamlCommentFormat - the comment format to use

setComment

public void setComment(String path,
                       String comment,
                       YamlCommentFormatter yamlCommentFormatter)

Set a block comment to the section or value selected by path. Comment will be indented automatically. Multi-line comments can be provided using \n character.

Comment format will follow the rules of the provided YamlCommentFormatter.

Parameters:

path - path of desired section or key

comment - the block comment to add, # prefix is not needed

yamlCommentFormatter - the comment formatter to use

setComment

public void setComment(String path,
                       String comment,
                       YamlCommentFormat yamlCommentFormat)

Set a block comment to the section or value selected by path. Comment will be indented automatically. Multi-line comments can be provided using \n character.

Comment format will follow the rules of the provided YamlCommentFormat.

Parameters:

path - path of desired section or key

comment - the block comment to add, # prefix is not needed

yamlCommentFormat - the comment format to use

setBlankLine

public void setBlankLine(String path)

Set a blank line at the beginning of the block comment. If currently there is no block comment for the provided path then it sets "\n" as the block comment.

Parameters:

path - path of desired section or key

getComment

public String getComment(String path,
                         org.simpleyaml.configuration.comments.CommentType type)

Retrieve the comment of the section or value selected by path.

Comment format will follow the rules of YamlConfiguration.options() YamlConfigurationOptions.commentFormatter().

Specified by:

getComment in interface org.simpleyaml.configuration.comments.Commentable

Parameters:

path - path of desired section or key

type - either above (BLOCK) or SIDE

Returns:

the comment of the section or value selected by path, or null if that path does not have any comment of this type

getComment

public String getComment(String path)

Retrieve the block comment of the section or value selected by path.

Comment format will follow the rules of YamlConfiguration.options() YamlConfigurationOptions.commentFormatter().

Specified by:

getComment in interface org.simpleyaml.configuration.comments.Commentable

Parameters:

path - path of desired section or key

Returns:

the block comment of the section or value selected by path, or null if that path does not have any comment of type block

getComment

public String getComment(String path,
                         org.simpleyaml.configuration.comments.CommentType type,
                         YamlCommentFormatter yamlCommentFormatter)

Retrieve the comment of the section or value selected by path.

Comment format will follow the rules of the provided YamlCommentFormatter.

Parameters:

path - path of desired section or key

type - either above (BLOCK) or SIDE

yamlCommentFormatter - the comment formatter to use

Returns:

the comment of the section or value selected by path, or null if that path does not have any comment of this type

getComment

public String getComment(String path,
                         org.simpleyaml.configuration.comments.CommentType type,
                         YamlCommentFormat yamlCommentFormat)

Retrieve the comment of the section or value selected by path.

Comment format will follow the rules of the provided YamlCommentFormat.

Parameters:

path - path of desired section or key

type - either above (BLOCK) or SIDE

yamlCommentFormat - the comment format to use

Returns:

the comment of the section or value selected by path, or null if that path does not have any comment of this type

getComment

public String getComment(String path,
                         YamlCommentFormatter yamlCommentFormatter)

Retrieve the block comment of the section or value selected by path.

Comment format will follow the rules of the provided YamlCommentFormatter.

Parameters:

path - path of desired section or key

yamlCommentFormatter - the comment formatter to use

Returns:

the block comment of the section or value selected by path, or null if that path does not have any comment of type block

getComment

public String getComment(String path,
                         YamlCommentFormat yamlCommentFormat)

Retrieve the block comment of the section or value selected by path.

Comment format will follow the rules of the provided YamlCommentFormat.

Parameters:

path - path of desired section or key

yamlCommentFormat - the comment format to use

Returns:

the block comment of the section or value selected by path, or null if that path does not have any comment of type block

setCommentFormat

public void setCommentFormat(YamlCommentFormat yamlCommentFormat)

Change the comment formatter to one of the defaults provided by YamlCommentFormat.

This will change the behaviour for parsing comments with getComment(String, CommentType) and for dumping comments with setComment(String, String, CommentType). If default behaviour does not suits you then change the format before calling one of these methods.

Parameters:

yamlCommentFormat - desired format to set/dump and get/parse comments

setCommentFormat

public void setCommentFormat(YamlCommentFormatter yamlCommentFormatter)

Change the comment formatter for parsing and dumping comments. This is a shortcut to YamlConfiguration.options() YamlConfigurationOptions.commentFormatter(YamlCommentFormatter).

This will change the behaviour for parsing comments with getComment(String, CommentType) and for dumping comments with setComment(String, String, CommentType).

Parameters:

yamlCommentFormatter - desired formatter to set/dump and get/parse comments

getHeader

public String getHeader()

Gets the header of this configuration file.

The string format will respect the rules of the YamlConfiguration.options() YamlConfigurationOptions.headerFormatter(). By default the YamlHeaderFormatter is used and the result string will not have a blank line at the end.

Null is a valid value which will indicate that no header is applied. The default value is null.

Returns:

header

setHeader

public void setHeader(String header)

Sets the header that will be applied to the top of the saved output. This is a shortcut to YamlConfiguration.options() YamlConfigurationOptions.header(String).

This header will be commented out and applied directly at the top of the generated output of this configuration file.

The rules of YamlConfiguration.options() YamlConfigurationOptions.headerFormatter() will be respected. By default the YamlHeaderFormatter is used and the header will have a blank line written at the end of the header in the file. It is not required to include a newline at the end of the header as it will automatically be applied, but you may include one if you wish for extra spacing.

Null is a valid value which will indicate that no header is to be applied.

Parameters:

header - New header

getFooter

public String getFooter()

Gets the footer of this configuration file. This is a shortcut to getComment(String) with null path.

The string format will respect the rules of the YamlConfiguration.options() YamlConfigurationOptions.commentFormatter().

Null is a valid value which will indicate that no footer is applied. The default value is null.

Returns:

the footer comment at the end of the file

setFooter

public void setFooter(String footer)

Sets the footer of this configuration file. This is a shortcut to setComment(String, String) with null path.

This footer will be commented out and applied at the bottom of the generated output of this configuration file. The end of the file will have a new line character '\n'. The rules of YamlConfiguration.options() YamlConfigurationOptions.commentFormatter() will be respected.

Null is a valid value which will indicate that no footer is applied.

Parameters:

footer - the footer comment to write at the end of the file

path

public YamlFileWrapper path(String path)

Get a wrapper builder to set a value to the given path and optionally set comments.

This is an alternative API for the following pattern:

 
 yamlFile.set("test.hello", "Hello");
 yamlFile.setComment("test.hello", "Block comment");
 yamlFile.setComment("test.hello", "Side comment", CommentType.SIDE);
 
 

You can achieve the same with:

 
 yamlFile.path("test.hello")
         .set("Hello")
         .comment("Block comment")
         .commentSide("Side comment");
 
 

Parameters:

path - path of the object or configuration to set

Returns:

the wrapper builder

getCommentMapper

public YamlCommentMapper getCommentMapper()

Get the comment mapper. This has access to read the comment nodes directly.

Returns:

the comment mapper or null if this configuration is loaded without comments

See Also:

getComment(String, CommentType), setComment(String, String, CommentType)

set

public void set(String path,
                Object value)

Description copied from class: YamlConfiguration

Sets the specified path to the given value.

If value is null, the entry will be removed. Any existing entry will be replaced, regardless of what the new value is.

Some implementations may have limitations on what you may store. See their individual javadocs for details. No implementations should allow you to store Configurations or ConfigurationSections, please use MemorySection.createSection(String) for that.

Specified by:

set in interface org.simpleyaml.configuration.ConfigurationSection

Overrides:

set in class YamlConfiguration

Parameters:

path - Path of the object to set.

value - New value to set the path to.

setListNode

protected void setListNode(Collection<?> value,
                           org.simpleyaml.configuration.comments.KeyTree.Node node)

load

public void load()
          throws org.simpleyaml.exceptions.InvalidConfigurationException,
                 IOException

Loads configurations from this configuration file.

This method will use the YamlConfiguration.options() charset encoding, which defaults to UTF8.

Note that this method will not load comments of original configuration file, if needed use loadWithComments() instead.

Throws:

IOException - if it hasn't been possible to load file

org.simpleyaml.exceptions.InvalidConfigurationException - if there has been an error while parsing configuration file

FileNotFoundException - if configuration file is not found

See Also:

loadWithComments()

loadWithComments

public void loadWithComments()
                      throws org.simpleyaml.exceptions.InvalidConfigurationException,
                             IOException

Loads configurations from this configuration file including comments.

This method will use the YamlConfiguration.options() charset encoding, which defaults to UTF8.

Use load() instead to improve performance when configuration file has no comments or don't need it.

Throws:

IOException - if it hasn't been possible to load file

org.simpleyaml.exceptions.InvalidConfigurationException - if there has been an error while parsing configuration file

FileNotFoundException - if configuration file is not found

See Also:

load()

load

public void load(org.simpleyaml.utils.SupplierIO.Reader readerSupplier)
          throws IOException,
                 org.simpleyaml.exceptions.InvalidConfigurationException

Loads this YamlFile from the specified reader.

All the values contained within this configuration will be removed, leaving only settings and defaults, and the new values will be loaded from the given stream.

If the file cannot be loaded for any reason, an exception will be thrown.

Overrides:

load in class YamlConfiguration

Parameters:

readerSupplier - a function providing the reader to load from (new instance)

Throws:

IOException - Thrown when underlying reader throws an IOException.

org.simpleyaml.exceptions.InvalidConfigurationException - Thrown when the reader does not represent a valid Configuration.

IllegalArgumentException - Thrown when reader is null.

createOrLoad

public void createOrLoad()
                  throws IOException,
                         org.simpleyaml.exceptions.InvalidConfigurationException

If this configuration file does not exist then it is created along with missing parent directories.

Otherwise loads configurations from this configuration file.

This method will use the YamlConfiguration.options() charset encoding, which defaults to UTF8.

Throws:

IOException - if it hasn't been possible to load file

org.simpleyaml.exceptions.InvalidConfigurationException - if there has been an error while parsing configuration file

FileNotFoundException - if configuration file is not found

See Also:

createOrLoadWithComments()

createOrLoadWithComments

public void createOrLoadWithComments()
                              throws IOException,
                                     org.simpleyaml.exceptions.InvalidConfigurationException

If this configuration file does not exist then it is created along with missing parent directories.

Otherwise loads configurations from this configuration file, including comments.

This method will use the YamlConfiguration.options() charset encoding, which defaults to UTF8.

Throws:

IOException - if it hasn't been possible to load file

org.simpleyaml.exceptions.InvalidConfigurationException - if there has been an error while parsing configuration file

FileNotFoundException - if configuration file is not found

See Also:

createOrLoad()

exists

public boolean exists()

Tests whether this configuration file exists.

Returns:

true if and only if this configuration file exists; false otherwise

createNewFile

public void createNewFile(boolean overwrite)
                   throws IOException

Creates a new empty file atomically for this configuration file.

Parent directories will be created if they do not exist.

Parameters:

overwrite - indicates if file must be overwritten if it already exists. Note that if overwrite is set to false and there is already a file with that path file will not be created and no exception is thrown.

Throws:

IOException - if I/O error occurs creating the configuration file

createNewFile

public void createNewFile()
                   throws IOException

Creates a new empty file atomically for this configuration file if and only if it does not already exist.

Parent directories will be created if they do not exist.

Throws:

IOException - if I/O error occurs creating the configuration file

deleteFile

public void deleteFile()
                throws IOException

Deletes this configuration file from disk.

Throws:

IOException - if file cannot be deleted

getSize

public long getSize()

Returns the size of this configuration file.

Returns:

the size, in bytes, of this configuration file.

getFilePath

public String getFilePath()

Returns the absolute pathname string of this configuration file.

Returns:

the absolute path where configuration file is located.

getConfigurationFile

public File getConfigurationFile()

Returns this configuration file where data is located.

Returns:

the configuration file where this FileConfiguration writes.

setConfigurationFile

public void setConfigurationFile(String path)
                          throws IllegalArgumentException

Rebuilds this FileConfiguration with the file specified by path.

Parameters:

path - location for the configuration file

Throws:

IllegalArgumentException - if path is null or is a directory.
Note that if IllegalArgumentException is thrown then this configuration file will be null.

setConfigurationFile

public void setConfigurationFile(URI uri)
                          throws IllegalArgumentException

Rebuilds this FileConfiguration with the file specified by uri.

Parameters:

uri - of the configuration file

Throws:

IllegalArgumentException - if file is null or is a directory.
Note that if IllegalArgumentException is thrown then this configuration file will be null.

setConfigurationFile

public void setConfigurationFile(File file)
                          throws IllegalArgumentException

Rebuilds this FileConfiguration with a source file.

Parameters:

file - the configuration file

Throws:

IllegalArgumentException - if file is null or is a directory.
Note that if IllegalArgumentException is thrown then this configuration file will be null.

copyTo

public File copyTo(String path)
            throws FileNotFoundException,
                   IllegalArgumentException,
                   IOException

Copy this configuration file to another path, without deleting configuration file. If there is already a file on the other path it will be overwritten.

Parameters:

path - the location of the new file, including name (mustn't be a directory)

Returns:

the new copied file

Throws:

FileNotFoundException - if configuration file is not found as source to copy

IllegalArgumentException - if path is a directory or it is null

IOException - if there I/O error occurs copying file

copyTo

public void copyTo(File file)
            throws FileNotFoundException,
                   IllegalArgumentException,
                   IOException

Copy this configuration file to another file, without deleting configuration file.

Parameters:

file - destination file (mustn't be a directory)

Throws:

FileNotFoundException - if configuration file is not found as source to copy

IllegalArgumentException - if path is a directory or it is null

IOException - if there I/O error occurs copying file

fileToString

public String fileToString()
                    throws IOException

Returns a representation of the already saved configuration file.

Returns:

the configuration file disk contents, or null if the file does not exist

Throws:

IOException - if configuration file cannot be read

toString

public String toString()

Returns a representation of this configuration file.

Overrides:

toString in class org.simpleyaml.configuration.MemorySection

Returns:

a representation of this configuration file
If something goes wrong then this string is an error message.

loadConfiguration

public static YamlFile loadConfiguration(File file,
                                         boolean withComments)
                                  throws IOException

Creates a new YamlFile, loading from the given file.

This method will use the YamlConfiguration.options() charset encoding, which defaults to UTF8.

Parameters:

file - Input file

withComments - if comments should be parsed

Returns:

Resulting configuration

Throws:

IOException - if configuration cannot be loaded

IllegalArgumentException - if file is null

loadConfiguration

public static YamlFile loadConfiguration(File file)
                                  throws IOException

Creates a new YamlFile, loading from the given file (without comments).

This method will use the YamlConfiguration.options() charset encoding, which defaults to UTF8.

Parameters:

file - Input file

Returns:

Resulting configuration

Throws:

IOException - if configuration cannot be loaded

IllegalArgumentException - if file is null

See Also:

loadConfiguration(File, boolean)

loadConfigurationFromString

public static YamlFile loadConfigurationFromString(String contents,
                                                   boolean withComments)
                                            throws IOException

Creates a new YamlFile, loading from the specified string contents.

If the file cannot be loaded for any reason, an exception will be thrown.

Parameters:

contents - the contents to load from

withComments - if comments should be parsed

Returns:

resulting configuration

Throws:

IOException - if underlying reader throws an IOException.

org.simpleyaml.exceptions.InvalidConfigurationException - if the contents does not represent a valid Configuration.

IllegalArgumentException - if contents is null.

loadConfigurationFromString

public static YamlFile loadConfigurationFromString(String contents)
                                            throws IOException

Creates a new YamlFile, loading from the specified string contents (without comments).

If the file cannot be loaded for any reason, an exception will be thrown.

Parameters:

contents - the contents to load from

Returns:

resulting configuration

Throws:

IOException - if underlying reader throws an IOException.

org.simpleyaml.exceptions.InvalidConfigurationException - if the contents does not represent a valid Configuration.

IllegalArgumentException - if contents is null.

loadConfiguration

public static YamlFile loadConfiguration(org.simpleyaml.utils.SupplierIO.Reader readerSupplier,
                                         boolean withComments)
                                  throws IOException

Creates a new YamlFile, loading from the given reader.

Parameters:

readerSupplier - reader supplier

withComments - if comments should be parsed

Returns:

resulting configuration

Throws:

IOException - if configuration cannot be loaded

IllegalArgumentException - if stream is null

loadConfiguration

public static YamlFile loadConfiguration(org.simpleyaml.utils.SupplierIO.Reader readerSupplier)
                                  throws IOException

Creates a new YamlFile, loading from the given reader (without comments).

Parameters:

readerSupplier - reader supplier

Returns:

resulting configuration

Throws:

IOException - if configuration cannot be loaded

IllegalArgumentException - if stream is null

loadConfiguration

public static YamlFile loadConfiguration(org.simpleyaml.utils.SupplierIO.InputStream streamSupplier,
                                         boolean withComments)
                                  throws IOException

Creates a new YamlFile, loading from the given stream.

This method will use the YamlConfiguration.options() charset encoding, which defaults to UTF8.

Parameters:

streamSupplier - input stream supplier

withComments - if comments should be parsed

Returns:

Resulting configuration

Throws:

IOException - if configuration cannot be loaded

IllegalArgumentException - if stream is null

loadConfiguration

public static YamlFile loadConfiguration(org.simpleyaml.utils.SupplierIO.InputStream streamSupplier)
                                  throws IOException

Creates a new YamlFile, loading from the given stream (without comments).

This method will use the YamlConfiguration.options() charset encoding, which defaults to UTF8.

Parameters:

streamSupplier - input stream supplier

Returns:

Resulting configuration

Throws:

IOException - if configuration cannot be loaded

IllegalArgumentException - if stream is null

loadConfiguration

@Deprecated
public static YamlFile loadConfiguration(InputStream stream,
                                                     boolean withComments)
                                              throws IOException

Deprecated. this method loads the entire file into memory, for larger files please use loadConfiguration(SupplierIO.InputStream, boolean)

Throws:

IOException

loadConfiguration

@Deprecated
public static YamlFile loadConfiguration(InputStream stream)
                                              throws IOException

Deprecated. this method loads the entire file into memory, for larger files please use loadConfiguration(SupplierIO.InputStream)

Throws:

IOException

loadConfiguration

@Deprecated
public static YamlFile loadConfiguration(Reader reader,
                                                     boolean withComments)
                                              throws IOException

Deprecated. this method loads the entire file into memory, for larger files please use loadConfiguration(SupplierIO.Reader, boolean)

Throws:

IOException

loadConfiguration

@Deprecated
public static YamlFile loadConfiguration(Reader reader)
                                              throws IOException

Deprecated. this method loads the entire file into memory, for larger files please use loadConfiguration(SupplierIO.Reader)

Throws:

IOException