------
 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}}.