You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@polygene.apache.org by pa...@apache.org on 2017/06/05 09:54:42 UTC
[3/6] polygene-java git commit: Documentation: tools/model-detail +
some edits in other tools docs
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 <pa...@apache.org>
Authored: Mon Jun 5 08:17:47 2017 +0200
Committer: Paul Merlin <pa...@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