[LIB-5] Site sources of snooker-score-api

author gotty <gotty@fb0bcced-7025-49ed-a12f-f98bce993226>

Fri, 2 Jun 2017 13:01:00 +0000 (13:01 +0000)

committer gotty <gotty@fb0bcced-7025-49ed-a12f-f98bce993226>

Fri, 2 Jun 2017 13:01:00 +0000 (13:01 +0000)
author gotty <gotty@fb0bcced-7025-49ed-a12f-f98bce993226>
Fri, 2 Jun 2017 13:01:00 +0000 (13:01 +0000)
committer gotty <gotty@fb0bcced-7025-49ed-a12f-f98bce993226>
Fri, 2 Jun 2017 13:01:00 +0000 (13:01 +0000)
diff --git a/sample.txt b/sample.txt

new file mode 100644 (file)

index 0000000..2786210
--- /dev/null
+++ b/sample.txt
@@ -0,0 +1,159 @@
+Event
+[
+{
+"ID": 398,
+"Name": "Shanghai Masters Qualifiers",
+"StartDate": "2015-08-05",
+"EndDate": "2015-08-09",
+"Sponsor": "Bank of Communications OTO",
+"Season": 2015,
+"Type": "Qualifying",
+"Num": 0,
+"Venue": "Barnsley Metrodome",
+"City": "Barnsley",
+"Country": "England",
+"Discipline": "snooker",
+"Main": 403,
+"Sex": "Both",
+"AgeGroup": "O",
+"Url": "",
+"Related": "shanghai",
+"Stage": "Q",
+"ValueType": "SM",
+"ShortName": "",
+"WorldSnookerId": 13850,
+"RankingType": "WR",
+"EventPredictionID": 0,
+"Team": false,
+"Format": 1,
+"Twitter": "",
+"HashTag": "SnookerShanghaiMasters",
+"ConversionRate": 1,
+"AllRoundsAdded": true,
+"PhotoURLs": "",
+"NumCompetitors": 96,
+"NumUpcoming": 0,
+"NumActive": 0,
+"NumResults": 96,
+"Note": "",
+"CommonNote": "Watch on <a href=\u0022http:\u002F\u002Fwww.worldsnooker.livesport.tv\u002F\u0022>World Snooker<\u002Fa> and selected betting sites",
+"DefendingChampion": 0,
+"PreviousEdition": 0
+}
+]
+
+*********************************************************
+Match
+[
+{
+"ID": 2240166,
+"EventID": 397,
+"Round": 1,
+"Number": 5,
+"Player1ID": 1730,
+"Score1": 1,
+"Walkover1": false,
+"Player2ID": 1590,
+"Score2": 4,
+"Walkover2": false,
+"WinnerID": 1590,
+"Unfinished": false,
+"OnBreak": false,
+"WorldSnookerID": 386706,
+"LiveUrl": "",
+"DetailsUrl": "",
+"PointsDropped": false,
+"ShowCommonNote": false,
+"Estimated": false,
+"Type": 1,
+"TableNo": 0,
+"VideoURL": "",
+"InitDate": "2015-07-08T13:36:14Z",
+"ModDate": "2015-07-29T14:14:35Z",
+"StartDate": "2015-07-29T14:14:35Z",
+"EndDate": "2015-07-29T17:25:14Z",
+"ScheduledDate": "2015-07-29T14:00:00Z",
+"FrameScores": "",
+"Sessions": "",
+"Note": "",
+"ExtendedNote": ""
+}
+]
+
+*********************************************************
+Player
+
+[
+{
+"ID": 1,
+"Type": 1,
+"FirstName": "Mark",
+"MiddleName": "J",
+"LastName": "Williams",
+"TeamName": "",
+"TeamNumber": 0,
+"TeamSeason": 0,
+"ShortName": "M J Williams",
+"Nationality": "Wales",
+"Sex": "M",
+"BioPage": "http:\u002F\u002Fsnooker.org\u002Fplr\u002Fbio\u002Fmwilliams.shtml",
+"Born": "1975-03-21",
+"Twitter": "markwil147",
+"SurnameFirst": false,
+"License": "",
+"Club": "",
+"URL": "",
+"Photo": "http:\u002F\u002Fsnooker.org\u002Fimg\u002Fplayers\u002FMarkWilliams.png",
+"Info": ""
+}
+]
+
+*********************************************************
+Ranking
+[
+{
+"ID": 10830258,
+"Position": 1,
+"PlayerID": 17,
+"Season": 2015,
+"Sum": 680041,
+"Type": "MoneyRankings"
+}
+]
+*********************************************************
+OngoingMatch
+[
+{
+"ID": 3352339,
+"EventID": 531,
+"Round": 7,
+"Number": 8,
+"Player1ID": 17,
+"Score1": 0,
+"Walkover1": false,
+"Player2ID": 1,
+"Score2": 1,
+"Walkover2": false,
+"WinnerID": 0,
+"Unfinished": true,
+"OnBreak": false,
+"WorldSnookerID": 434080,
+"LiveUrl": "",
+"DetailsUrl": "",
+"PointsDropped": false,
+"ShowCommonNote": true,
+"Estimated": false,
+"Type": 1,
+"TableNo": 0,
+"VideoURL": "",
+"InitDate": "2016-12-04T14:45:51Z",
+"ModDate": "2017-01-18T13:39:40Z",
+"StartDate": "2017-01-18T13:10:00Z",
+"EndDate": "",
+"ScheduledDate": "2017-01-18T13:00:00Z",
+"FrameScores": "",
+"Sessions": "",
+"Note": "",
+"ExtendedNote": ""
+}
+]
diff --git a/src/site/apt/examples/handle-the-api-exceptions.apt.vm b/src/site/apt/examples/handle-the-api-exceptions.apt.vm

