Configuration API Reference/pl

API Konfiguracji jest zestawem narzędzie pomagającym deweloperom na szybkie przeanalizowanie i tworzenie plików konfiguracyjnych zdolnych do przeczytania i edycji przez Administratorów Serwerów. Ignorując nazwę API, można stwierdzić, że API może z powodzeniem zostać wykorzystane do przechowywania danych pluginu innych niż sama konfiguracja. Aktualnie tylko pliki YAML mogą być wykorzystane. Zostało jednak zaprojektowane jako możliwie elastyczne i miało pozwalać na inne implementacje

API Konfiguracji znajduje się w pakiecie *org.bukkit.configuration* oraz *org.bukkit.configuration.file*. Pluginy stworzone przed wersją 1.1-R5 prawdopodobnie wykorzystują starszą i inną implementację, znajdującą się w pakiecie *org.bukkit.util.configuration*. Implementacje te nie są kompatybilne ze sobą i ta starsza została usunięta.

To wprowadzenie zakłada, że masz trochę wiedzy o poprawnym programowaniu zorientowanym obiektowo, Javie oraz wewnętrznej architekturze pluginów. Ta strona nie jest substytutem dla JavaDocs klasy FileConfiguration.

## Podstawowe zagadnienia

### Obiekt

Twój plugin rozszerza JavaPlugin, a więc, poprzez to, dziedziczy jego metody. Odziedziczona metoda, getConfig zwraca obiekt typu FileConfiguration. Jest to obiekt reprezentujący plik config.yml znajdujący się w folderze Twojego pluginu.

Podczas pierwszego wywołania metody *getConfig()*, plik config.yml jest wczytywany z dysku, a domyślne wartości są wczytywane z pliku JAR pluginu. Kolejne wywołania *getConfig()* będą zwracać obiekt *FileConfiguration* znajdujący się w pamięci. Operacje wykonywane na tym obiekcie nie będą zapisywane na dysku, dopóki ich ręcznego zapisania. Idąc krok dalej, żadne modyfikacje wykonane na pliku nie zostaną uwzględnione w obiekcie. Jeśli plik *config.yml* nie istnieje na dysku, jest równy pustemu plikowi *config.yml* i wczyta pusty *FileConfiguration*.

 **Note**: lepiej jest wykorzystywać po prostu *getConfig()* niż przypisywać go do zmiennej
### Klucze

Plik konfiguracyjny jest zbudowany z wielu par klucz-wartość, gdzie kluczami są dane typu String. Wartością tych kluczy może być ConfigurationSection lub jakieś dane. Metoda *getKeys(boolean)* zwraca zestaw kluczy znajdujących się w danej *FileConfigurationSection*. Wartość typu boolean determinuje to, czy zwrócony zestaw kluczy jest rekursywny. Jeśli tak (wartość true), zwrócone zostaną wszystkie klucze i klucze potomne danej sekcji. W drugim wypadku, czyli gdy podstawiona zostanie wartość false, metoda zwróci tylko klucze zawarte w danej sekcji. Aby uzyskać klucze zawarte w danej sekcji, metoda *getKeys(boolean)* musi zostać wywołana na tej właśnie sekcji. Sekcję tą możemy uzyskać poprzez wywołanie metody *getConfigurationSection(String)*.

### Ścieżki

API konfiguracyjne wykorzystuje Ścieżki (ang. *Paths*) w celu tworzenia unikalnych par klucz-wartość. Ścieżka jest zestawem kluczy pozwalającym na zidentyfikowanie danej wartości. Klucze są oddzielone pomiędzy sobą poprzez specjalny separator, którym domyślnie jest '.' (kropka). Dla przykładu, ten plik YAML ma następujące ścieżki.

```
klucz: wartosc
jeden:
  dwa: wartosc
  trzy:
    - wartosc
    - wartosc
    - wartosc
  cztery:
    piec: wartosc
  *:
    szesc: wartosc
    siedem: wartosc
```

* klucz
* jeden
* jeden.dwa
* jeden.trzy
* jeden.cztery
* jeden.cztery.piec
* jeden.\*
* jeden.\*.szesc
* jeden.\*.siedem

### Wartości domyślne

Domyślny plik config.yml powininen być zawarty, dla wygody użytkowników, w jarze pluginu. W przypadku niekompletnego lub w ogóle brakującego pliku config.yml, wartości zostaną wczytane właśnie z tego załączonego do pluginu. Dostarczany plik musi mieć nazwę *config.yml* i znajdować się w tej samej lokalizacji co plik plugin.yml. Jego truktura powinna odzwierciedlać Twój zamysł co do konfiguracji pluginu. Plik ten może zostać skopiowany do folderu danych poprzez wywołanie metody *saveDefaultConfig()* na odpowiedniej instancji JavaPlugin.

```
this.saveDefaultConfig()
```

Jeśli dynamicznie tworzone pary klucz-wartość są wymagane jako wartości domyślne, mogą być dodane poprzez wywołania metod *addDefault(String, Object)* lub *addDefaults(Map<String, Object>).*

W niektórych wypadkach, jeśli chcesz dopisać nowe pary klucz-wartość do istniejącego pliku konfiguracyjnego, możesz ustawić wartość *copyDefaults* na true dla obiektu ConfigurationOptions.

```
this.getConfig().options().copyDefaults(true)
```

#### Tworzenie kopii pliku config.yml

Możesz skopiować domyślny plik config.yml (zawarty w jarze pluginu) wywołując metodę *saveDefaultConfig()* w klasie rozwijającej JavaPlugin. Metoda ta nie nadpisze istniejącego już pliku.