From 5249634fbece93b8481cd7f1dc9bb7e55194e3d4 Mon Sep 17 00:00:00 2001 From: gotty Date: Fri, 2 Jun 2017 13:01:00 +0000 Subject: [PATCH] [LIB-5] Site sources of snooker-score-api git-svn-id: https://svn.hedgecode.org/lib/snooker-score-api/trunk@120 fb0bcced-7025-49ed-a12f-f98bce993226 --- sample.txt | 159 +++++++++++++++++++++ .../apt/examples/handle-the-api-exceptions.apt.vm | 68 +++++++++ .../apt/examples/use-sort-in-collections.apt.vm | 89 ++++++++++++ .../apt/examples/work-with-the-cached-api.apt.vm | 85 +++++++++++ src/site/apt/index.apt.vm | 56 ++++++++ src/site/apt/usage.apt.vm | 119 +++++++++++++++ src/site/fml/faq.fml | 139 ++++++++++++++++++ .../apt/examples/handle-the-api-exceptions.apt.vm | 68 +++++++++ .../ru/apt/examples/use-sort-in-collections.apt.vm | 88 ++++++++++++ .../apt/examples/work-with-the-cached-api.apt.vm | 84 +++++++++++ src/site/ru/apt/index.apt.vm | 58 ++++++++ src/site/ru/apt/usage.apt.vm | 125 ++++++++++++++++ src/site/ru/fml/faq.fml | 138 ++++++++++++++++++ src/site/ru/xdoc/download.xml.vm | 53 +++++++ src/site/site.xml | 44 ++++++ src/site/site_ru.xml | 44 ++++++ src/site/xdoc/download.xml.vm | 53 +++++++ 17 files changed, 1470 insertions(+) create mode 100644 sample.txt create mode 100644 src/site/apt/examples/handle-the-api-exceptions.apt.vm create mode 100644 src/site/apt/examples/use-sort-in-collections.apt.vm create mode 100644 src/site/apt/examples/work-with-the-cached-api.apt.vm create mode 100644 src/site/apt/index.apt.vm create mode 100644 src/site/apt/usage.apt.vm create mode 100644 src/site/fml/faq.fml create mode 100644 src/site/ru/apt/examples/handle-the-api-exceptions.apt.vm create mode 100644 src/site/ru/apt/examples/use-sort-in-collections.apt.vm create mode 100644 src/site/ru/apt/examples/work-with-the-cached-api.apt.vm create mode 100644 src/site/ru/apt/index.apt.vm create mode 100644 src/site/ru/apt/usage.apt.vm create mode 100644 src/site/ru/fml/faq.fml create mode 100644 src/site/ru/xdoc/download.xml.vm create mode 100644 src/site/site.xml create mode 100644 src/site/site_ru.xml create mode 100644 src/site/xdoc/download.xml.vm diff --git a/sample.txt b/sample.txt new file mode 100644 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 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 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 <<>> 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 <<>>. + + The type <<>> 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 <<>> 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 <> 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 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 (<<>>, <<>>, <<>>) + 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. + +=== + + <<>> - 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(); +... ++------- + +=== + + <<>> - 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(); +... ++------- + +=== + + <<>> - 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 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 <<>>.\ + 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 <<>>) as well as to the players + participating in each match (objects <<>>) 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 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}}} + + <>: + +* 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 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.groupId} + ${project.artifactId} + ${project.version} + + + ... + ++----- + + <>: 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(); ++----- + + <<>> 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 <<>> 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 index 0000000..85077a7 --- /dev/null +++ b/src/site/fml/faq.fml @@ -0,0 +1,139 @@ + + + + + + + General: + + + How to get full information on a specific tournament? + + + 

Event event = Snooker.API().getEvent(eventId);
+ where parameter eventId is ID of the tournament. +

+ + + + + How to get full information on a specific match? + + + 

Match match = Snooker.API().getMatch(eventId, roundId, matchNumber);
+ where parameter eventId is ID of the tournament which the match is played; + roundId is ID of the round of the tournament; + matchNumber is number of the match in the round. +

+ + + + + How to get full information on a specific player? + + + 

Player player = Snooker.API().getPlayer(int playerId);
+ where parameter playerId is ID of the player. +

+ + + + + How to get information on all tournaments in the season? + + + 

Events seasonEvents = Snooker.API().getSeasonEvents(season);
+ where parameter season is object of class Season + that specify a season or Season.ALL for all available seasons. +

+ + + + + How to get information on all matches of a specific tournament? + + + 

Matches eventMatches = Snooker.API().getEventMatches(eventId);
+ where parameter eventId is ID of the tournament. +

+ + + + + How to get information on the matches which take place in this moment? + + + 

OngoingMatches matches = Snooker.API().getOngoingMatches();
+

+ + + + + How to get information on all matches of a specific player in the season? + + + 

Matches playerMatches = Snooker.API().getPlayerMatches(playerId, season);
+ where parameter playerId is ID of the player + and season is object of class Season + that specify a season or Season.ALL for all available seasons. +

+ + + + + How to get information on all players in a specific tournament? + + + 

