# Package org.qi4j.api.common

Common API.

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  AppliesToFilter | Implementations of this interface can be specified in the @AppliesTo.

- Class Summary
  Class | Description
  --- | ---
  MetaInfo | Used to declare and access meta-info.
  QualifiedName | QualifiedName is a representation of Property names to their full declaration.
  TypeName | Represents a Type name.

- Enum Summary
  Enum | Description
  --- | ---
  Visibility | Visibility is a core concept in the Zest structure system.

- Exception Summary
  Exception | Description
  --- | ---
  ConstructionException | Thrown when a Fragment or object could not be instantiated.
  InvalidApplicationException | Thrown when an application is considered to not be constructed properly.

- Annotation Types Summary
  Annotation Type | Description
  --- | ---
  AppliesTo | Fragments that implement InvocationHandler and which should only be applied to methods that have a particular annotation or implement a known interface should use this annotation.
  Optional | Annotation to denote that something is optional.
  UseDefaults | Annotation to denote that the initial value of a Property will be the default value for the type if none is specified during construction.

## Package org.qi4j.api.common Description

## Common API.

The Common API package is a collection of really low-level types needed at the core of the Zest™ Runtime. It is also a collection of types that are not particularly cohesive, and effectively this package contains the loose ends that does not belong elsewhere.

In this package, you can safely ignore the following classes;

- MetaInfo
- QualifiedName
- TypeName

UNLESS you are into deep integration into the Zest™ Runtime.

### @AppliesTo and AppliesToFilter

This tandem of interface + annotation are primarily used for Generic Fragments, to indicate which methods on the interface the fragment should be applied to.

### @Optional

In Zest™, method arguments, property values and injected fields are not allowed to be null by default. To allow any of these to be null, i.e. undeclared, it is required that the argument, field or method is marked with the @Optional annotation.

### @UseDefaults

Since null is not allowed without the @Optional annotation, it can sometimes by tedious to initialize all the property values. And the @UseDefaults annotation allows us to declare that Zest™ should set the Property to a default value. These are either the pre-defined ones, or can be set per property declaration during the assembly.

### @Visibility

Visibility is another innovative concept in Zest™, which leverage the structure system (Application, Layer, Module) to limit the 'reach' when requesting composites and objects. The Visibility is declared per Composite/Object, preferably in the most restrictive mode possible, and the visibility resolver will ensure a predictable resolution algorithm;

1. Search the module of the caller first. If one and only one composite type fulfilling the request is available return that to the caller. If two or more are found, throw an AmbiguousTypeException. If no composite found continue to the next step.
2. Search all modules in the Layer of the caller for composite that has a declaration other than `Visibility.module`. If one and only one composite type fulfilling the request is available return that to the caller. If two or more are found, throw an AmbiguousTypeException. If no composite found continue to the next step.
3. Search all modules in the Layer(s) (if any) directly below of the caller for composite that has a declaration of `Visibility.application`. If one and only one composite type fulfilling the request is available return that to the caller. If two or more are found, throw an AmbiguousTypeException. If no composite found continue to the next step.
4. Throw an NoSuchCompositeException (or related) exception.