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.

Warning:

jeśli przydzielasz obiekt zwrócony przez getConfig(), NIE przydzielaj go do statycznego pola

Warning:

jeśli zrobisz powyższe, przydziel getConfig() do zmiennej PONOWNIE po reloadConfig.

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.