Players eventPlayers = Snooker.API().getEventPlayers(eventId);
+ where parameter eventId is ID of the tournament. +

+ + + + + How to get information on all players in a specific season? + + + 

Players players = Snooker.API().getPlayers(season, category);
+ where parameter season is object of class Season + that specify a season or Season.ALL for all available seasons + and category is object of class PlayerCategory + that specify a category of players (for example, PlayerCategory.PRO). +

+ + + + + Additional: + + + How to get information on the ratings/earnings of all players in the season? + + + 

Rankings rankings = Snooker.API().getRankings(season, rankingType);
+ where parameter season is object of class Season + that specify a season or Season.ALL for all available seasons + and rankingType is object of class RankingType + that specify a rating type (for example, RankingType.MoneyRankings). +

+ + + + 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 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 + + В данной библиотеке реализовано основное исключение <<>>, которое + при возникновении исключительных ситуаций может сообщать клиентскому приложению + о типе возникшей ошибке в процессе использования библиотечных методов.\ + Данное исключение может уведомлять о двух типах исключительных ситуаций: + ++------- +public class APIException extends Exception { + + public static enum Type { + INFO, + REQUEST + } + ... +} ++------- + + Получить тип возникшего исключения можно при помощи метода <<>>. + + Тип <<>> сообщает клиентскому приложению о том, что возникшее исключение не является + критическим и не связано с невозможностью получить полезную информацию. + Работа приложения может быть продолжена после обнаружения данного типа исключения без + серьезных последствий, но с определенными корректировками в дальнейшем рабочем функционале. + + Тип <<>> сообщает клиентскому приложению о том, что возникшее исключение связано + с процессом получения полезной информации с портала {{{http://snooker.org/}snooker.org}}, либо + с невозможностью обработать полученную информацию.\ + Данный тип исключения может возникнуть по нескольким причинам: + + <<1.>> Данные, переданные API-методу, некорректны. Такое может возникнуть в случае передачи + некорректного входного ID (турнира, игрока и пр.) или же <>-параметра. В данном случае + работа приложения может быть продолжена после корректировки передаваемых параметров. + + <<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 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-методов основного интерфейса библиотеки, в большинстве своем + представляют классы-коллекции (<<>>, <<>>, <<>>), к которым для удобства + дальнейшего использования в клиентских приложениях можно применять сортировку по определенным параметрам. + + Ниже перечислены виды возможных сортировок для конкретных классов-коллекций. + +=== + + <<>> - класс-сущность, в котором содержится выборка игроков по определенным параметрам.\ + Данный класс предоставляет два вида сортировки: + + <<1.>> Сортировка игроков по имени. + + <<2.>> Сортировка игроков по возрасту, как по убыванию, так и по возрастанию. + + Ниже представлен Java-код, демонстрирующий все вышеуказанные способы сортировки: + ++------- +Players players = Snooker.API().getPlayers(...); +... +players.sortByName(); +... +players.sortByAge(); +players.sortByAgeDesc(); +... ++------- + +=== + + <<>> - класс-сущность, в котором содержится выборка турниров по определенным параметрам. + + Ниже представлен Java-код, демонстрирующий сортировку турниров по дате: + ++------- +Events events = Snooker.API().getSeasonEvents((...); +... +events.sortByDate(); +... ++------- + +=== + + <<>> - класс-сущность, в котором содержится выборка матчей по определенным параметрам.\ + Данный класс предоставляет два вида сортировки: + + <<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 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 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 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 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.groupId} + ${project.artifactId} + ${project.version} + + + ... + ++----- + + <<Примечание>>: Maven 3.0 будет выдавать предупреждение, + если вы не укажите версию плагина. + +* Работа с Java-кодом библиотеки + + После подключения библиотеки к проекту можно начинать работать с её кодом.\ + Для того, чтобы получить экземпляр основного интерфейса библиотеки, нужно + выполнить следующий код: + ++----- +SnookerScoreAPI api = Snooker.API(); ++----- + + <<>> представляет собой интерфейс с набором всех основных методов, + которые позволяют через объекты-сущности получить доступ к информации о сезонах, + турнирах, матчах, игроках и их рейтингах. + + Библиотека предоставляет две реализации вышеуказанного интерфейса: с кэшированием + данных по игрокам и событиям (турнирам) внутри библиотеки и без кэширования. + Реализация интерфейса с кэшированием является реализацией "по умолчанию".\ + Доступ к каждой из двух реализаций интерфейса может быть получен путём выполнения + следующих вызовов: + ++----- +SnookerScoreAPI cachedApi = Snooker.cachedAPI(); /* API with cache */ +... +SnookerScoreAPI uncachedApi = Snooker.uncachedAPI(); /* API without cache */ ++----- + + Дальнейшая работа с библиотекой представляет собой последовательность вызовов методов + интерфейса <<>> для получения списков турниров, игроков, текущих матчей + и прочей статистической информации.\ + Например, чтобы получить информацию по матчам, проходящим в данный момент, достаточно + выполнить следующий код: + ++----- +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 index 0000000..f4d4262 --- /dev/null +++ b/src/site/ru/fml/faq.fml @@ -0,0 +1,138 @@ + + + + + + + Основные вопросы: + + + Как получить полную информацию по конкретному турниру? + + + 

Event event = Snooker.API().getEvent(eventId);
+ где параметр eventId - ID турнира. +

+ + + + + Как получить полную информацию по конкретному матчу? + + + 

Match match = Snooker.API().getMatch(eventId, roundId, matchNumber);
+ где параметр eventId - ID турнира, в котором играется искомый матч; + roundId - ID раунда турнира; matchNumber - номер матча в раунде. +

+ + + + + Как получить полную информацию по конкретному игроку? + + + 

Player player = Snooker.API().getPlayer(int playerId);
+ где параметр playerId - ID игрока. +

+ + + + + Как получить информацию по всем турнирам в сезоне? + + + 

Events seasonEvents = Snooker.API().getSeasonEvents(season);
+ где параметр season - объект класса Season, задающий + конкретный сезон, или же Season.ALL - для всех доступных сезонов. +

+ + + + + Как получить информацию по всем матчам конкретного турнира? + + + 

Matches eventMatches = Snooker.API().getEventMatches(eventId);
+ где параметр eventId - ID турнира. +

+ + + + + Как получить информацию по матчам, которые проходят в данным момент? + + + 

OngoingMatches matches = Snooker.API().getOngoingMatches();
+

+ + + + + Как получить информацию по всем матчам конкретного игрока в сезоне? + + + 

Matches playerMatches = Snooker.API().getPlayerMatches(playerId, season);
+ где параметр playerId - ID игрока, + а season - объект класса Season, задающий + конкретный сезон, или же Season.ALL - для всех доступных сезонов. +

+ + + + + Как получить информацию по всем игрокам в конкретном турнире? + + + 

Players eventPlayers = Snooker.API().getEventPlayers(eventId);
+ где параметр eventId - ID турнира. +

+ + + + + Как получить информацию по всем игрокам в конкретном сезоне? + + + 

Players players = Snooker.API().getPlayers(season, category);
+ где параметр season - объект класса Season, задающий + конкретный сезон, или же Season.ALL - для всех доступных сезонов, + а category - объект класса PlayerCategory, + задающий категорию игроков (например, PlayerCategory.PRO). +

+ + + + + Дополнительно: + + + Как получить информацию по рейтингам/заработанным суммам всех игроков в сезоне? + + + 

Rankings rankings = Snooker.API().getRankings(season, rankingType);
+ где параметр season - объект класса Season, задающий + конкретный сезон, или же Season.ALL - для всех доступных сезонов, + а rankingType - объект класса RankingType, + задающий тип рейтинга (например, RankingType.MoneyRankings). +

+ + + + diff --git a/src/site/ru/xdoc/download.xml.vm b/src/site/ru/xdoc/download.xml.vm new file mode 100644 index 0000000..fdbd3c8 --- /dev/null +++ b/src/site/ru/xdoc/download.xml.vm @@ -0,0 +1,53 @@ + + + + + + + Скачать + + +
+ +

${project.name} ${project.version} доступен как в двоичном формате (JAR артефакт), так и в исходных кодах.

+ + +

+ Текущая стабильная версия ${project.name}: + ${project.artifactId}-${project.version}.jar + и её MD5 сумма. +

+ + + +

Старые release-версии ${project.artifactId} доступны на странице Hedgecode Release Repository.

+

Старые snapshot-версии ${project.artifactId} доступны на странице Hedgecode Snapshot Repository.

+ + + +

Архивы с javadoc и исходными кодами текущей версии библиотеки: + javadoc, + sources. +

+

Исходный код ${project.artifactId} доступен в Hedgecode Subversion Repository.

+

Исходный код ${project.name} распространяется под лицензией Apache License, version 2.0.

+ + +
+ + + diff --git a/src/site/site.xml b/src/site/site.xml new file mode 100644 index 0000000..d099627 --- /dev/null +++ b/src/site/site.xml @@ -0,0 +1,44 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/site/site_ru.xml b/src/site/site_ru.xml new file mode 100644 index 0000000..b19fe08 --- /dev/null +++ b/src/site/site_ru.xml @@ -0,0 +1,44 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/site/xdoc/download.xml.vm b/src/site/xdoc/download.xml.vm new file mode 100644 index 0000000..7bedc4a --- /dev/null +++ b/src/site/xdoc/download.xml.vm @@ -0,0 +1,53 @@ + + + + + + + Download + + +
+ +

${project.name} ${project.version} is distributed in ready-made binary format (jar artifact) and source format.

+ + +

+ The current stable version of ${project.name}: + ${project.artifactId}-${project.version}.jar + and its MD5 sum. +

+ + + +

Older releases can be found on ${project.artifactId} page of Hedgecode Release Repository.

+

Older snapshots can be found on ${project.artifactId} page of Hedgecode Snapshot Repository.

+ + + +

Javadoc and Sources archives of the current version of the library: + javadoc, + sources. +

+

Source code of the ${project.artifactId} can be found on Hedgecode Subversion Repository.

+

${project.name} source code is distributed under the Apache License, version 2.0.

+ + +
+ + + -- 2.10.0