Project Polygene has retired. For details please refer to its Attic page.
Core Extension SPI
Zest™
Introduction
Tutorials
Javadoc
Samples
Core
Libraries
Extensions
Tools
Glossary 

Core Extension SPI

code

docs

tests

The Zest™ Core Runtime has a number of extension points, which we call the Qi4j Core Extension SPI. These are defined interfaces used only by the Core Runtime and never directly by application code. Extensions are assembled in applications during the bootstrap phase.

Table 20. Artifact

Group IDArtifact IDVersion

org.qi4j.core

org.qi4j.core.spi

2.1


There are currently 5 Core SPI extensions;

Zest™ Runtime Extensions implementations may depend on Zest™ Libraries, but Libraries are NOT ALLOWED to depend on Extensions. Applications code is NOT ALLOWED to depend on extensions. And application code SHOULD NOT depend on the Core Extension SPI. If you think that is needed, please contact qi4j-dev forum at Google Groups, to see if your usecase can be solved in a support manner, or that we need to extend the Core API to support it.

ValueSerialization SPI

Overview

The Zest™ Core Runtime use ValueSerialization to provide string representation of ValueComposites via their toString() method, and, their instanciation from the very same representation via the newValueFromSerializedState(..) method of the ValueBuilderFactory API.

If no ValueSerialization service is visible, a default implementation supporting the JSON format used but note that it won’t be available as a Service. So, in order to use the full ValueSerialization API a ValueSerialization service must be explicitely assembled in the Application. See the Extensions documentation for details.

Implementation notes

Simply implement ValueSerialization to create an extension for the ValueSerialization SPI. The Core SPI module provides adapters to create pull-parsing capable ValueSerializers and pull-parsing and tree-parsing capable ValueDeserializers.

The behaviour described here apply to all ValueSerialization services implemented using the Core SPI adapters. Note that nothing stops you from implementing an extension for the ValueSerialization SPI without relying on theses adapters.

Theses adapters are tailored for serialization mechanisms that support the following two structures that can be nested:

  • a collection of name/value pairs. In various languages, this is realized as an object, record, struct, dictionary, hash table, keyed list, or associative array,
  • an ordered list of values. In most languages, this is realized as an array, vector, list, or sequence ;

in other words, a JSON-like structure.

Special attention is taken when dealing with Maps. They are serialized as an ordered list of collections of name/value pairs to keep the Map order for least surprise. That way, even when the underlying serialization mechanism do not keep the collection of name/value pairs order we can rely on it being kept.

Here is a sample Map with two entries in JSON notation to make things clear:

[
    { "key": "foo",       "value": "bar"   },
    { "key": "cathedral", "value": "bazar" }
]

Among Plain Values (see the ValueSerialization API section) some are considered primitives to underlying serialization mechanisms and by so handed/come without conversion to/from implementations.

Primitive values can be one of:

  • String,
  • Boolean or boolean,
  • Integer or int,
  • Long or long,
  • Short or short,
  • Byte or byte,
  • Float or float,
  • Double or double.

Serialization is always done in a streaming manner using a pull-parsing based approach.

Deserialization is done in a streaming manner using a pull-parsing based approach except when encountering a ValueComposite. ValueComposite types are deserialized using a tree-parsing based approach.

All this means that you can serialize and deserialize large collections of values without filling the heap.

EntityStore SPI

Note

This SPI has no documentation yet. Learn how to contribute in Writing Documentation.

Cache SPI

Note

This SPI has no documentation yet. Learn how to contribute in Writing Documentation.

Indexing/Query SPI

Note

This SPI has no documentation yet. Learn how to contribute in Writing Documentation.

Metrics SPI

It is very easy to create an extension for the Metrics SPI, simply by implementing the MetricsProvider. If only a subset of the factories/types are supported, there is a convenience adapter call MetricsProviderAdapter in the Metrics SPI package.