Repository: polygene-java Updated Branches: refs/heads/develop e21738bb2 -> 05ddab16a
More documentation Signed-off-by: niclas <[email protected]> Project: http://git-wip-us.apache.org/repos/asf/polygene-java/repo Commit: http://git-wip-us.apache.org/repos/asf/polygene-java/commit/14125f65 Tree: http://git-wip-us.apache.org/repos/asf/polygene-java/tree/14125f65 Diff: http://git-wip-us.apache.org/repos/asf/polygene-java/diff/14125f65 Branch: refs/heads/develop Commit: 14125f658eb461843f25f1f0f08811e42dcee68a Parents: e21738b Author: niclas <[email protected]> Authored: Sun Jun 4 17:23:52 2017 +0800 Committer: niclas <[email protected]> Committed: Sun Jun 4 17:23:52 2017 +0800 ---------------------------------------------------------------------- core/api/src/docs/api.txt | 2 +- core/api/src/docs/composition.txt | 10 +- core/api/src/docs/dependency-injection.txt | 136 +++++++++++++++++++ core/api/src/docs/fragment.txt | 10 +- core/api/src/docs/layer.txt | 24 ++++ core/api/src/docs/module.txt | 12 ++ core/api/src/docs/structure.txt | 35 +---- core/api/src/docs/visibility.txt | 16 +++ .../runtime/composite/CompositeMethodModel.java | 2 +- manual/src/docs/userguide/extensions.txt | 4 + manual/src/docs/userguide/glossary.txt | 8 ++ 11 files changed, 215 insertions(+), 44 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/polygene-java/blob/14125f65/core/api/src/docs/api.txt ---------------------------------------------------------------------- diff --git a/core/api/src/docs/api.txt b/core/api/src/docs/api.txt index fa7188e..0523cb6 100644 --- a/core/api/src/docs/api.txt +++ b/core/api/src/docs/api.txt @@ -62,7 +62,7 @@ include::objects.txt[] :leveloffset: {level3} -// include::dependency-injection.txt[] +include::dependency-injection.txt[] :leveloffset: {level3} http://git-wip-us.apache.org/repos/asf/polygene-java/blob/14125f65/core/api/src/docs/composition.txt ---------------------------------------------------------------------- diff --git a/core/api/src/docs/composition.txt b/core/api/src/docs/composition.txt index 1a60a3a..895cca0 100644 --- a/core/api/src/docs/composition.txt +++ b/core/api/src/docs/composition.txt @@ -23,15 +23,7 @@ In Polygene, we use the term Assembly for the second case of composition. See se Composition will allow library authors a new level of flexibility in how functionality is provided to client code. More on that later. -== Fragments == - -There are 4 types of Fragments in Polygene; - - * <<core-api-mixin>> - The state carrying part of a Composite. - * <<core-api-constraint>> - Rules for in and out arguments, typically used for validation. - * <<core-api-concern>> - Interceptor of method calls. General purpose use, often for cross-cutting behaviors. - * <<core-api-sideeffect>> - Executed after the method call has been completed, and unable to influence the - outcome of the method call. +include::fragment.txt[] == Composites == http://git-wip-us.apache.org/repos/asf/polygene-java/blob/14125f65/core/api/src/docs/dependency-injection.txt ---------------------------------------------------------------------- diff --git a/core/api/src/docs/dependency-injection.txt b/core/api/src/docs/dependency-injection.txt index fc7aac6..d9fabca 100644 --- a/core/api/src/docs/dependency-injection.txt +++ b/core/api/src/docs/dependency-injection.txt @@ -16,3 +16,139 @@ * specific language governing permissions and limitations * under the License. /////////////////////////////////////////////////////////////// + +[[core-api-dependency-injection,Dependency Injection]] += Dependency Injection = + +Polygene has a rather sophisticated dependency injection system, which is based around the <<core-api-modules>> +and <<core-api-visibility>> concepts. The dependency injection system also need help to keep the injection scopes +separated. The following injection scopes exists, some more common than others; + + * ++@This++ - injection of fragment from the same Composite instance. + * ++@Structure++ - injection of <<core-api-structure>> organized types. + * ++@Service++ - injection of services. + * ++@Uses++ - injection of construction injected objects + * ++@Invocation++ - injection of parts related to the current method invocation. + * ++@State++ - injection of state of the composite instance + * Custom injection scopes - managed through ++@AppliesTo++ and ++AppliesToFilter++ declarations. + +[[core-api-this,@This]] +== @This == +++@This++ is equivalent to the ++this++ pointer in the Java language, but refers to any part of the current +<<core-api-composite>>. This can either be a declared mixin type, or if not declared will be a <<def-private-mixin>>. + +=== Example === + +We can simply request the injection of any type of the composite that we belong to, such as; + +[source,java] +-------------- +@Mixins( { OrderMixin.class, ShippingMixin.class } ) +public interface Order extends HasShippingInformation +{ + : +} + +public abstract class OrderMixin + implements Order +{ + @This + private HasShippingInformation shipping; +} +-------------- + +But we can have <<def-private-mixin>> instead, where the injected mixin type will be automatically added to the +composite. + +[source,java] +-------------- +@MIxins( OrderMixin.class ) +public interface Order +{ + : +} + +public class OrderMixin + implements Order +{ + @This + private DiscountRate discount; +-------------- + +[[core-api-structure-injection,@Structure]] +== @Structure == +The ++@Structure++ injection scope is all about the types involved in the Application <<core-api-structure>> system. +The possible types are; + + * Application + * ApplicationDescriptor + * Layer + * LayerDescriptor + * Module + * ModuleDescriptor + * ModuleSPI + * UnitOfWorkFactory + * EntityBuilderFactory + * ValueBuilderFactory + * TransientBuilderFactory + * ObjectFactory + * QueryBuilderFactory + * ServiceFinder + * PolygeneAPI + * PolygeneSPI + +[[core-api-service,@Service]] +== @Service == +Services are injected either in a number of ways, either direct, via List or via ServiceReference types. The following +combinations are allowed; + +[source,java] +-------------- + @Service + private MyService service; + + @Service + private Iterable<MyService> services; + + @Service + private ServiceReference<MyService> service; + + @Service + private Iterable<ServiceReference<MyService>> services; +-------------- + +If service is not declared ++instantiateOnStartup++ during assembly, then the service will be activated on first +method invocation, and not on injection. This means that any reflection on the injected instance, may result in +unexpected behavior. + +[[core-api-uses,@Uses]] +== @Uses == +<<def-object>> and <<def-valuecomposite>> can be created with ++uses()++ declarations. This allows injection of +arbitrary types to these meta types. Only type matching will occur, so for instance only one String can be injected +this way. + +If a ++@Uses++ declaration can not be satisfied from the injected objects via ++uses()++ builder method, then +if the ++@Uses++ injection is not ++@Optional++ the Polygene runtime will attempt to (in this order) + + * Instantiate a visible <<def-transientcomposite>> + * Instantiate a visible <<def-object>> + * Instantiate a plain object with this Composite instance as a single constructor argument. + +If the ++@Uses++ is ++@Optional++ then no implict object creation will take place. + +[[core-api-invocation,@Invocation]] +== @Invocation == +++@Invocation++ injection scope is all about the current method call. It is possible to inject the following types; + + * The ++Method++ being executed. + * Any annotation type that the method is annotated with. + * An ++Iterable++ of either of the above + +[[core-api-state,@State]] +== @State == +This injection scope can inject either a ++StateHolder++ which allows inspection of current state of the Composite, +or it can inject any declared <<def-property>>, <<def-assocation>>, <<def-manyassociation>> or +<<def-namedassociation>>. + +[[core-api-custom-injection,Custom Injection Scopes]] +== Custom Injection Scopes == http://git-wip-us.apache.org/repos/asf/polygene-java/blob/14125f65/core/api/src/docs/fragment.txt ---------------------------------------------------------------------- diff --git a/core/api/src/docs/fragment.txt b/core/api/src/docs/fragment.txt index 3edbf3b..ef68223 100644 --- a/core/api/src/docs/fragment.txt +++ b/core/api/src/docs/fragment.txt @@ -12,7 +12,8 @@ ////////////////////// [[core-api-fragment,Fragment]] -= Fragment = +== Fragment == + Composites should be perceived as single units, although they consist of many Java classes and instances. Some of those Java instances are not even belonging to a particular instance in runtime, but such details can and should be ignored by the developer. Developers should think of the Composite as a single concept, and not be concerned @@ -21,6 +22,13 @@ about its internal structure. The Composite is composed by declaring the parts it forms in the Composite Type interface declaration. Technically speaking, Composite Type is the only Fragment that is required to exist. The other Fragments are optional. +There are 4 types of Fragments in Polygene; + + * <<core-api-mixin>> - The state carrying part of a Composite. + * <<core-api-constraint>> - Rules for in and out arguments, typically used for validation. + * <<core-api-concern>> - Interceptor of method calls. General purpose use, often for cross-cutting behaviors. + * <<core-api-sideeffect>> - Executed after the method call has been completed, and unable to influence the outcome of the method call. + There are one very important thing to know about Fragments; *ONLY Mixins can maintain inter-method state.* http://git-wip-us.apache.org/repos/asf/polygene-java/blob/14125f65/core/api/src/docs/layer.txt ---------------------------------------------------------------------- diff --git a/core/api/src/docs/layer.txt b/core/api/src/docs/layer.txt new file mode 100644 index 0000000..d3484f4 --- /dev/null +++ b/core/api/src/docs/layer.txt @@ -0,0 +1,24 @@ +////////////////////// + * Licensed 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. +////////////////////// + +[[core-api-layer,Layer]] += Layer = +A Polygene⢠Application must consist of at least one layer. More layers are common, often dividing the application along the +common architectural diagrams used on whiteboards, perhaps with a UI layer at the top, followed by a service or application +layer, then with a domain layer and finally some persistence layer at the bottom. + +Polygene⢠enforces this layering by requiring the <<core-bootstrap-assembly>> to declare which layer uses which other layer. And +<<core-api-visibility>> rules define that layers below can not locate composites in layers above. Also, defining that +"Layer1 uses Layer2" and "Layer2 uses Layer3" does NOT imply that Layer1 has <<core-api-visibility>> to Layer3. If that +is wanted, then it must be declared explicitly. + http://git-wip-us.apache.org/repos/asf/polygene-java/blob/14125f65/core/api/src/docs/module.txt ---------------------------------------------------------------------- diff --git a/core/api/src/docs/module.txt b/core/api/src/docs/module.txt index eb191a9..4fd9fbf 100644 --- a/core/api/src/docs/module.txt +++ b/core/api/src/docs/module.txt @@ -11,3 +11,15 @@ * and limitations under the License. ////////////////////// +[[core-api-module,Module]] += Module = +Modules are logical compartments to assist developers in creating and maintaining well modularized code. A Module only +belongs to a single Layer, but many Modules can exist in the same Layer. Composite access is limited to; + + * Composites within the same Module, with Visibility set to Visibility.module (default). + * Composites from Modules in the same Layer, with Visibility set to Visibility.layer + * Composites from Modules in Layers below, with Visibility set to Visibility.application + +Modules contains a lot of the Polygene⢠infrastructure, which are the enforcers of these wise modularization principles. + +It is not possible to modify the Modules, their resolution nor binding in any way after the application starts. http://git-wip-us.apache.org/repos/asf/polygene-java/blob/14125f65/core/api/src/docs/structure.txt ---------------------------------------------------------------------- diff --git a/core/api/src/docs/structure.txt b/core/api/src/docs/structure.txt index 04952fe..2c91e77 100644 --- a/core/api/src/docs/structure.txt +++ b/core/api/src/docs/structure.txt @@ -29,38 +29,9 @@ in Modules (including itself) of the same or lower Layers. Each Layer has to be declared which lower Layer(s) it uses, and it is not allowed that a lower Layer uses a higher Layer, i.e. cyclic references. -[[core-api-application,Application]] -= Application = -Every Polygene⢠runtime has _one and only one_ Application in it. It is possible to run multiple Polygene⢠runtimes in the same -JVM, and it is even possible to embed a Polygene⢠runtime within a Polygene⢠Application, but there can only be one Application -in a Polygene⢠runtime. +include::application.txt[] -An Application is then broken into layers and modules are placed within those layers. Composites are placed within -modules. This forms the Application Structure and is enforced by the Polygene⢠runtime. +include::layer.txt[] -[[core-api-layer,Layer]] -= Layer = -A Polygene⢠Application must consist of at least one layer. More layers are common, often dividing the application along the -common architectural diagrams used on whiteboards, perhaps with a UI layer at the top, followed by a service or application -layer, then with a domain layer and finally some persistence layer at the bottom. +include::module.txt[] -Polygene⢠enforces this layering by requiring the <<core-bootstrap-assembly>> to declare which layer uses which other layer. And -<<core-api-visibility>> rules define that layers below can not locate composites in layers above. Also, defining that -"Layer1 uses Layer2" and "Layer2 uses Layer3" does NOT imply that Layer1 has <<core-api-visibility>> to Layer3. If that -is wanted, then it must be declared explicitly. - -[[core-api-module,Module]] -= Module = -Modules are logical compartments to assist developers in creating and maintaining well modularized code. A Module only -belongs to a single Layer, but many Modules can exist in the same Layer. Composite access is limited to; - - * Composites within the same Module, with Visibility set to Visibility.module (default). - * Composites from Modules in the same Layer, with Visibility set to Visibility.layer - * Composites from Modules in Layers below, with Visibility set to Visibility.application - -Modules contains a lot of the Polygene⢠infrastructure, which are the enforcers of these wise modularization principles. - -It is not possible to modify the Modules, their resolution nor binding in any way after the application starts. - -[[core-api-visibility,Visibility]] -= Visibility = http://git-wip-us.apache.org/repos/asf/polygene-java/blob/14125f65/core/api/src/docs/visibility.txt ---------------------------------------------------------------------- diff --git a/core/api/src/docs/visibility.txt b/core/api/src/docs/visibility.txt new file mode 100644 index 0000000..c0dad46 --- /dev/null +++ b/core/api/src/docs/visibility.txt @@ -0,0 +1,16 @@ +////////////////////// + * Licensed 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. +////////////////////// + +[[core-api-visibility,Visibility]] += Visibility = + http://git-wip-us.apache.org/repos/asf/polygene-java/blob/14125f65/core/runtime/src/main/java/org/apache/polygene/runtime/composite/CompositeMethodModel.java ---------------------------------------------------------------------- diff --git a/core/runtime/src/main/java/org/apache/polygene/runtime/composite/CompositeMethodModel.java b/core/runtime/src/main/java/org/apache/polygene/runtime/composite/CompositeMethodModel.java index d290f97..ec6de3b 100644 --- a/core/runtime/src/main/java/org/apache/polygene/runtime/composite/CompositeMethodModel.java +++ b/core/runtime/src/main/java/org/apache/polygene/runtime/composite/CompositeMethodModel.java @@ -52,7 +52,7 @@ public final class CompositeMethodModel private final ConcernsModel concerns; private final SideEffectsModel sideEffects; private final MixinsModel mixins; - private AnnotatedElement annotations; + private final AnnotatedElement annotations; // Context // private final SynchronizedCompositeMethodInstancePool instancePool = new SynchronizedCompositeMethodInstancePool(); http://git-wip-us.apache.org/repos/asf/polygene-java/blob/14125f65/manual/src/docs/userguide/extensions.txt ---------------------------------------------------------------------- diff --git a/manual/src/docs/userguide/extensions.txt b/manual/src/docs/userguide/extensions.txt index 433bd47..44bfd3f 100644 --- a/manual/src/docs/userguide/extensions.txt +++ b/manual/src/docs/userguide/extensions.txt @@ -61,6 +61,10 @@ include::../../../../extensions/entitystore-memory/src/docs/es-memory.txt[] :leveloffset: 2 +include::../../../../extensions/entitystore-file/src/docs/es-cassandra.txt[] + +:leveloffset: 2 + include::../../../../extensions/entitystore-file/src/docs/es-file.txt[] :leveloffset: 2 http://git-wip-us.apache.org/repos/asf/polygene-java/blob/14125f65/manual/src/docs/userguide/glossary.txt ---------------------------------------------------------------------- diff --git a/manual/src/docs/userguide/glossary.txt b/manual/src/docs/userguide/glossary.txt index ffef798..f2fb326 100644 --- a/manual/src/docs/userguide/glossary.txt +++ b/manual/src/docs/userguide/glossary.txt @@ -321,6 +321,14 @@ This term has no definition yet. Learn how to contribute in <<community-docs>>. -- +[[def-object,Object]]Object:: ++ +-- +Polygene can manage Java classes that are not Composites, and injections can be made on these objects. Read more +in the user guide about <<core-api-object>>. +-- + + [[def-private-mixin,Private Mixin]]Private Mixin:: + --
