polygene-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From paulmer...@apache.org
Subject [3/6] polygene-java git commit: Documentation: tools/model-detail + some edits in other tools docs
Date Mon, 05 Jun 2017 09:54:42 GMT
Documentation: tools/model-detail + some edits in other tools docs


Project: http://git-wip-us.apache.org/repos/asf/polygene-java/repo
Commit: http://git-wip-us.apache.org/repos/asf/polygene-java/commit/b3d5854c
Tree: http://git-wip-us.apache.org/repos/asf/polygene-java/tree/b3d5854c
Diff: http://git-wip-us.apache.org/repos/asf/polygene-java/diff/b3d5854c

Branch: refs/heads/develop
Commit: b3d5854c044db8e9572a80447db71ebc21d44da5
Parents: 43876cd
Author: Paul Merlin <paulmerlin@apache.org>
Authored: Mon Jun 5 08:17:47 2017 +0200
Committer: Paul Merlin <paulmerlin@apache.org>
Committed: Mon Jun 5 08:17:47 2017 +0200

----------------------------------------------------------------------
 manual/src/docs/userguide/tools.txt             |  12 +-
 tools/envisage/src/docs/envisage.txt            |  10 +-
 .../src/docs/yeoman_polygene.txt                |  25 +++-
 tools/model-detail/src/docs/model-detail.txt    |  52 ++++++++
 .../tools/model/DocumentationSupport.java       | 118 +++++++++++++++++
 .../src/test/resources/doc-support-report.json  | 129 +++++++++++++++++++
 6 files changed, 330 insertions(+), 16 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/polygene-java/blob/b3d5854c/manual/src/docs/userguide/tools.txt
----------------------------------------------------------------------
diff --git a/manual/src/docs/userguide/tools.txt b/manual/src/docs/userguide/tools.txt
index 840115e..bd129c9 100644
--- a/manual/src/docs/userguide/tools.txt
+++ b/manual/src/docs/userguide/tools.txt
@@ -24,11 +24,9 @@
 
 == Overview ==
 
-The Polygene™ SDK comes with useful development tools. Theses tools can come in
-handy when assembled into your <<def-application>> in development
-<<def-application-mode, Mode>>.
-
-The tools are available in the +tools/+ directory of the Polygene™ SDK.
+The Polygene™ SDK comes with useful development tools:
+ a `yeoman` project generator,
+ a detailed application model and its visualization gui.
 
 :leveloffset: 2
 
@@ -39,3 +37,7 @@ include::../../../../tools/generator-polygene/src/docs/yeoman_polygene.txt[]
 include::../../../../tools/envisage/src/docs/envisage.txt[]
 
 :leveloffset: 2
+
+include::../../../../tools/model-detail/src/docs/model-detail.txt[]
+
+:leveloffset: 2

http://git-wip-us.apache.org/repos/asf/polygene-java/blob/b3d5854c/tools/envisage/src/docs/envisage.txt
----------------------------------------------------------------------
diff --git a/tools/envisage/src/docs/envisage.txt b/tools/envisage/src/docs/envisage.txt
index 9202133..dc411f2 100644
--- a/tools/envisage/src/docs/envisage.txt
+++ b/tools/envisage/src/docs/envisage.txt
@@ -23,6 +23,10 @@
 Envisage is a Swing based visualization tool for the Polygene™ Application model.
 Visualizations can be printed to PDFs.
 
+include::../../build/docs/buildinfo/artifact.txt[]
+
+It can be handy to run Envisage in development <<def-application-mode, Mode>>
while working on assemblies.
+
 == Usage ==
 
 Envisage can be easily used directly and prior your Application activation:
@@ -48,9 +52,3 @@ image:tools-envisage-stacked-collapsed.png[width="800px"]
 image:tools-envisage-stacked.png[width="800px"]
 
 image:tools-envisage-type.png[width="800px"]
-
-== Embed into your Application ==
-
-include::../../build/docs/buildinfo/artifact.txt[]
-
-It can be handy to run Envisage in development <<def-application-mode, Mode>>
while working on assemblies.

