# Package org.apfloat.spi

package org.apfloat.spi
The apfloat Service Provider Interface (SPI).

The apfloat API is a high-level API that defines algorithms on the level of e.g. the Newton iteration for the inverse of a number. Behind this high-level API there is a lot of low-level functionality that makes all the arbitrary precision arithmetic happen. The digits of a large number are stored in an array of `int`s, for example. In fact, an `Apfloat` is structurally just a pointer to an `ApfloatImpl`, and most of the functionality of the Apfloat class is simply delegated to the underlying ApfloatImpl.

The apfloat SPI defines the general interface for the low-level things that must happen behind the scenes of the high-level API. An actual implementation of the SPI can be optimized for different things, for example:

- Size of numbers: different algorithms are efficient for numbers with with 1000 or 1000000 digits. This applies both to the actual storage method of the data, and the mathematical algorithms used for e.g. multiplying numbers.
- Memory consumption vs. performance: different types of Fast Fourier Transform (FFT) based algorithms can be used to find a suitable trade-off between memory consumption and performance.
- Hardware architecture: 32-bit and 64-bit systems handle `int` and `long` type elements correspondingly most efficiently, for example. Some systems perform floating-point operations (with `float` or `double` type elements) faster than integer operations (`int` or `long`).
- Complexity: a more complex implementation may be optimized for different cases, however more code will take more space and use more memory. This may be a concern on some systems (e.g. mobile devices).

A Service Provider is only required to implement the `BuilderFactory` interface, and actually only the `BuilderFactory.getApfloatBuilder()` method in this interface. All apfloat implementations (`ApfloatImpl`) are created through the `ApfloatBuilder` interface's methods. The rest of the interfaces in the SPI exist only for the convenience of the default apfloat SPI implementations (`org.apfloat.internal`).

The apfloat SPI suggests the usage of various patterns, as encouraged by the specification of all the interfaces in the SPI. These patterns include:

- Abstract factory pattern, for getting instances of the various builders, as well as other types of components built by the different builders (`ApfloatBuilder`, `DataStorageBuilder`, `ConvolutionBuilder`, `NTTBuilder`).
- Factory method pattern; obviously the abstract factories use factory methods to create instances of objects.
- Builder pattern: an `ApfloatImpl` needs various "parts" for its structural construction (`DataStorage`) as well as its behavior (`ConvolutionStrategy`). Builders are used to build the different sub-parts needed, and the ApfloatImpl itself only knows the high-level algorithm for how the parts are used and related. The construction of the sub-part details is left for the builders, and the ApfloatImpl accesses the parts only via an interface.
- Strategy pattern: for multiplying numbers, completely different algorithms are optimal, depending on the size of the numbers. The `ConvolutionStrategy` defines different convolution algorithms to be used in the multiplication. For very large numbers, a transform-based convolution can be used, and even a different transform strategy can be specified via the `NTTStrategy` interface.
- Iterators are used for iterating through `DataStorage` elements in a highly flexible manner. The base class is `DataStorage.Iterator`. For example, a data storage that uses a simple array to store the entire data set in memory can return a simple iterator that goes through the array element by element. In comparison, a data storage that stores the data in a disk file, can have an iterator that reads blocks of data from the file to a memory array, and then iterates through the array, one block at a time.
- Singleton pattern, assumed to be used in the `BuilderFactory` class, as there should be no need to have more than one instance of each builder class. Also the BuilderFactory instance itself is a singleton, within an `ApfloatContext`.
- Bridge pattern: the SPI itself is the bridge pattern. An `Apfloat` provides a simple high-level programming interface and the complex technical implementation details are delegated to an `ApfloatImpl`. The Apfloat class can be subclassed for additional functionality, and independent of that, different subclasses of an ApfloatImpl can be used to optimize the implementation.

Associations of the SPI classes are shown in a class diagram format below:

The class implementing `BuilderFactory` that is used in creating apfloat implementations is defined in the `ApfloatContext`. You can set the BuilderFactory instance programmatically by calling `ApfloatContext.setBuilderFactory(BuilderFactory)`, for example:

    BuilderFactory builderFactory = new MyBuilderFactory();
    ApfloatContext.getContext().setBuilderFactory(builderFactory);

It's a lot easier to specify this to happen automatically whenever your program starts. To do this just specify the BuilderFactory class name in the `apfloat.properties` file (or the apfloat ResourceBundle if you use one). For example, the `apfloat.properties` file might contain the line:

    builderFactory=org.mycompany.MyBuilderFactory

For more details about configuring the apfloat BuilderFactory, see the documentation for `ApfloatContext`.

See Also:
  - `org.apfloat.internal`

- Related Packages
  Package
  Description
  org.apfloat
  The apfloat Application Programming Interface (API).
  org.apfloat.aparapi
  Transforms for using a GPU via the aparapi library.
  org.apfloat.calc
  Arbitrary precision calculator interactive application.
  org.apfloat.internal
  Default implementations of the apfloat Service Provider Interface (SPI).
  org.apfloat.jscience
  JScience wrapper for apfloat.
  org.apfloat.samples
  Sample applications demonstrating apfloat use.
- Class
  Description
  AdditionBuilder<T>
  Interface of a factory for creating addition strategies.
  AdditionStrategy<T>
  Generic addition strategy.
  ApfloatBuilder
  An ApfloatBuilder contains factory methods to create new instances of `ApfloatImpl` implementations.
  ApfloatImpl
  Interface for apfloat implementations.
  ArrayAccess
  The `ArrayAccess` class simulates a `C` language pointer.
  BuilderFactory
  A `BuilderFactory` object contains factory methods for building the various parts of an apfloat using the Builder pattern.
  CarryCRTBuilder<T>
  Interface of a factory for creating carry-CRT related objects.
  CarryCRTStepStrategy<T>
  Interface for performing the steps of a carry-CRT operation in a convolution.
  CarryCRTStrategy
  Interface for performing the final step of a three-modulus Number Theoretic Transform based convolution.
  ConvolutionBuilder
  Interface of a factory for creating convolutors.
  ConvolutionStrategy
  Generic convolution strategy.
  DataStorage
  Generic data storage class.
  DataStorage.Iterator
  Iterator for iterating through elements of the data storage.
  DataStorageBuilder
  Interface for determining a suitable storage type for data of some expected size.
  ExecutionBuilder
  Interface of a factory for creating execution related objects.
  ExecutionStrategy
  Thread execution operations.
  Factor3NTTStepStrategy
  Steps for the factor-3 NTT.
  FilenameGenerator
  Class for generating filenames for temporary files.
  MatrixBuilder
  Interface of a factory for creating matrix related objects.
  MatrixStrategy
  Matrix operations.
  NTTBuilder
  Interface of a factory for creating Number Theoretic Transforms.
  NTTConvolutionStepStrategy
  Steps for a three-NTT convolution.
  NTTStepStrategy
  Steps for the six-step or two-pass NTT.
  NTTStrategy
  Number Theoretic Transform (NTT) strategy.
  RadixConstants
  Constants related to different radixes.
  Util
  Miscellaneous utility methods.