------
 Working with the cached version API
 ------
 Dmitry Samoshin aka gotty
 ------
 2017-01-27
 ------

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

Working with the cached version API

  When you first call the API method to get the main interface of the library

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

  by default we get the cached implementation of the API interface <<<SnookerScoreAPI>>>.\
  What are its advantages?

===

  Firstly, when using the cached version of the interface for various queries, you get a full range 
  of useful information. For example, when requesting current matches, the sample will contain 
  links to the tournament (object <<<Event>>>) as well as to the players 
  participating in each match (objects <<<Player>>>) in addition to other information:

+-------
SnookerScoreAPI api = Snooker.API();
OngoingMatches matches = api.getOngoingMatches();
for (OngoingMatch match : matches) {
    Event event = match.event();
    Player player1 = match.player1();
    Player player2 = match.player2();
}
+-------

  Whereas when working with the noncached version of the interface, you will have to make 
  additional queries about the tournament and players in order to get full information 
  about the ongoing matches:

+-------
SnookerScoreAPI api = Snooker.uncachedAPI();
OngoingMatches matches = api.getOngoingMatches();
for (OngoingMatch match : matches) {
    Event event = api.getEvent(match.eventId());
    Player player1 = api.getPlayer(match.player1Id());
    Player player2 = api.getPlayer(match.player2Id());
}
+-------

===

  Secondly, in the cached version of the interface, you are given the opportunity to specify 
  the current season, with the events of which in the future you are going to work 
  by requesting tournaments and matches:

+-------
SnookerScoreAPI api = Snooker.API();
api.setCurrentSeason(Season.getSeason(2015));
+-------

===

  P.S. If you need to use the noncached version of the API, you can get it as follows:

+-------
SnookerScoreAPI uncachedApi = Snooker.uncachedAPI();
+-------