------
 Usage
 ------
 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

Usage

* Add the library for use in Java applications

  The template for adding this library for developing Java applications
  using the pom.xml configuration maven file is described below:

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

  <<Note>>: Maven 3.0 will issue warnings if you do not specify the version of a plugin.

* Work with the Java code of the library

  After adding the library to the project you can start working with its code.\
  To get an instance of the main library interface you need to add the following code:

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

  <<<SnookerScoreAPI>>> is an interface with a set of all main methods that allow to access information 
  about the seasons, tournaments, matches, players and their ratings through entity objects.

  The library provides two implementations of the main interface:
  with caching data for players and events (tournaments) inside and without caching.
  Implementation of the interface with caching is "by default".\
  Access to each of the two implementations of the interface can be obtained by the following method calls:

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

  Further work with the library is a sequence of calls to <<<SnookerScoreAPI>>> interface methods
  to obtain lists of tournaments, players, current matches and other statistical information.\
  For example, to get information on the matches currently underway, 
  it is enough to execute the following code:

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

  Description of most interface methods can be found in the section {{{./faq.html}FAQ}},
  and the most often encountered situations are considered on the pages with examples.
  Signature of methods as well as information on other entities of the library is presented in
  {{{./apidocs/}JavaDoc}}.

* Run the library from the command line

  You can run this library from the command line to check the correctness of the connection 
  to the information portal {{{http://snooker.org/}snooker.org}}.
  Starting the library from the command line is as follows:

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

  If the launch is working correctly, you can see a list of current and upcoming snooker tournaments.\
  The sample output of the launching the library is shown below:

+-----
********************************************************************************
                    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)
********************************************************************************
+-----