polygene-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From nic...@apache.org
Subject [1/4] polygene-java git commit: More documentation
Date Sun, 04 Jun 2017 10:20:28 GMT
Repository: polygene-java
Updated Branches:
  refs/heads/develop e21738bb2 -> 05ddab16a


More documentation

Signed-off-by: niclas <niclas@hedhman.org>


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 <niclas@hedhman.org>
Authored: Sun Jun 4 17:23:52 2017 +0800
Committer: niclas <niclas@hedhman.org>
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::
 +
 --


Mime
View raw message