new file mode 100644 (file)

index 0000000..45cbab6
--- /dev/null
+++ b/src/site/apt/examples/handle-the-api-exceptions.apt.vm
@@ -0,0 +1,68 @@
+ ------
+ Handling the API exceptions
+ ------
+ 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
+
+Handling the API exceptions
+
+  This library provides the basic exception <<<APIException>>> that in the event 
+  of exceptional situations can inform the client application of the type of error 
+  that occurred in the process of using library methods.\
+  This exception can notify you about two types of exception:
+
++-------
+public class APIException extends Exception {
+
+    public static enum Type {
+        INFO,
+        REQUEST
+    }
+    ...
+}
++-------
+
+  You can get the type of exception that was thrown by using the method <<<APIException.getType()>>>.
+
+  The type <<<INFO>>> tells the client application that the exception that that has occurred 
+  is not critical and is not related to the inability to obtain useful information.
+  The work of the application can be continued after detection of this type of exception without 
+  serious consequences but with some adjustments in the future working functionality.
+
+  The type <<<REQUEST>>> tells the client application that the exception that has occurred is associated 
+  with the process of obtaining useful information from the portal {{{http://snooker.org/}snooker.org}}
+  or with the inability to handle the received information.\
+  This type of exception can occur for several reasons:
+
+  <<1.>> The data passed to the API method is incorrect. This can occur in case of an incorrect 
+  input ID (tournament, player, etc.) or a <<null>> input parameter. In this case the application 
+  can continue to work after correction the transmitted parameters.
+
+  <<2.>> Inaccessibility of the communication channel (access to the portal).
+  Information simply can not be obtained. In this case the client application can not continue
+  to work until an Internet connection is established.
+
+  <<3.>> The portal API has changed. Incoming data can not be processed correctly.
+  This case is the most significant. It means that the current version of the library
+  can no longer be considered workable. It is necessary to check the availability of 
+  a more recent version of the library and if there is none then inform the developer about 
+  of a detected nonconformity between API library and portal {{{http://api.snooker.org/}api.snooker.org}}.
diff --git a/src/site/apt/examples/use-sort-in-collections.apt.vm b/src/site/apt/examples/use-sort-in-collections.apt.vm

new file mode 100644 (file)

index 0000000..ec7f9b3
--- /dev/null
+++ b/src/site/apt/examples/use-sort-in-collections.apt.vm
@@ -0,0 +1,89 @@
+ ------
+ Using sorting of received data
+ ------
+ 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
+
+Using sorting of received data
+
+  The data obtained from the API methods calls of the main interface of the library,
+  in most cases, represent collection classes (<<<Players>>>, <<<Events>>>, <<<Matches>>>) 
+  which can be sorted by certain parameters for convenience of further use in client applications.
+
+  The types of possible sorts for specific collection classes are listed below.
+
+===
+
+  <<<Players>>> - entity class which contains a selection of players on certain parameters.\
+  This class provides two types of sorting:
+
+  <<1.>> Sorting players by name.
+
+  <<2.>> Sorting players by age, both in descending order and in ascending order.
+
+  Java code that shows all the above sorting methods is presented below:
+
++-------
+Players players = Snooker.API().getPlayers(...);
+...
+players.sortByName();
+...
+players.sortByAge();
+players.sortByAgeDesc();
+...
++-------
+
+===
+
+  <<<Events>>> - entity class which contains a selection of tournaments for certain parameters.
+
+  Java code that shows the sorting of tournaments by date is presented below:
+
++-------
+Events events = Snooker.API().getSeasonEvents((...);
+...
+events.sortByDate();
+...
++-------
+
+===
+
+  <<<Matches>>> - entity class which contains a selection of matches for certain parameters.\
+  This class provides two types of sorting:
+
+  <<1.>> Sorting matches by number.\
+  This sorting type will be useful when the selection contains all the matches of a single tournament.
+
+  <<2.>> Sorting matches by tournament.\
+  This sorting type will be useful when the selection contains all the matches
+  of an individual player for the season in different tournaments.
+
+  Java code that shows all the above sorting methods is presented below:
+
++-------
+Matches matches = Snooker.API().getEventMatches((...);
+...
+matches.sortByNumber();
+...
+matches.sortByEvent();
+...
++-------
diff --git a/src/site/apt/examples/work-with-the-cached-api.apt.vm b/src/site/apt/examples/work-with-the-cached-api.apt.vm

new file mode 100644 (file)

index 0000000..912a756
--- /dev/null
+++ b/src/site/apt/examples/work-with-the-cached-api.apt.vm
@@ -0,0 +1,85 @@
+ ------
+ 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();
++-------
diff --git a/src/site/apt/index.apt.vm b/src/site/apt/index.apt.vm

new file mode 100644 (file)

index 0000000..5f23c23
--- /dev/null
+++ b/src/site/apt/index.apt.vm
@@ -0,0 +1,56 @@
+ ------
+ Introduction
+ ------
+ 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
+
+${project.name}
+
+  ${project.description}
+
+  All useful information is downloaded via the HTTP protocol from the portal {{{http://snooker.org/}snooker.org}},
+  so for the functioning of applications that use this library Internet access is required.
+
+  The current version of the library:
+  {{{http://repo.hedgecode.org/content/repositories/releases/org/hedgecode/snooker/${project.artifactId}/${project.version}/${project.artifactId}-${project.version}.jar}${project.version}}}
+
+  <<Note>>: <All versions of the library up to version 1.0 can not be considered completely stable.>
+
+* Usage
+
+  General instructions on how to use this library can be found on the {{{./usage.html}usage page}}.
+
+  Description of the main methods of the library is in the section {{{./faq.html}FAQ}}.
+
+  Some more specific use cases are described in the examples given below.
+
+* Examples
+
+  To better understand the described library you can refer to the following examples:
+
+  * {{{./examples/work-with-the-cached-api.html}Working with the cached version API}}
+
+  * {{{./examples/use-sort-in-collections.html}Using sorting of received data}}
+
+  * {{{./examples/handle-the-api-exceptions.html}Handling the API exceptions}}
+
+  []
diff --git a/src/site/apt/usage.apt.vm b/src/site/apt/usage.apt.vm

new file mode 100644 (file)

index 0000000..15f62f4
--- /dev/null
+++ b/src/site/apt/usage.apt.vm
@@ -0,0 +1,119 @@
+ ------
+ 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)
+********************************************************************************
++-----
diff --git a/src/site/fml/faq.fml b/src/site/fml/faq.fml

new file mode 100644 (file)

index 0000000..85077a7
--- /dev/null
+++ b/src/site/fml/faq.fml
@@ -0,0 +1,139 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+  ~ 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.
+-->
+
+<faqs xmlns="http://maven.apache.org/FML/1.0.1"
+      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+      xsi:schemaLocation="http://maven.apache.org/FML/1.0.1 http://maven.apache.org/xsd/fml-1.0.1.xsd"
+      title="Frequently Asked Questions">
+    <part id="general">
+        <title>General:</title>
+        <faq id="how-to-get-event">
+            <question>
+                How to get full information on a specific tournament?
+            </question>
+            <answer>
+                <p><pre>Event event = Snooker.API().getEvent(eventId);</pre>
+                where parameter <code>eventId</code> is ID of the tournament.
+                </p>
+            </answer>
+        </faq>
+        <faq id="how-to-get-match">
+            <question>
+                How to get full information on a specific match?
+            </question>
+            <answer>
+                <p><pre>Match match = Snooker.API().getMatch(eventId, roundId, matchNumber);</pre>
+                where parameter <code>eventId</code> is ID of the tournament which the match is played;
+                <code>roundId</code> is ID of the round of the tournament;
+                <code>matchNumber</code> is number of the match in the round.
+                </p>
+            </answer>
+        </faq>
+        <faq id="how-to-get-player">
+            <question>
+                How to get full information on a specific player?
+            </question>
+            <answer>
+                <p><pre>Player player = Snooker.API().getPlayer(int playerId);</pre>
+                where parameter <code>playerId</code> is ID of the player.
+                </p>
+            </answer>
+        </faq>
+        <faq id="how-to-get-season-events">
+            <question>
+                How to get information on all tournaments in the season?
+            </question>
+            <answer>
+                <p><pre>Events seasonEvents = Snooker.API().getSeasonEvents(season);</pre>
+                where parameter <code>season</code> is object of class <code>Season</code>
+                that specify a season or <code>Season.ALL</code> for all available seasons.
+                </p>
+            </answer>
+        </faq>
+        <faq id="how-to-get-event-matches">
+            <question>
+                How to get information on all matches of a specific tournament?
+            </question>
+            <answer>
+                <p><pre>Matches eventMatches = Snooker.API().getEventMatches(eventId);</pre>
+                where parameter <code>eventId</code> is ID of the tournament.
+                </p>
+            </answer>
+        </faq>
+        <faq id="how-to-get-ongoing-matches">
+            <question>
+                How to get information on the matches which take place in this moment?
+            </question>
+            <answer>
+                <p><pre>OngoingMatches matches = Snooker.API().getOngoingMatches();</pre>
+                </p>
+            </answer>
+        </faq>
+        <faq id="how-to-get-player-matches">
+            <question>
+                How to get information on all matches of a specific player in the season?
+            </question>
+            <answer>
+                <p><pre>Matches playerMatches = Snooker.API().getPlayerMatches(playerId, season);</pre>
+                where parameter <code>playerId</code> is ID of the player
+                and <code>season</code> is object of class <code>Season</code>
+                that specify a season or <code>Season.ALL</code> for all available seasons.
+                </p>
+            </answer>
+        </faq>
+        <faq id="how-to-get-event-players">
+            <question>
+                How to get information on all players in a specific tournament?
+            </question>
+            <answer>
+                <p><pre>Players eventPlayers = Snooker.API().getEventPlayers(eventId);</pre>
+                where parameter <code>eventId</code> is ID of the tournament.
+                </p>
+            </answer>
+        </faq>
+        <faq id="how-to-get-players">
+            <question>
+                How to get information on all players in a specific season?
+            </question>
+            <answer>
+                <p><pre>Players players = Snooker.API().getPlayers(season, category);</pre>
+                where parameter <code>season</code> is object of class <code>Season</code>
+                that specify a season or <code>Season.ALL</code> for all available seasons
+                and <code>category</code> is object of class <code>PlayerCategory</code>
+                that specify a category of players (for example, <code>PlayerCategory.PRO</code>).
+                </p>
+            </answer>
+        </faq>
+    </part>
+    <part id="additional">
+        <title>Additional:</title>
+        <faq id="how-to-get-rankings">
+            <question>
+                How to get information on the ratings/earnings of all players in the season?
+            </question>
+            <answer>
+                <p><pre>Rankings rankings = Snooker.API().getRankings(season, rankingType);</pre>
+                where parameter <code>season</code> is object of class <code>Season</code>
+                that specify a season or <code>Season.ALL</code> for all available seasons
+                and <code>rankingType</code> is object of class <code>RankingType</code>
+                that specify a rating type (for example, <code>RankingType.MoneyRankings</code>).
+                </p>
+            </answer>
+        </faq>
+    </part>
+</faqs>
diff --git a/src/site/ru/apt/examples/handle-the-api-exceptions.apt.vm b/src/site/ru/apt/examples/handle-the-api-exceptions.apt.vm

new file mode 100644 (file)

index 0000000..acaaa15
--- /dev/null
+++ b/src/site/ru/apt/examples/handle-the-api-exceptions.apt.vm
@@ -0,0 +1,68 @@
+ ------
+ Обработка исключений, возникающих при работе с 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
+
+Обработка исключений, возникающих при работе с API
+
+  В данной библиотеке реализовано основное исключение <<<APIException>>>, которое
+  при возникновении исключительных ситуаций может сообщать клиентскому приложению
+  о типе возникшей ошибке в процессе использования библиотечных методов.\
+  Данное исключение может уведомлять о двух типах исключительных ситуаций:
+
++-------
+public class APIException extends Exception {
+
+    public static enum Type {
+        INFO,
+        REQUEST
+    }
+    ...
+}
++-------
+
+  Получить тип возникшего исключения можно при помощи метода <<<APIException.getType()>>>.
+
+  Тип <<<INFO>>> сообщает клиентскому приложению о том, что возникшее исключение не является
+  критическим и не связано с невозможностью получить полезную информацию.
+  Работа приложения может быть продолжена после обнаружения данного типа исключения без
+  серьезных последствий, но с определенными корректировками в дальнейшем рабочем функционале.
+
+  Тип <<<REQUEST>>> сообщает клиентскому приложению о том, что возникшее исключение связано
+  с процессом получения полезной информации с портала {{{http://snooker.org/}snooker.org}}, либо
+  с невозможностью обработать полученную информацию.\
+  Данный тип исключения может возникнуть по нескольким причинам:
+
+  <<1.>> Данные, переданные API-методу, некорректны. Такое может возникнуть в случае передачи
+  некорректного входного ID (турнира, игрока и пр.) или же <<null>>-параметра. В данном случае
+  работа приложения может быть продолжена после корректировки передаваемых параметров.
+
+  <<2.>> Нарушение канала связи (доступа к порталу). Информация просто не может быть получена.
+  В данном случае клиентское приложение не может продолжать работать до установления нормального 
+  интернет-соединения.
+
+  <<3.>> API самого портала претерпело изменения. Входящие данные не могут быть корректно обработаны.
+  Этот случай самый существенный. Он означает, что текущая версия библиотеки уже не может считаться
+  работоспособной. Необходимо проверить наличие более свежей версии данной библиотеки, и если таковая
+  отсутствует, то сообщить разработчику о выявленном несоответствии API библиотеки
+  и портала {{{http://api.snooker.org/}api.snooker.org}}.
diff --git a/src/site/ru/apt/examples/use-sort-in-collections.apt.vm b/src/site/ru/apt/examples/use-sort-in-collections.apt.vm

new file mode 100644 (file)

index 0000000..244cb61
--- /dev/null
+++ b/src/site/ru/apt/examples/use-sort-in-collections.apt.vm
@@ -0,0 +1,88 @@
+ ------
+ Использование сортировки полученных данных
+ ------
+ 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
+
+Использование сортировки полученных данных
+
+  Данные, получаемые при вызовах API-методов основного интерфейса библиотеки, в большинстве своем
+  представляют классы-коллекции (<<<Players>>>, <<<Events>>>, <<<Matches>>>), к которым для удобства
+  дальнейшего использования в клиентских приложениях можно применять сортировку по определенным параметрам.
+
+  Ниже перечислены виды возможных сортировок для конкретных классов-коллекций.
+
+===
+
+  <<<Players>>> - класс-сущность, в котором содержится выборка игроков по определенным параметрам.\
+  Данный класс предоставляет два вида сортировки:
+
+  <<1.>> Сортировка игроков по имени.
+
+  <<2.>> Сортировка игроков по возрасту, как по убыванию, так и по возрастанию.
+
+  Ниже представлен Java-код, демонстрирующий все вышеуказанные способы сортировки:
+
++-------
+Players players = Snooker.API().getPlayers(...);
+...
+players.sortByName();
+...
+players.sortByAge();
+players.sortByAgeDesc();
+...
++-------
+
+===
+
+  <<<Events>>> - класс-сущность, в котором содержится выборка турниров по определенным параметрам.
+
+  Ниже представлен Java-код, демонстрирующий сортировку турниров по дате:
+
++-------
+Events events = Snooker.API().getSeasonEvents((...);
+...
+events.sortByDate();
+...
++-------
+
+===
+
+  <<<Matches>>> - класс-сущность, в котором содержится выборка матчей по определенным параметрам.\
+  Данный класс предоставляет два вида сортировки:
+
+  <<1.>> Сортировка матчей по номеру.\
+  Данный тип сортировки будет полезен тогда, когда выборка содержит все матчи отдельно взятого турнира.
+
+  <<2.>> Сортировка матчей по турнирам.\
+  Данный тип сортировки будет полезен тогда, когда выборка содержит все матчи отдельно взятого игрока за сезон в разных турнирах.
+
+  Ниже представлен Java-код, демонстрирующий все вышеуказанные способы сортировки:
+
++-------
+Matches matches = Snooker.API().getEventMatches((...);
+...
+matches.sortByNumber();
+...
+matches.sortByEvent();
+...
++-------
diff --git a/src/site/ru/apt/examples/work-with-the-cached-api.apt.vm b/src/site/ru/apt/examples/work-with-the-cached-api.apt.vm

new file mode 100644 (file)

index 0000000..1c8f111
--- /dev/null
+++ b/src/site/ru/apt/examples/work-with-the-cached-api.apt.vm
@@ -0,0 +1,84 @@
+ ------
+ Работа с кэширующей версией 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
+
+Работа с кэширующей версией API
+
+  При первоначальном вызове API-метода для получения основного интерфейса библиотеки
+
++-------
+SnookerScoreAPI api = Snooker.API();
++-------
+
+  мы по умолчанию имеем дело с кэширующей реализацией API-интерфейса <<<SnookerScoreAPI>>>.\
+  В чем же её преимущества?
+
+===
+
+  Во-первых, при работе с кэширующей версией интерфейса при различных запросах вы получаете 
+  более полный объём полезной информации. Например, при запросе текущих матчей в выборке будут 
+  содержаться, помимо другой информации, ссылки на турнир (объект <<<Event>>>), а также на игроков,
+  участвующих в каждом матче (объекты <<<Player>>>):
+
++-------
+SnookerScoreAPI api = Snooker.API();
+OngoingMatches matches = api.getOngoingMatches();
+for (OngoingMatch match : matches) {
+    Event event = match.event();
+    Player player1 = match.player1();
+    Player player2 = match.player2();
+}
++-------
+
+  Тогда как при работе с некэширующей версией интерфейса вам придётся делать дополнительные запросы
+  о турнире и игроках, чтобы получить полную информацию о проходящих матчах:
+
++-------
+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());
+}
++-------
+
+===
+
+  Во-вторых, в кэширующей версии интерфейса вам предоставляется возможность задать текущий сезон,
+  с событиями которого в дальнейшем вы собираетесь работать путем запросов турниров и матчей:
+
++-------
+SnookerScoreAPI api = Snooker.API();
+api.setCurrentSeason(Season.getSeason(2015));
++-------
+
+===
+
+  P.S. Если вам необходимо использовать некэширующую версию API-интерфейса,
+  то её можно получить следующим образом:
+
++-------
+SnookerScoreAPI uncachedApi = Snooker.uncachedAPI();
++-------
diff --git a/src/site/ru/apt/index.apt.vm b/src/site/ru/apt/index.apt.vm

new file mode 100644 (file)

index 0000000..80db9d3
--- /dev/null
+++ b/src/site/ru/apt/index.apt.vm
@@ -0,0 +1,58 @@
+ ------
+ Введение
+ ------
+ 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
+
+${project.name}
+
+  Hedgecode Snooker Score представляет собой библиотеку с набором API сущностей, которая
+  может использоваться в клиентских Java-приложениях, имеющих своей целью информирование
+  о результатах снукерных матчей, а также о прочей статистической информации из мира снукера.
+
+  Вся полезная информация загружается по протоколу HTTP с портала {{{http://snooker.org/}snooker.org}},
+  поэтому для функционирования приложений, использующих данную библиотеку, необходим доступ в Интернет.
+
+  Текущая версия библиотеки:
+  {{{http://repo.hedgecode.org/content/repositories/releases/org/hedgecode/snooker/${project.artifactId}/${project.version}/${project.artifactId}-${project.version}.jar}${project.version}}}
+
+  <<Примечание>>: <Все версии библиотеки до версии 1.0 не могут считаться полностью стабильными.>
+
+* Использование
+
+  Общие инструкции о том, как использовать данную библиотеку можно найти на {{{./usage.html}этой странице}}.
+
+  Описание работы основных методов библиотеки находится в разделе {{{./faq.html}ЧаВо}}.
+
+  Некоторые более конкретные случаи использования описаны в примерах, приведенных ниже.
+
+* Примеры
+
+  Чтобы лучше понять описываемую библиотеку, вы можете обратиться к следующим примерам:
+
+  * {{{./examples/work-with-the-cached-api.html}Работа с кэширующей версией API}}
+
+  * {{{./examples/use-sort-in-collections.html}Использование сортировки полученных данных}}
+
+  * {{{./examples/handle-the-api-exceptions.html}Обработка исключений, возникающих при работе с API}}
+
+  []
diff --git a/src/site/ru/apt/usage.apt.vm b/src/site/ru/apt/usage.apt.vm

new file mode 100644 (file)

index 0000000..0a74c70
--- /dev/null
+++ b/src/site/ru/apt/usage.apt.vm
@@ -0,0 +1,125 @@
+ ------
+ Использование
+ ------
+ 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)
+********************************************************************************
++-----
diff --git a/src/site/ru/fml/faq.fml b/src/site/ru/fml/faq.fml

new file mode 100644 (file)

index 0000000..f4d4262
--- /dev/null
+++ b/src/site/ru/fml/faq.fml
@@ -0,0 +1,138 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+  ~ 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.
+-->
+
+<faqs xmlns="http://maven.apache.org/FML/1.0.1"
+      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+      xsi:schemaLocation="http://maven.apache.org/FML/1.0.1 http://maven.apache.org/xsd/fml-1.0.1.xsd"
+      title="Часто Задаваемые Вопросы">
+    <part id="general">
+        <title>Основные вопросы:</title>
+        <faq id="how-to-get-event">
+            <question>
+                Как получить полную информацию по конкретному турниру?
+            </question>
+            <answer>
+                <p><pre>Event event = Snooker.API().getEvent(eventId);</pre>
+                где параметр <code>eventId</code> - ID турнира.
+                </p>
+            </answer>
+        </faq>
+        <faq id="how-to-get-match">
+            <question>
+                Как получить полную информацию по конкретному матчу?
+            </question>
+            <answer>
+                <p><pre>Match match = Snooker.API().getMatch(eventId, roundId, matchNumber);</pre>
+                где параметр <code>eventId</code> - ID турнира, в котором играется искомый матч;
+                <code>roundId</code> - ID раунда турнира; <code>matchNumber</code> - номер матча в раунде.
+                </p>
+            </answer>
+        </faq>
+        <faq id="how-to-get-player">
+            <question>
+                Как получить полную информацию по конкретному игроку?
+            </question>
+            <answer>
+                <p><pre>Player player = Snooker.API().getPlayer(int playerId);</pre>
+                где параметр <code>playerId</code> - ID игрока.
+                </p>
+            </answer>
+        </faq>
+        <faq id="how-to-get-season-events">
+            <question>
+                Как получить информацию по всем турнирам в сезоне?
+            </question>
+            <answer>
+                <p><pre>Events seasonEvents = Snooker.API().getSeasonEvents(season);</pre>
+                где параметр <code>season</code> - объект класса <code>Season</code>, задающий
+                конкретный сезон, или же <code>Season.ALL</code> - для всех доступных сезонов.
+                </p>
+            </answer>
+        </faq>
+        <faq id="how-to-get-event-matches">
+            <question>
+                Как получить информацию по всем матчам конкретного турнира?
+            </question>
+            <answer>
+                <p><pre>Matches eventMatches = Snooker.API().getEventMatches(eventId);</pre>
+                где параметр <code>eventId</code> - ID турнира.
+                </p>
+            </answer>
+        </faq>
+        <faq id="how-to-get-ongoing-matches">
+            <question>
+                Как получить информацию по матчам, которые проходят в данным момент?
+            </question>
+            <answer>
+                <p><pre>OngoingMatches matches = Snooker.API().getOngoingMatches();</pre>
+                </p>
+            </answer>
+        </faq>
+        <faq id="how-to-get-player-matches">
+            <question>
+                Как получить информацию по всем матчам конкретного игрока в сезоне?
+            </question>
+            <answer>
+                <p><pre>Matches playerMatches = Snooker.API().getPlayerMatches(playerId, season);</pre>
+                где параметр <code>playerId</code> - ID игрока,
+                а <code>season</code> - объект класса <code>Season</code>, задающий
+                конкретный сезон, или же <code>Season.ALL</code> - для всех доступных сезонов.
+                </p>
+            </answer>
+        </faq>
+        <faq id="how-to-get-event-players">
+            <question>
+                Как получить информацию по всем игрокам в конкретном турнире?
+            </question>
+            <answer>
+                <p><pre>Players eventPlayers = Snooker.API().getEventPlayers(eventId);</pre>
+                где параметр <code>eventId</code> - ID турнира.
+                </p>
+            </answer>
+        </faq>
+        <faq id="how-to-get-players">
+            <question>
+                Как получить информацию по всем игрокам в конкретном сезоне?
+            </question>
+            <answer>
+                <p><pre>Players players = Snooker.API().getPlayers(season, category);</pre>
+                где параметр <code>season</code> - объект класса <code>Season</code>, задающий
+                конкретный сезон, или же <code>Season.ALL</code> - для всех доступных сезонов,
+                а <code>category</code> - объект класса <code>PlayerCategory</code>,
+                задающий категорию игроков (например, <code>PlayerCategory.PRO</code>).
+                </p>
+            </answer>
+        </faq>
+    </part>
+    <part id="additional">
+        <title>Дополнительно:</title>
+        <faq id="how-to-get-rankings">
+            <question>
+                Как получить информацию по рейтингам/заработанным суммам всех игроков в сезоне?
+            </question>
+            <answer>
+                <p><pre>Rankings rankings = Snooker.API().getRankings(season, rankingType);</pre>
+                где параметр <code>season</code> - объект класса <code>Season</code>, задающий
+                конкретный сезон, или же <code>Season.ALL</code> - для всех доступных сезонов,
+                а <code>rankingType</code> - объект класса <code>RankingType</code>,
+                задающий тип рейтинга (например, <code>RankingType.MoneyRankings</code>).
+                </p>
+            </answer>
+        </faq>
+    </part>
+</faqs>
diff --git a/src/site/ru/xdoc/download.xml.vm b/src/site/ru/xdoc/download.xml.vm

new file mode 100644 (file)

index 0000000..fdbd3c8
--- /dev/null
+++ b/src/site/ru/xdoc/download.xml.vm
@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+  ~ 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.
+-->
+
+<document>
+    <properties>
+        <title>Скачать</title>
+    </properties>
+    <body>
+        <section name="Загрузка ${project.name}">
+
+            <p>${project.name} ${project.version} доступен как в двоичном формате (JAR артефакт), так и в исходных кодах.</p>
+
+            <subsection name="${project.name} ${project.version} Двоичный Формат">
+                <p>
+                    Текущая стабильная версия ${project.name}:
+                    <a href="http://repo.hedgecode.org/content/repositories/releases/org/hedgecode/snooker/${project.artifactId}/${project.version}/${project.artifactId}-${project.version}.jar">${project.artifactId}-${project.version}.jar</a>
+                    и её <a href="http://repo.hedgecode.org/content/repositories/releases/org/hedgecode/snooker/${project.artifactId}/${project.version}/${project.artifactId}-${project.version}.jar.md5">MD5</a> сумма.
+                </p>
+            </subsection>
+
+            <subsection name="Предыдущие Версии">
+                <p>Старые release-версии ${project.artifactId} доступны на странице <a href="http://repo.hedgecode.org/content/repositories/releases/org/hedgecode/snooker/${project.artifactId}/">Hedgecode Release Repository</a>.</p>
+                <p>Старые snapshot-версии ${project.artifactId} доступны на странице <a href="http://repo.hedgecode.org/content/repositories/snapshots/org/hedgecode/snooker/${project.artifactId}/">Hedgecode Snapshot Repository</a>.</p>
+            </subsection>
+
+            <subsection name="${project.name} ${project.version} Исходный Код">
+                <p>Архивы с javadoc и исходными кодами текущей версии библиотеки:
+                    <a href="http://repo.hedgecode.org/content/repositories/releases/org/hedgecode/snooker/${project.artifactId}/${project.version}/${project.artifactId}-${project.version}-javadoc.jar">javadoc</a>,
+                    <a href="http://repo.hedgecode.org/content/repositories/releases/org/hedgecode/snooker/${project.artifactId}/${project.version}/${project.artifactId}-${project.version}-sources.jar">sources</a>.
+                </p>
+                <p>Исходный код ${project.artifactId} доступен в <a href="http://svn.hedgecode.org/lib/${project.artifactId}/trunk/">Hedgecode Subversion Repository</a>.</p>
+                <p>Исходный код ${project.name} распространяется под лицензией <a href="http://www.apache.org/licenses/">Apache License, version 2.0</a>.</p>
+            </subsection>
+
+        </section>
+    </body>
+</document>
+
diff --git a/src/site/site.xml b/src/site/site.xml

new file mode 100644 (file)

index 0000000..d099627
--- /dev/null
+++ b/src/site/site.xml
@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+  ~ 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.
+-->
+
+<project xmlns="http://maven.apache.org/DECORATION/1.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/DECORATION/1.0.0 http://maven.apache.org/xsd/decoration-1.0.0.xsd">
+    <body>
+        <breadcrumbs>
+            <item name="${project.artifactId}" href="/"/>
+        </breadcrumbs>
+        <links>
+            <item name="ENG" href="index.html"/>
+            <item name="RUS" href="ru/index.html"/>
+        </links>
+        <menu name="Overview">
+            <item name="Introduction" href="index.html"/>
+            <item name="Usage" href="usage.html"/>
+            <item name="FAQ" href="faq.html"/>
+            <item name="License" href="http://www.apache.org/licenses/"/>
+            <item name="Download" href="download.html"/>
+        </menu>
+        <menu name="Examples">
+            <item name="Work with cached API" href="examples/work-with-the-cached-api.html"/>
+            <item name="Use data sorting" href="examples/use-sort-in-collections.html"/>
+            <item name="Handle API Exceptions" href="examples/handle-the-api-exceptions.html"/>
+        </menu>
+        <menu ref="reports"/>
+    </body>
+</project>
diff --git a/src/site/site_ru.xml b/src/site/site_ru.xml

new file mode 100644 (file)

index 0000000..b19fe08
--- /dev/null
+++ b/src/site/site_ru.xml
@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+  ~ 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.
+-->
+
+<project xmlns="http://maven.apache.org/DECORATION/1.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/DECORATION/1.0.0 http://maven.apache.org/xsd/decoration-1.0.0.xsd">
+    <body>
+        <breadcrumbs>
+            <item name="${project.artifactId}" href="/"/>
+        </breadcrumbs>
+        <links>
+            <item name="ENG" href="../index.html"/>
+            <item name="RUS" href="index.html"/>
+        </links>
+        <menu name="Описание">
+            <item name="Введение" href="index.html"/>
+            <item name="Использование" href="usage.html"/>
+            <item name="ЧаВо" href="faq.html"/>
+            <item name="Лицензия" href="http://www.apache.org/licenses/"/>
+            <item name="Скачать" href="download.html"/>
+        </menu>
+        <menu name="Примеры">
+            <item name="Работа с кэширующей версией API" href="examples/work-with-the-cached-api.html"/>
+            <item name="Использование сортировки полученных данных" href="examples/use-sort-in-collections.html"/>
+            <item name="Обработка исключений, возникающих при работе с API" href="examples/handle-the-api-exceptions.html"/>
+        </menu>
+        <menu ref="reports"/>
+    </body>
+</project>
diff --git a/src/site/xdoc/download.xml.vm b/src/site/xdoc/download.xml.vm

new file mode 100644 (file)

index 0000000..7bedc4a
--- /dev/null
+++ b/src/site/xdoc/download.xml.vm
@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+  ~ 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.
+-->
+
+<document>
+    <properties>
+        <title>Download</title>
+    </properties>
+    <body>
+        <section name="Download ${project.name}">
+
+            <p>${project.name} ${project.version} is distributed in ready-made binary format (jar artifact) and source format.</p>
+
+            <subsection name="${project.name} ${project.version} Binary Format">
+                <p>
+                    The current stable version of ${project.name}:
+                    <a href="http://repo.hedgecode.org/content/repositories/releases/org/hedgecode/maven/plugins/${project.artifactId}/${project.version}/${project.artifactId}-${project.version}.jar">${project.artifactId}-${project.version}.jar</a>
+                    and its <a href="http://repo.hedgecode.org/content/repositories/releases/org/hedgecode/maven/plugins/${project.artifactId}/${project.version}/${project.artifactId}-${project.version}.jar.md5">MD5</a> sum.
+                </p>
+            </subsection>
+
+            <subsection name="Previous Versions">
+                <p>Older releases can be found on ${project.artifactId} page of <a href="http://repo.hedgecode.org/content/repositories/releases/org/hedgecode/maven/plugins/${project.artifactId}/">Hedgecode Release Repository</a>.</p>
+                <p>Older snapshots can be found on ${project.artifactId} page of <a href="http://repo.hedgecode.org/content/repositories/snapshots/org/hedgecode/maven/plugins/${project.artifactId}/">Hedgecode Snapshot Repository</a>.</p>
+            </subsection>
+
+            <subsection name="${project.name} ${project.version} Source Code">
+                <p>Javadoc and Sources archives of the current version of the library:
+                    <a href="http://repo.hedgecode.org/content/repositories/releases/org/hedgecode/maven/plugins/${project.artifactId}/${project.version}/${project.artifactId}-${project.version}-javadoc.jar">javadoc</a>,
+                    <a href="http://repo.hedgecode.org/content/repositories/releases/org/hedgecode/maven/plugins/${project.artifactId}/${project.version}/${project.artifactId}-${project.version}-sources.jar">sources</a>.
+                </p>
+                <p>Source code of the ${project.artifactId} can be found on <a href="http://svn.hedgecode.org/maven/plugins/trunk/${project.artifactId}/">Hedgecode Subversion Repository</a>.</p>
+                <p>${project.name} source code is distributed under the <a href="http://www.apache.org/licenses/">Apache License, version 2.0</a>.</p>
+            </subsection>
+
+        </section>
+    </body>
+</document>
+
author	gotty <gotty@fb0bcced-7025-49ed-a12f-f98bce993226>
	Fri, 2 Jun 2017 13:01:00 +0000 (13:01 +0000)
committer	gotty <gotty@fb0bcced-7025-49ed-a12f-f98bce993226>
	Fri, 2 Jun 2017 13:01:00 +0000 (13:01 +0000)
sample.txt	[new file with mode: 0644]	patch \| blob
src/site/apt/examples/handle-the-api-exceptions.apt.vm	[new file with mode: 0644]	patch \| blob
src/site/apt/examples/use-sort-in-collections.apt.vm	[new file with mode: 0644]	patch \| blob
src/site/apt/examples/work-with-the-cached-api.apt.vm	[new file with mode: 0644]	patch \| blob
src/site/apt/index.apt.vm	[new file with mode: 0644]	patch \| blob
src/site/apt/usage.apt.vm	[new file with mode: 0644]	patch \| blob
src/site/fml/faq.fml	[new file with mode: 0644]	patch \| blob
src/site/ru/apt/examples/handle-the-api-exceptions.apt.vm	[new file with mode: 0644]	patch \| blob
src/site/ru/apt/examples/use-sort-in-collections.apt.vm	[new file with mode: 0644]	patch \| blob
src/site/ru/apt/examples/work-with-the-cached-api.apt.vm	[new file with mode: 0644]	patch \| blob
src/site/ru/apt/index.apt.vm	[new file with mode: 0644]	patch \| blob
src/site/ru/apt/usage.apt.vm	[new file with mode: 0644]	patch \| blob
src/site/ru/fml/faq.fml	[new file with mode: 0644]	patch \| blob
src/site/ru/xdoc/download.xml.vm	[new file with mode: 0644]	patch \| blob
src/site/site.xml	[new file with mode: 0644]	patch \| blob
src/site/site_ru.xml	[new file with mode: 0644]	patch \| blob
src/site/xdoc/download.xml.vm	[new file with mode: 0644]	patch \| blob