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 <[email protected]> Authored: Mon Jun 5 08:17:47 2017 +0200 Committer: Paul Merlin <[email protected]> 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
