/*
 *  @author Ranides Atterwim <ranides@gmail.com>
 *  @copyright Ranides Atterwim
 *  @license WTFPL
 *  @url http://ranides.net/projects/assira
 */

package net.ranides.assira.config;

import net.ranides.assira.events.EventRouter;

/**
 * <p>
 * Interfejs reprezentujący konfigurację, którą można nie tylko czytać i modyfikować,
 * ale również obserwować zmiany (obsługuje klasyczny model zdarzeń assira).
 * </p><p>
 * Każda klasa implementująca interfejs powinna udostępniać konstruktor pobierający
 * nazwę konfiguracji i opcjonalnie dokonywać w nim pierwszego ładowania danych.
 * Metody load i save są opcjonalne i wywoływane przez użytkownika w celu odświeżenia/ sychronizacji
 * danych z fizycznym nośnikiem.
 * </p><p>
 * Uwaga! Wielokrotne utworzenie konfiguracji za pomocą {@link ConfigService} zwróci
 * poprzednią instancję tak długo, jak gdziekolwiek w programie będzie istnieć referencja
 * do niej. Z tego względu każda niezależna część aplikacji, która chce mieć
 * gwarancję, że wprowadzane przez nią zmiany będą globalnie widoczne, musi
 * przechowywać referencję do wyniku. Innymi słowy, z {@link Configuration} należy
 * postępować identycznie jak z {@link java.util.logging.Logger}.
 * </p>
 * @author ranides
 */
public interface Configuration extends Branch, EventRouter {

    /**
     * Abstrakcyjna ścieżka do załadowanej konfiguracji
     * @return
     */
    String resource();

    /**
     * Ładuje konfigurację z persistent storage
     * @return
     * @throws ConfigException
     */
    Configuration load() throws ConfigException;

    /**
     * Zapisuje konfigurację do persistent storage
     * @return
     * @throws ConfigException
     */
    Configuration save() throws ConfigException;

}
