//////////////////////
 * 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.
//////////////////////

[[howto-contextual-fragments,Use Contextual Fragments]]
= Use contextual fragments =
Contextual fragments are fragments that are added to the composites during assembly time. That means that they are not
present in the composite declarations, but a start-up decision what should be added. Once the application instance is
created, it is no longer possible to modify which fragments are attached.

Typical use-case is tracing and debugging. Other potential uses are additional security or context interfaces needing
access to internal mixins not originally intended for, such as GUI frameworks doing reflection on certain composites.
We strongly recommend against using this feature, as it is not needed as commonly as you may think.

NOTE: Constraints are not supported to be contextual at the moment.

If you want to reproduce what's explained in this tutorial, remember to depend on the Core Bootstrap artifact:

include::../../../../core/bootstrap/build/docs/buildinfo/artifact.txt[]

At runtime you will need the Core Runtime artifact too. See the <<howto-depend-on-polygene>> tutorial for details.

The mixins, sideeffects and concerns are added during the bootstrap phase. It is very straight-forward;

[snippet,java]
-----------
source=manual/src/main/java/org/apache/polygene/manual/recipes/contextualFragments/TraceAll.java
tag=assemble
-----------

In the example above, we add the TraceAllConcern from the Logging Library if the system property "trace.all" is true.
If the system property is not set to true, there will be no TraceAllConcern on the PinSearchService.

Concerns that are added in this way will be at the top of the method invocation stack, i.e. will be the first one to be
called and last one to be completed.

SideEffects that are added in this way will be the last one's to be executed.