http://git-wip-us.apache.org/repos/asf/polygene-java/blob/b3d5854c/tools/generator-polygene/src/docs/yeoman_polygene.txt
----------------------------------------------------------------------
diff --git a/tools/generator-polygene/src/docs/yeoman_polygene.txt b/tools/generator-polygene/src/docs/yeoman_polygene.txt
index 19cca52..388aea2 100644
--- a/tools/generator-polygene/src/docs/yeoman_polygene.txt
+++ b/tools/generator-polygene/src/docs/yeoman_polygene.txt
@@ -19,14 +19,29 @@
 
 [[tools-shell,Command Line Shell]]
 = Polygene Generator =
-Apache Polygene comes with a Yeoman code generator, to quickly set up a
-project for Polygene applications.
+Apache Polygene comes with a http://yeoman.io/[Yeoman] code generator, to
+quickly set up a project for Polygene applications.
+
+== Usage ==
+
+You will need `node` installed in your machine. In case you don't have it
+(you can check this typing `node --version` in your terminal) please visit
+this https://nodejs.org/en/download/[link].
+
+Then run the following command to install Yeoman and the Polygene generator:
+
+[source,shell]
+----
+$ npm install -g yo generator-polygene
+----
+
+Then run the following commands to get started:
 
 [source,shell]
 ----
-mkdir projectdirname
-cd projectdirname
-yo polygene
+$ mkdir projectdirname
+$ cd projectdirname
+$ yo polygene
 ----
 
 It will ask a lot of questions. For choice questions, you operate up and down, and with multi-choice,
you

http://git-wip-us.apache.org/repos/asf/polygene-java/blob/b3d5854c/tools/model-detail/src/docs/model-detail.txt
----------------------------------------------------------------------
diff --git a/tools/model-detail/src/docs/model-detail.txt b/tools/model-detail/src/docs/model-detail.txt
new file mode 100644
index 0000000..333016c
--- /dev/null
+++ b/tools/model-detail/src/docs/model-detail.txt
@@ -0,0 +1,52 @@
+///////////////////////////////////////////////////////////////
+ * 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.
+///////////////////////////////////////////////////////////////
+
+[[tools-model-detail,Detailed Application Model]]
+= Detailed Application Model =
+
+For troubleshooting it can be handy to log the application model, or write it to some file,
when activating an application.
+
+This library is what <<tools-envisage>> uses under the hood.
+
+include::../../build/docs/buildinfo/artifact.txt[]
+
+== Usage ==
+
+On application bootstrap:
+
+[snippet,java]
+----
+source=tools/model-detail/src/test/java/org/apache/polygene/tools/model/DocumentationSupport.java
+tag=usage
+----
+
+    . Given an application assembler,
+    . and a Polygene runtime,
+    . create the `ApplicationModel`.
+    . Use the `createApplicationDetailDescriptor()` static method to create a detailed application
model object.
+    . Use its `toJson()` method to get a detailed report of the application model.
+    . Continue with regular application activation.
+
+Here is what a sample JSON dump looks like:
+
+[snippet,javascript]
+----
+source=tools/model-detail/src/test/resources/doc-support-report.json
+tag=report
+----

