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