------
 Использование
 ------
 Dmitry Samoshin aka gotty
 ------
 2017-01-22
 ------

~~ Copyright (c) 2017. Developed by Hedgecode.
~~
~~ Licensed under the Apache License, Version 2.0 (the "License");
~~ you may not use this file except in compliance with the License.
~~ You may obtain a copy of the License at
~~
~~   http://www.apache.org/licenses/LICENSE-2.0
~~
~~ Unless required by applicable law or agreed to in writing, software
~~ distributed under the License is distributed on an "AS IS" BASIS,
~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
~~ See the License for the specific language governing permissions and
~~ limitations under the License.

~~ NOTE: For help with the syntax of this file, see:
~~ http://maven.apache.org/doxia/references/apt-format.html

Использование

* Подключение библиотеки для использования в Java-приложениях

  Шаблон подключения данной библиотеки для разработки Java-приложений с
  использованием конфигурационного Maven-файла pom.xml представлен ниже:

+-----
<project>
    ...
    <dependencies>
        <dependency>
            <groupId>${project.groupId}</groupId>
            <artifactId>${project.artifactId}</artifactId>
            <version>${project.version}</version>
        </dependency>
    </dependencies>
    ...
</project>
+-----

  <<Примечание>>: Maven 3.0 будет выдавать предупреждение,
  если вы не укажите версию плагина.

* Работа с Java-кодом библиотеки

  После подключения библиотеки к проекту можно начинать работать с её кодом.\
  Для того, чтобы получить экземпляр основного интерфейса библиотеки, нужно 
  выполнить следующий код:

+-----
SnookerScoreAPI api = Snooker.API();
+-----

  <<<SnookerScoreAPI>>> представляет собой интерфейс с набором всех основных методов,
  которые позволяют через объекты-сущности получить доступ к информации о сезонах,
  турнирах, матчах, игроках и их рейтингах.
  
  Библиотека предоставляет две реализации вышеуказанного интерфейса: с кэшированием
  данных по игрокам и событиям (турнирам) внутри библиотеки и без кэширования.
  Реализация интерфейса с кэшированием является реализацией "по умолчанию".\
  Доступ к каждой из двух реализаций интерфейса может быть получен путём выполнения
  следующих вызовов:

+-----
SnookerScoreAPI cachedApi = Snooker.cachedAPI(); /* API with cache */
...
SnookerScoreAPI uncachedApi = Snooker.uncachedAPI(); /* API without cache */
+-----

  Дальнейшая работа с библиотекой представляет собой последовательность вызовов методов
  интерфейса <<<SnookerScoreAPI>>> для получения списков турниров, игроков, текущих матчей
  и прочей статистической информации.\
  Например, чтобы получить информацию по матчам, проходящим в данный момент, достаточно
  выполнить следующий код:

+-----
SnookerScoreAPI api = Snooker.API();
OngoingMatches matches = api.getOngoingMatches();
+-----

  Описание работы большинства методов интерфейса можно найти в разделе {{{./faq.html}ЧаВо}},
  а на страницах с примерами рассмотрены наиболее часто встречающиеся ситуации.
  Сигнатура методов, а также информация по другим сущностям библиотеки, представлена в
  {{{./apidocs/}JavaDoc}}.

* Запуск библиотеки из командной строки

  В данной библиотеке имеется возможность произвести запуск из командной строки для проверки
  корректности соединения с информационным порталом {{{http://snooker.org/}snooker.org}}.
  Запуск библиотеки из командной строки осуществляется следующим образом:

+-----
java -jar ${project.artifactId}-${project.version}.jar
+-----

  Если программа отработает корректно, то можно будет увидеть список текущих и предстоящих
  турниров по снукеру.\  
  Примерный результат вывода программы представлен ниже:

+-----
********************************************************************************
                    Welcome to Hedgecode Snooker Score API!
                -----------------------------------------------
         It is an API library for portal snooker.org, which contains
      the results of snooker competitions and other snooker information.
    This library provides a set of entity objects that can be used in client
    applications (to inform about the results of snooker), developed in Java.
********************************************************************************
  Current Snooker Events:
     China Open Qualifiers [24.01.2017 - 27.01.2017] (England, Preston)
********************************************************************************
  Upcoming Snooker Events:
     German Masters [01.02.2017 - 05.02.2017] (Germany, Berlin)
     World Grand Prix [06.02.2017 - 12.02.2017] (England, Preston)
     Welsh Open [13.02.2017 - 19.02.2017] (Wales, Cardiff)
     Connie Gough Memorial Trophy [18.02.2017 - 18.02.2017] (England, Dunstable)
     Championship League - Group 5 [20.02.2017 - 21.02.2017] (England, Coventry)
********************************************************************************
+-----