1. The base Package

As every thing in the world jKiska needs a kind of parent respective something that serves as a root. jKiska's root package is named org.xshare.base and all other packages you will come across within this guide or the JavaDoc API are below it. This naming keeps the namespace above free and offers the possiblity to potential other jKiska projects to create their own package namespace under org.xshare without any danger of a namespace collision.

But this package is not only a organisational one. It contains also exception classes which can be used in other packages, but don't belong to a specific one. These exceptions could be divided in two groups: project public exceptions and project private exceptions.

1.1. API Public And API Private Exceptions

Both exception groups doesn't differ so much, only the way how they are used is different. The frist group contains all the exceptions which are thrown by public methods of the API and are mentioned in the API documentation. For example the java.io.IOExceptions or the java.util.NoSuchElementException would be API public exception if they would belong to jKiska. This exceptions are intended for the user to signal him some problems.

The other group contains the so called API private exceptions. These are in opposite of the public ones used within private and protected methods and classes to assert the internal method calls and are not intended for the end user. May an small example will help to understand it. Let us imagine there is a class Antic with an private method shutdownSystem() which takes an int value as parameter and this parameter must be between 10 and 27.

      private method shutdown(int aIntValue)
      {
        if (aIntValue < 11 && aIntValue > 27)
          throw new IllegaljKiskaArgumentException("...");

        ...
      }
    

Since this is a private method which can be called only from methods in the same class, the calling method of this method is responsible for the value passed to this method. In case this contract between the shutdown() method and its caller is violated a IllegaljKiskaArgumentException [1] is thrown.

All methods using and throwing API private exceptions are not intended for the end user - remember they are either private or protected. Therefore the normal user shouldn't be able to produce a situation there an instance of an API private exception will be thrown.

1.2. Public Exception Classes In The Base Package

1.2.1. OverRunException

Signals that a numerical value of the type int, float, double or long has become larger or smaller then the defined maximum or minimum.



[1] The IllegaljKiskaArgumentException belongs to so called the API private exceptions.