src/site/apt/examples/handle-the-api-exceptions.apt.vm

   1  ------
   2  Handling the API exceptions
   3  ------
   4  Dmitry Samoshin aka gotty
   5  ------
   6  2017-01-27
   7  ------
   8
   9 ~~ Copyright (c) 2017. Developed by Hedgecode.
  10 ~~
  11 ~~ Licensed under the Apache License, Version 2.0 (the "License");
  12 ~~ you may not use this file except in compliance with the License.
  13 ~~ You may obtain a copy of the License at
  14 ~~
  15 ~~   http://www.apache.org/licenses/LICENSE-2.0
  16 ~~
  17 ~~ Unless required by applicable law or agreed to in writing, software
  18 ~~ distributed under the License is distributed on an "AS IS" BASIS,
  19 ~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  20 ~~ See the License for the specific language governing permissions and
  21 ~~ limitations under the License.
  22
  23 ~~ NOTE: For help with the syntax of this file, see:
  24 ~~ http://maven.apache.org/doxia/references/apt-format.html
  25
  26 Handling the API exceptions
  27
  28   This library provides the basic exception <<<APIException>>> that in the event
  29   of exceptional situations can inform the client application of the type of error
  30   that occurred in the process of using library methods.\
  31   This exception can notify you about two types of exception:
  32
  33 +-------
  34 public class APIException extends Exception {
  35
  36     public static enum Type {
  37         INFO,
  38         REQUEST
  39     }
  40     ...
  41 }
  42 +-------
  43
  44   You can get the type of exception that was thrown by using the method <<<APIException.getType()>>>.
  45
  46   The type <<<INFO>>> tells the client application that the exception that that has occurred
  47   is not critical and is not related to the inability to obtain useful information.
  48   The work of the application can be continued after detection of this type of exception without
  49   serious consequences but with some adjustments in the future working functionality.
  50
  51   The type <<<REQUEST>>> tells the client application that the exception that has occurred is associated
  52   with the process of obtaining useful information from the portal {{{http://snooker.org/}snooker.org}}
  53   or with the inability to handle the received information.\
  54   This type of exception can occur for several reasons:
  55
  56   <<1.>> The data passed to the API method is incorrect. This can occur in case of an incorrect
  57   input ID (tournament, player, etc.) or a <<null>> input parameter. In this case the application
  58   can continue to work after correction the transmitted parameters.
  59
  60   <<2.>> Inaccessibility of the communication channel (access to the portal).
  61   Information simply can not be obtained. In this case the client application can not continue
  62   to work until an Internet connection is established.
  63
  64   <<3.>> The portal API has changed. Incoming data can not be processed correctly.
  65   This case is the most significant. It means that the current version of the library
  66   can no longer be considered workable. It is necessary to check the availability of
  67   a more recent version of the library and if there is none then inform the developer about
  68   of a detected nonconformity between API library and portal {{{http://api.snooker.org/}api.snooker.org}}.