http://git-wip-us.apache.org/repos/asf/polygene-java/blob/b3d5854c/tools/model-detail/src/test/java/org/apache/polygene/tools/model/DocumentationSupport.java
----------------------------------------------------------------------
diff --git a/tools/model-detail/src/test/java/org/apache/polygene/tools/model/DocumentationSupport.java
b/tools/model-detail/src/test/java/org/apache/polygene/tools/model/DocumentationSupport.java
new file mode 100644
index 0000000..cb6bba9
--- /dev/null
+++ b/tools/model-detail/src/test/java/org/apache/polygene/tools/model/DocumentationSupport.java
@@ -0,0 +1,118 @@
+/*
+ *  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.
+ *
+ *
+ */
+package org.apache.polygene.tools.model;
+
+import java.io.BufferedReader;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.InputStreamReader;
+import java.io.StringReader;
+import java.io.StringWriter;
+import javax.json.Json;
+import javax.json.JsonObject;
+import javax.json.stream.JsonGenerator;
+import org.apache.polygene.api.activation.ActivationException;
+import org.apache.polygene.api.activation.PassivationException;
+import org.apache.polygene.api.common.Visibility;
+import org.apache.polygene.api.structure.Application;
+import org.apache.polygene.api.structure.ApplicationDescriptor;
+import org.apache.polygene.bootstrap.ApplicationAssembler;
+import org.apache.polygene.bootstrap.ApplicationAssembly;
+import org.apache.polygene.bootstrap.Energy4Java;
+import org.apache.polygene.bootstrap.LayerAssembly;
+import org.apache.polygene.bootstrap.ModuleAssembly;
+import org.apache.polygene.tools.model.descriptor.ApplicationDetailDescriptor;
+import org.junit.Test;
+
+import static java.util.Collections.singletonMap;
+import static java.util.stream.Collectors.joining;
+import static org.apache.polygene.tools.model.descriptor.ApplicationDetailDescriptorBuilder.createApplicationDetailDescriptor;
+import static org.hamcrest.Matchers.equalTo;
+import static org.junit.Assert.assertThat;
+
+public class DocumentationSupport
+{
+    interface HttpService {}
+
+    interface MyDomain {}
+
+    @Test
+    public void usage() throws ActivationException, PassivationException, IOException
+    {
+        // START SNIPPET: usage
+        ApplicationAssembler assembler = // (1)
+            // END SNIPPET: usage
+            applicationFactory -> {
+                ApplicationAssembly assembly = applicationFactory.newApplicationAssembly();
+                assembly.setName( "my-app" );
+                assembly.setMode( Application.Mode.staging );
+
+                LayerAssembly network = assembly.layer( "network" );
+                ModuleAssembly http = network.module( "http" );
+                http.services( HttpService.class ).instantiateOnStartup();
+
+                LayerAssembly application = assembly.layer( "application" );
+                ModuleAssembly domain = application.module( "domain" );
+                domain.transients( MyDomain.class ).visibleIn( Visibility.application );
+
+                network.uses( application );
+
+                return assembly;
+            };
+        // START SNIPPET: usage
+        Energy4Java polygene = new Energy4Java(); // (2)
+        ApplicationDescriptor model = polygene.newApplicationModel( assembler ); // (3)
+        ApplicationDetailDescriptor detailedModel = createApplicationDetailDescriptor( model
); // (4)
+
+        System.out.println( detailedModel.toJson().toString() ); // (5)
+
+        Application application = model.newInstance( polygene.spi() ); // (6)
+        try
+        {
+            application.activate();
+            // END SNIPPET: usage
+            ClassLoader loader = getClass().getClassLoader();
+            try( InputStream input = loader.getResourceAsStream( "doc-support-report.json"
) )
+            {
+                String text = new BufferedReader( new InputStreamReader( input ) )
+                    .lines()
+                    .filter( line -> !line.startsWith( "//" ) )
+                    .collect( joining( "\n" ) );
+                JsonObject reference = Json.createReader( new StringReader( text ) ).readObject();
+
+                JsonObject detailedModelReport = detailedModel.toJson();
+
+                StringWriter writer = new StringWriter();
+                Json.createWriterFactory( singletonMap( JsonGenerator.PRETTY_PRINTING, true
) )
+                    .createWriter( writer )
+                    .write( detailedModelReport );
+                System.out.println( "--------\n" + writer.toString() );
+
+                assertThat( reference, equalTo( detailedModelReport ) );
+            }
+            // START SNIPPET: usage
+        }
+        finally
+        {
+            application.passivate();
+        }
+        // END SNIPPET: usage
+    }
+}

