Package 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:
Commentable, Configuration, ConfigurationSection, LoadableConfiguration
public class YamlFile extends YamlConfiguration implements 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

  • Constructor Details

  • Method Details

    • 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 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, 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 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 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, 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, 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, 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 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 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, 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, 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:

    • 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 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, KeyTree.Node node)

    • load

      public void load() throws 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
      InvalidConfigurationException - if there has been an error while parsing configuration file
      FileNotFoundException - if configuration file is not found
      See Also:

    • loadWithComments

      public void loadWithComments() throws 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
      InvalidConfigurationException - if there has been an error while parsing configuration file
      FileNotFoundException - if configuration file is not found
      See Also:

    • load

      public void load(SupplierIO.Reader readerSupplier) throws IOException, 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.
      InvalidConfigurationException - Thrown when the reader does not represent a valid Configuration.
      IllegalArgumentException - Thrown when reader is null.

    • createOrLoad

      public void createOrLoad() throws IOException, 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
      InvalidConfigurationException - if there has been an error while parsing configuration file
      FileNotFoundException - if configuration file is not found
      See Also:

    • createOrLoadWithComments

      public void createOrLoadWithComments() throws IOException, 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
      InvalidConfigurationException - if there has been an error while parsing configuration file
      FileNotFoundException - if configuration file is not found
      See Also:

    • 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 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:

    • 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.
      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.
      InvalidConfigurationException - if the contents does not represent a valid Configuration.
      IllegalArgumentException - if contents is null.

    • loadConfiguration

      public static YamlFile loadConfiguration(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(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(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(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