///////////////////////////////////////////////////////////////
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you 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.
///////////////////////////////////////////////////////////////

:leveloffset: 1

[[glossary,Glossary Section]]
= Glossary&nbsp; =

== Glossary ==

There are a lot of concepts in Zest™ which may have different meanings in other contexts. So in true DDD-style
ubiquitous language, we are here listing the definitions of the terms and concepts that are being used.

[glossary]
[[def-abstract-mixin,Abstract Mixin]]Abstract Mixin::
+
--
An Abstract Mixin is an implementation of the <<def-mixin-type>> interface, but is an abstract class and has not
implemented all the methods.

The Zest™ runtime can use multiple <<def-mixin,Mixins>> for each <<def-mixin-type>> interface. It is also possible to let
a <<def-generic-mixin>> handle the remaining missing methods.
--


[[def-abstract-modifier,Abstract Modifier]]Abstract Modifier::
+
--
Abstract Modifiers are <<def-modifier,Modifiers>> that do not implement all the methods of the <<def-mixin-type>>
interface.

This works essentially in the same manner as the <<def-abstract-mixin>>. And the methods that are not implemented
will not be part of the <<def-invocation-stack>> of those methods.
--


[[def-application,Application]]Application::
+
--
Application is the top level concept handled by the Zest™ runtime instance. It holds the information about the
<<def-layer,Layers>> in the application architecture. See <<def-structure>> for more information.

There is one and only one Application instance per Zest™ Runtime instance.
--


[[def-application-mode,Application Mode]]Application Mode::
+
--
During the Bootstrap phase an <<def-application>> is given a Mode that can be 'test', 'development', 'staging' or
'production'.

See <<core-bootstrap-assembly>>.
--


[[def-association,Association]]Association::
+
--
An Association is a reference to an <<def-entitycomposite>>.

References to <<def-entitycomposite,Entities>> must be maintained in <<def-association,Associations>>. It is illegal to
define a <<def-property>> with an <<def-entitycomposite>> as its type.
--


[[def-composite,Composite]]Composite::
+
--
A Composite is an instance of a <<def-composite-type>>.

However, we often speak of Composites when we actually mean CompositeType, similarly as we often speak of objects
when we really are talking of classes in OOP.
--


[[def-composite-context,Composite Context]]Composite Context::
+
--
A Composite Context is a mechanism to separate the state of a <<def-transientcomposite>> across two or more threads.
If a thread modifies a value, only that thread will see the changes, another thread will have its values protected
by the thread boundaries. Use-cases for this include user credentials on which behalf the thread is executing.
--


[[def-composite-metatype,Composite Meta Type]]Composite Meta Type::
+
--
There are 5 Composite Meta Types defined in Zest, which each share the composition features but have distinct
semantic differences.

* <<def-entitycomposite>>
* <<def-valuecomposite>>
* <<def-servicecomposite>>
* <<def-configurationcomposite>> (subtype of EntityComposite)
* <<def-transientcomposite>>
--


[[def-composite-type,Composite Type]]Composite Type::
+
--
CompositeType is the Java interface that declares the composition, from which <<def-composite>> instances can be
created.

Composite Type interfaces must be a sub-type of one of the 5 <<def-composite-metatype,Composite Meta Types>> defined in
Zest™ otherwise it can not be instantiated.
--


[[def-concern,Concern]]Concern::
+
--
A concern is a stateless <<def-fragment>>, shared between invocations, that acts as an interceptor of the call to
the <<def-mixin>>. The Concern is a Java class, that either implements the <<def-mixin-type>> it can be used on, or
java.lang.reflect.InvocationHandler which allows it to be used on any arbitrary <<def-mixin-type>>.

Concerns have many purposes, but they are not intended to produce side effects (see <<def-sideeffect>>). Use-cases
involves;

* Transaction handling.
* Call Tracing.
* User security.

Concerns are established by the use of the @Concerns annotation on composites.

Concern is one of the 3 kinds of <<def-modifier,Modifiers>> defined in Zest.
--


[[def-configurationcomposite,Configuration Composite]]Configuration Composite::
+
--
Service Composites can have configuration associated to it and that is done via
<<def-configurationcomposite,Configuration Composites>>, which are a subtype of <<def-entitycomposite>>, as they are
stored permanently in configured Entity Stores. Configuration Composites are also initialized automatically from
properties files first time. Note that on consequent start-ups the properties file is not read, as the configuration is
read from the EntityStore.

ConfigurationComposite is one of the 5 <<def-composite-metatype,Composite Meta Types>> defined in Zest.

See <<howto-configure-service>> to learn how to use Configuration Composites.
--