http://git-wip-us.apache.org/repos/asf/polygene-java/blob/b3d5854c/tools/model-detail/src/test/resources/doc-support-report.json
----------------------------------------------------------------------
diff --git a/tools/model-detail/src/test/resources/doc-support-report.json b/tools/model-detail/src/test/resources/doc-support-report.json
new file mode 100644
index 0000000..a804f83
--- /dev/null
+++ b/tools/model-detail/src/test/resources/doc-support-report.json
@@ -0,0 +1,129 @@
+// START SNIPPET: report
+{
+  "name":"my-app",
+  "version":"1.0",
+  "mode":"staging",
+  "layers":[
+    {
+      "name":"network",
+      "modules":[
+        {
+          "name":"http",
+          "services":[
+            {
+              "type":"org.apache.polygene.tools.model.DocumentationSupport$HttpService",
+              "visibility":"module",
+              "types":[
+                "org.apache.polygene.tools.model.DocumentationSupport$HttpService",
+                "org.apache.polygene.api.service.ServiceComposite"
+              ],
+              "mixins":[
+                {
+                  "mixin":"org.apache.polygene.api.identity.HasIdentity$HasIdentityMixin",
+                  "constructors":[
+                    {
+                      "name":"org.apache.polygene.api.identity.HasIdentity_HasIdentityMixin_Stub"
+                    }
+                  ],
+                  "injection":{
+
+                  }
+                }
+              ]
+            },
+            {
+              "type":"org.apache.polygene.api.unitofwork.UnitOfWorkFactory",
+              "visibility":"module",
+              "types":[
+                "org.apache.polygene.api.unitofwork.UnitOfWorkFactory",
+                "org.apache.polygene.api.service.ServiceComposite"
+              ],
+              "mixins":[
+                {
+                  "mixin":"org.apache.polygene.runtime.unitofwork.UnitOfWorkFactoryMixin",
+                  "constructors":[
+                    {
+                      "name":"org.apache.polygene.runtime.unitofwork.UnitOfWorkFactoryMixin_Stub"
+                    }
+                  ],
+                  "injection":{
+
+                  }
+                },
+                {
+                  "mixin":"org.apache.polygene.api.identity.HasIdentity$HasIdentityMixin",
+                  "constructors":[
+                    {
+                      "name":"org.apache.polygene.api.identity.HasIdentity_HasIdentityMixin_Stub"
+                    }
+                  ],
+                  "injection":{
+
+                  }
+                }
+              ]
+            }
+          ],
+          "activators":[
+          ]
+        }
+      ],
+      "usedLayers":[
+        "application"
+      ],
+      "activators":[
+      ]
+    },
+    {
+      "name":"application",
+      "modules":[
+        {
+          "name":"domain",
+          "services":[
+            {
+              "type":"org.apache.polygene.api.unitofwork.UnitOfWorkFactory",
+              "visibility":"module",
+              "types":[
+                "org.apache.polygene.api.unitofwork.UnitOfWorkFactory",
+                "org.apache.polygene.api.service.ServiceComposite"
+              ],
+              "mixins":[
+                {
+                  "mixin":"org.apache.polygene.runtime.unitofwork.UnitOfWorkFactoryMixin",
+                  "constructors":[
+                    {
+                      "name":"org.apache.polygene.runtime.unitofwork.UnitOfWorkFactoryMixin_Stub"
+                    }
+                  ],
+                  "injection":{
+
+                  }
+                },
+                {
+                  "mixin":"org.apache.polygene.api.identity.HasIdentity$HasIdentityMixin",
+                  "constructors":[
+                    {
+                      "name":"org.apache.polygene.api.identity.HasIdentity_HasIdentityMixin_Stub"
+                    }
+                  ],
+                  "injection":{
+
+                  }
+                }
+              ]
+            }
+          ],
+          "activators":[
+          ]
+        }
+      ],
+      "usedLayers":[
+      ],
+      "activators":[
+      ]
+    }
+  ],
+  "activators":[
+  ]
+}
+// END SNIPPET: report


Mime
View raw message