Module org.tquadrat.foundation.inifile
Package org.tquadrat.foundation.inifile

Interface INIFile

All Known Implementing Classes:
INIFileImpl
@ClassVersion(sourceVersion="$Id: INIFile.java 1128 2024-04-06 07:17:56Z tquadrat $") @API(status=STABLE, since="0.1.0") public sealed interface INIFile permits INIFileImpl
The API for the access to Windows-style configuration files.
Note:
  • Changes will not be persisted automatically!
Author:
Thomas Thrien (thomas.thrien@tquadrat.org)
Version:
$Id: INIFile.java 1128 2024-04-06 07:17:56Z tquadrat $
Since:
0.1.0
UML Diagram
UML Diagram for "org.tquadrat.foundation.inifile.INIFile"⁠

UML Diagram for "org.tquadrat.foundation.inifile.INIFile"

UML Diagram for "org.tquadrat.foundation.inifile.INIFile"⁠

  • Field Details

  • Method Details

    • addComment

      void addComment(String comment)

      Adds the given comment to the INI file.

      The new comment will be appended to an already existing one.

      Parameters:
      comment - The comment.

    • addComment

      void addComment(String group, String comment)

      Adds the given comment to the given group.

      The new comment will be appended to an already existing one.

      Parameters:
      group - The group.
      comment - The comment.

    • addComment

      void addComment(String group, String key, String comment)

      Adds the given comment to the value that is identified by the given group and key.

      The new comment will be appended to an already existing one.

      Parameters:
      group - The group.
      key - The key for the value.
      comment - The comment.

    • create

      static INIFile create(Path file) throws IOException

      Creates an empty INI file. If the file already exists, it will be overwritten without notice.

      The given file is used to store the value on a call to save().

      Parameters:
      file - The file.
      Returns:
      The new instance.
      Throws:
      IOException - The file cannot be created.

    • getValue

      Optional<String> getValue(String group, String key)
      Retrieves the value for the given key from the given group.
      Parameters:
      group - The group.
      key - The key for the value.
      Returns:
      An instance of Optional that holds the retrieved value.

    • getValue

      default String getValue(String group, String key, String defaultValue)
      Retrieves the value for the given key from the given group.
      Parameters:
      group - The group.
      key - The key for the value.
      defaultValue - The value that will be returned if no other value could be found; can be null.
      Returns:
      The value.

    • getValue

      <T> Optional<T> getValue(String group, String key, StringConverter<? extends T> stringConverter)
      Retrieves the value for the given key from the given group.
      Type Parameters:
      T - The target type.
      Parameters:
      group - The group.
      key - The key for the value.
      stringConverter - The implementation of StringConverter that is used to convert the stored value into the target type.
      Returns:
      An instance of Optional that holds the retrieved value.

    • getValue

      default <T> T getValue(String group, String key, StringConverter<T> stringConverter, T defaultValue)
      Retrieves the value for the given key from the given group.
      Type Parameters:
      T - The target type.
      Parameters:
      group - The group.
      key - The key for the value.
      stringConverter - The implementation of StringConverter that is used to convert the stored value into the target type.
      defaultValue - The value that will be returned if no other value could be found; can be null.
      Returns:
      The value.

    • hasGroup

      boolean hasGroup(String group)

      Checks whether the INI file contains a group with the given name.

      This method will not throw an exception for an invalid group name; instead it returns false.

      Parameters:
      group - The group.
      Returns:
      true if there is a group with the given name, false otherwise.

    • hasValue

      boolean hasValue(String group, String key)

      Checks whether the INI file contains an entry with the given key.

      This method will not throw an exception for an invalid group name or an invalid key; instead it returns false.

      Parameters:
      group - The group.
      key - The key.
      Returns:
      true if there is an entry with the given key, false otherwise.

    • listEntries

      Collection<INIFile.Entry> listEntries()
      Returns all entries of the INI file.
      Returns:
      The entries.

    • loadEntries

      default void loadEntries(INIFile.Entry... entries)
      Loads the entries for the INI file.
      Parameters:
      entries - The entries.

    • loadEntries

      default void loadEntries(Collection<INIFile.Entry> entries)
      Loads the entries for the INI file.
      Parameters:
      entries - The entries.

    • open

      static INIFile open(Path file) throws IOException
      Opens the given INI file and reads its contents. If the file does not exist yet, a new, empty file will be created.
      Parameters:
      file - The file.
      Returns:
      The new instance.
      Throws:
      IOException - A problem occurred when reading the file.

    • refresh

      void refresh() throws IOException
      Re-reads the values.
      Throws:
      IOException - A problem occurred when reading the file.

    • save

      void save() throws IOException
      Saves the contents of the INI file to the file that was provided to create(Path) or open(Path). This method has to be called to persist any changes made to the contents of the INI file.
      Throws:
      IOException - A problem occurred when writing the contents to the file.

    • setComment

      @API(status=STABLE, since="0.4.3") void setComment(String comment)

      Sets the given comment to the INI file.

      The new comment will replace any already existing comment.

      Parameters:
      comment - The comment.
      Since:
      0.4.3

    • setComment

      @API(status=STABLE, since="0.4.3") void setComment(String group, String comment)

      Sets the given comment to the given group.

      The new comment will replace any already existing comment.

      Parameters:
      group - The group.
      comment - The comment.
      Since:
      0.4.3

    • setComment

      @API(status=STABLE, since="0.4.3") void setComment(String group, String key, String comment)

      Sets the given comment to the value that is identified by the given group and key.

      The new comment will replace any already existing comment.

      Parameters:
      group - The group.
      key - The key for the value.
      comment - The comment.
      Since:
      0.4.3

    • setValue

      void setValue(String group, String key, String value)
      Stores the given value with the given key to the given group.
      Parameters:
      group - The group.
      key - The key.
      value - The value.

    • setValue

      default <S> void setValue(String group, String key, S value, StringConverter<S> stringConverter)
      Stores the given value with the given key to the given group.
      Type Parameters:
      S - The source type for the value.
      Parameters:
      group - The group.
      key - The key.
      value - The value.
      stringConverter - The instance of StringConverter that is used to convert the value to a String.