[[def-constraint,Constraint]]Constraint::
+
--
Constraints are a kind of validators, which are consulted prior to invoking the method call. Zest™ currently only
supports ParameterConstraints on methods and value constraints on <<def-property,Properties>>, but future versions will
include Constraint types for checking complete method calls and return values.

See <<core-api-constraint>> for better understanding of its details.

See <<library-constraints>> for ready to use Constraints.

See <<howto-create-constraint>> to learn how to write your own Constraints.

Constraint is one of the 3 kinds of <<def-modifier,Modifiers>> defined in Zest.
--


[[def-entitycomposite,Entity Composite]]Entity Composite::
+
--
An Entity Composite, or just Entity for short, is a persisted composite with an <<def-identity>>. An entity only has
scope within an <<def-unitofwork>> and is therefor inherently thread-safe.

EntityComposite is one of the 5 <<def-composite-metatype,Composite Meta Types>> defined in Zest.
--


[[def-fragment,Fragment]]Fragment::
+
--
A part of the implementation of a <<def-composite>>. There are 4 fragment types:

* <<def-mixin>>
* <<def-concern>>
* <<def-constraint>>
* <<def-sideeffect>>.
--


[[def-generic-fragment,Generic Fragment]]Generic Fragment::
+
--
Generic Fragments are <<def-fragment,Fragments>> that implements java.lang.reflect.InvocationHandler and potentially
capable of being used for all <<def-mixin-type,MixinTypes>>. This is the direct opposite of the Typed Fragments, which
implements the <<def-mixin-type>> interface.
--


[[def-generic-mixin,Generic Mixin]]Generic Mixin::
+
--
A Generic Mixin implements the java.lang.reflect.InvocationHandler. The invoke() method will be called for all
<<def-mixin-type>> methods that the <<def-mixin>> has been matched with, through the matching rules.

It is potentially possible that the Generic Mixin also implements the <<def-mixin-type>> interface. In that case, the
concrete methods will be called, but if the <<def-mixin>> is also an abstract class, then the invoke() method will be
called for the methods that has been match but are not present.
--


[[def-identity,Identity]]Identity::
+
--
TODO

This term has no definition yet. Learn how to contribute in <<community-docs>>.
--


[[def-invocation-stack,Invocation Stack]]Invocation Stack::
+
--
For each method, Qi4J will create and re-use an Invocation Stack. It will be built with the sequence of
<<def-modifier,Modifiers>> and an end-point that will link into the stateful <<def-mixin>>.

It is important to recognize that, for memory footprint reasons, Invocation Stacks are shared across
<<def-composite,Composites>> of the same <<def-composite-type>>. They are however thread-safe, in that Zest™ will never
bind the same Invocation Stack to more than one <<def-composite>> instance during a method call, but that between method
invocations the <<def-modifier,Modifiers>> in the Invocation Stack can not assume that it is bound to the same
<<def-composite>> instance. Therefor, <<def-modifier,Modifiers>> are not expected to keep state between method
invocations, and when it needs to do that, then it should reference a <<def-mixin>> via the @This annotation. Zest™ will
during the binding of the Invocation Stack to the <<def-composite>>, also ensure that all referenced
<<def-mixin,Mixins>> are correctly injected in the Invocation Stack.
--


[[def-layer,Layer]]Layer::
+
--
Zest™ promotes a Layered application design, where Layers can only access lower Layers and not higher Layers or Layers at
the same level.
--


[[def-manyassociation,ManyAssociation]]ManyAssociation::
+
--
TODO

This term has no definition yet. Learn how to contribute in <<community-docs>>.
--


[[def-metainfo,MetaInfo]]MetaInfo::
+
--
TODO

This term has no definition yet. Learn how to contribute in <<community-docs>>.
--


[[def-mixin,Mixin]]Mixin::
+
--
The Mixin is the instance providing the stateful representation of the <<def-mixin-type>>. This can either be a class
implementing the <<def-mixin-type>> or a java.lang.reflect.InvocationHandler that is generic to handle any or a subset
of <<def-mixin-type>>.
--


[[def-mixin-type,MixinType]]MixinType::
+
--
The MixinType is the static type of a part of the <<def-composite>>. The MixinType is an interface that defines the methods
to be exposed in the <<def-composite>>.
--


[[def-modifier,Modifier]]Modifier::
+
--
Modifiers are stateless interceptors of method calls, that forms an <<def-invocation-stack>>. The top of the
<<def-invocation-stack>> is linked to the <<def-composite>> invocation handler and the bottom of the
<<def-invocation-stack>> is linked to the <<def-mixin,Mixins>>. <<def-invocation-stack,Invocation Stacks>> are shared,
so Modifiers must assume that the member fields will only be valid within a single method invocation.

There are 3 kinds of Modifiers;

* <<def-constraint>>
* <<def-concern>>
* <<def-sideeffect>>
--


[[def-module,Module]]Module::
+
--
Modules defines the scope of the <<def-composite,Composites>>. Modules are wired with Assemblies, and can expose
<<def-composite,Composites>> as visible. Non-visible <<def-composite,Composites>> are not reachable from other Modules.
--


[[def-namedassociation,NamedAssociation]]NamedAssociation::
+
--
TODO

This term has no definition yet. Learn how to contribute in <<community-docs>>.
--


[[def-private-mixin,Private Mixin]]Private Mixin::
+
--
When a @This injection refers to a <<def-mixin-type>> which is not extended by the <<def-composite-type>> the former
becomes a private <<def-mixin-type>>.
--


[[def-property,Property]]Property::
+
--
TODO

This term has no definition yet. Learn how to contribute in <<community-docs>>.

See the <<howto-leverage-properties>> how-to.
--


[[def-servicecomposite,Service composite]]Service Composite::
+
--
Service Composite is a subtype of <<def-composite>>, and has a range of features built into it.

ServiceComposite is one of the 5 <<def-composite-metatype,Composite Meta Types>> defined in Zest.

See the <<core-api-service,Service Composite chapter>>.
--


[[def-sideeffect,SideEffect]]SideEffect::
+
--
A side effect is a stateless <<def-fragment>>, shared between invocations, that acts as an interceptor of the call to
the <<def-mixin>>. The SideEffect is a Java class, that either implements the <<def-mixin-type>> it can be used on, or
java.lang.reflect.InvocationHandler which allows it to be used on any arbitrary <<def-mixin-type>>.

SideEffects are executed after the completion of the method invocation and therefore cannot change parameters nor
eventually returned object.

SideEffects have many purposes. Use-cases
involves;

* Sending emails.
* Call Tracing.
* Domain side effects modeling.

SideEffects are established by the use of the @SideEffects annotation on composites.

SideEffect is one of the 3 kinds of <<def-modifier,Modifiers>> defined in Zest.
--


[[def-structure,Structure]]Structure::
+
--
Zest™ promotes a conventional view of application structure, that computer science has been using for decades.

The definition is as follows;

* One <<def-application>> per Zest™ runtime instance.
* One or more <<def-layer,Layers>> per <<def-application>>.
* Zero, one or more <<def-module,Modules>> per <<def-layer>>.
* Zero, one or more Assemblies per <<def-module>>.

The principle of this Structure is to assist the programmer to create well modularized applications, that are easily
extended and maintained. Zest™ will restrict access between <<def-module,Modules>>, so that code can only reach
<<def-composite,Composites>> and Objects in <<def-module,Modules>> (including itself) of the same or lower
<<def-layer,Layers>>.

Each <<def-layer>> has to be declared which lower <<def-layer,Layer(s)>> it uses, and it is not allowed that a lower
<<def-layer>> uses a higher <<def-layer>>, i.e. cyclic references.
--


[[def-transientcomposite,TransientComposite]]TransientComposite::
+
--
TransientComposite is a <<def-composite-metatype>> for all other cases. The main characteristics are;

* It can not be serialized nor persisted.
* hashcode/equals are not treated specially and will be delegated to <<def-fragment,Fragment(s)>> implementing those methods.
* It can not be used as a <<def-property>> type.
--


[[def-unitofwork,UnitOfWork]]UnitOfWork::
+
--
TODO

This term has no definition yet. Learn how to contribute in <<community-docs>>.
--


[[def-valuecomposite,ValueComposite]]ValueComposite::
+
--
Usage of value objects is one of the most ignored and best return-on-investment the programmer can do. Values are
immutable and can be compared by value instead of memory reference. Concurrency is suddenly not an issue, since either
the value exists or it doesn't, no need for synchronization. Values are typically very easy to test and very robust to
refactoring.

Zest™ defines values as a primary meta type through the ValueComposite, as we think the benefits of values are great.
The ValueComposite is very light-weight compared to the <<def-entitycomposite>>, and its value can still be persisted as
part of an <<def-entitycomposite>> via a <<def-property>>.

The characteristics of a ValueComposite compared to other <<def-composite-metatype,Composite Meta Types>> are;

* It is Immutable.
* Its equals/hashCode works on the values of the ValueComposite.
* Can be used as <<def-property>> types, but will not be indexed and searchable.
--