You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2018/09/18 06:06:57 UTC

[isis] 02/02: ISIS-1899: updates ad.adoc

This is an automated email from the ASF dual-hosted git repository.

danhaywood pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/isis.git

commit 37d11c07a51174cd0150836ce141f36f1a36acd0
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Tue Sep 18 07:06:39 2018 +0100

    ISIS-1899: updates ad.adoc
---
 .../src/main/asciidoc/guides/ad/ad.adoc            | 150 ++++++++++++++-------
 1 file changed, 103 insertions(+), 47 deletions(-)

diff --git a/adocs/documentation/src/main/asciidoc/guides/ad/ad.adoc b/adocs/documentation/src/main/asciidoc/guides/ad/ad.adoc
index ad3dd07..16e305a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ad/ad.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ad/ad.adoc
@@ -68,72 +68,76 @@ All of these have the same Maven `groupId`, namely `org.apache.isis.core`.
 | `isis-core-applib`
 | Core application library.
 
-| `isis-core-commons`
-| Commons library
-
-
 | `isis-core-integtestsupport`
-|
+| Integration test support.
+Application integration tests typically extend from adapter superclasses defined in this module.
 
 | `isis-core-log4j`
-|
-
-| `isis-maven-plugin`
-|
+| Configures Log4j as the logging framework
 
 | `isis-core-metamodel`
-|
+| The classes that make up the metamodel which is used to render the UI.
+
+See the xref:ad.adoc#__ad_metamodel[section below] which also includes a simplified UML diagram of these classes.
 
 | `isis-core-runtime`
-|
+| The classes that make up runtime management and persistence of domain objects, as well as framework for security (concepts of authentication or authorisation).
+
 
 | `isis-core-schema`
-|
+| Defines XSDs and generated classes that capture commands and interactions in XML form.
 
 | `isis-core-security`
-|
+| Defines a "bypass" implementation of security, for prototyping only.
+
+Using this implementation, any user/password is accepted and
 
 | `isis-core-security-shiro`
-|
+| Defines an implementation of security authentication which delegates to Apache Shiro.
 
 | `isis-core-specsupport`
-|
+| Application BDD specs typically inherit from classes defined in this module.
 
 | `isis-core-unittestsupport`
-|
-
-| `isis-core-unittestsupport-test`
-|
+| Application unit tests may use some of the utilities defined in this module.
 
 | `isis-core-viewer-restfulobjects-applib`
-|
+| Defines a client-side Java library for interacting with the REST API exposed by the Restful Objects viewer.
 
 | `isis-core-viewer-restfulobjects-rendering`
-|
+| Provides a `RepresentationService` API and a lower-level `ContentNegotiationService` API, along with implementations of each.
+
+These implementations provide support for the representations defined by Restful Objects spec v1.0, as well as a number of other Apache Isis-specific representations.
 
 | `isis-core-viewer-restfulobjects-server`
-|
+| Defines the JAX-RS resources supported by the Restful Objects viewer.
+
+These parse the input, delegate to the runtime for a response, and hand control to the rendering module to generate a representation.
 
 | `isis-core-viewer-wicket-applib`
-|
+| Currently just defines `WicketDeveloperUtilitiesService`, for clearing the cache.
 
 | `isis-core-viewer-wicket-impl`
-|
+| The top-level integration with Wicket, for example defining the Apache Isis-specific implementations/subclasses of the Wicket APIs for application, web session, localizer and request cycle.
+
+Also defines registries of pages and components, as well as a number of domain services and mixins (for use by applications) that are only available within the Wicket viewer.
 
 | `isis-core-viewer-wicket-model`
-|
+| Serializable mementos representing the state of runtime domain objects (or their individual members).
 
 | `isis-core-viewer-wicket-ui`
-|
+| UI components that render the moduls.
+
+//| `isis-webdocker`
+//| Creates a Docker image for Tomcat that also contains the Apache Isis libraries, thereby enabling "skinny war" support.
 
-| `isis-webdocker`
-|
+// commented out because only added in 1.16.3-SNAPSHOT
 
 | `isis-core-webserver`
-|
+| For development within an IDE, provides a utility class to bootstrap the application (using Jetty).
 
 | `isis-core-wrapper`
-|
+| Provides an implementation of the `WrapperFactory` domain service.
 
 
 |===
@@ -168,10 +172,39 @@ All of these have the same Maven `groupId`, namely `org.apache.isis.mavendeps`.
 | Defunct.
 
 | `isis-mavendeps-testing`
-|
+| Aggregates dependencies on various test-scope plugins useful for unit- and integration testing a module.
+These include Apache Isis' own `unittestsupport`, `integtestsupport` and `specsupport` modules, as well as a number of common testing/mocking/assertion libraries.
+
+These can then be included using a single dependency declaration:
+
+[source,xml]
+----
+<dependencies>
+  <dependency>
+    <groupId>org.apache.isis.mavendeps</groupId>
+    <artifactId>isis-mavendeps-testing</artifactId>
+    <type>pom</type>
+    <scope>test</scope>
+  </dependency>
+</dependencies>
+----
+
 
 | `isis-mavendeps-webapp`
-|
+| Aggregates dependencies on Apache Isis runtime itself when used within a webapp.
+
+These can then be included using a single dependency declaration:
+
+[source,xml]
+----
+<dependencies>
+  <dependency>
+    <groupId>org.apache.isis.mavendeps</groupId>
+    <artifactId>isis-mavendeps-webapp</artifactId>
+    <type>pom</type>
+  </dependency>
+</dependencies>
+----
 
 |===
 
@@ -197,7 +230,8 @@ Its Maven `groupId` is `org.apache.isis.tools`.
 | Description
 
 | `isis-maven-plugin`
-|
+| Code to build a maven plugin for the build.
+This plugin can validate the metamodel and generate Swagger specs for a domain model as part of the application's build pipeline.
 
 
 |===
@@ -226,25 +260,33 @@ Its Maven `groupId` is `org.apache.isis.tools`.
 | Description
 
 | `helloworld`
-|
+| An example application as a single Maven module, including domain classes themselves plus code to bootstrap Apache Isis.
+
+This is reverse engineered into the "helloworld" archetype.
 
 | `simpleapp`
-|
+| The top-level aggregator module for the "simpleapp" example application.
+
+This is an extended version of helloworld, providing more structure (separating out domain model into modules) as well as unit tests, integration tests, BDD specs and fixtures.
+
+The simpleapp modules in aggregate are reverse engineered into the "simpleapp" archetype.
 
 | `simpleapp-application`
-|
+| Defines the contents of the "simpleapp" application using Apache Isis-defined classes, as well as globally scoped domain services and the home page.
 
 | `simpleapp-module-simple`
-|
+| Contains the domain model for a single module.
+
+The intention is to allow this module structure to be copied so that the developer can easily create further modules as their app increases in size.
 
 | `simpleapp-webapp`
-|
+| Bootstraps Apache Isis as a webapp.
 
 | `helloworld-archetype`
-|
+| Helloworld archetype, reverse engineered from the "helloworld" application (above).
 
 | `simpleapp-archetype`
-|
+| Simpleapp archetype, reverse engineered from the "simpleapp" application (above).
 
 |===
 
@@ -253,8 +295,7 @@ Its Maven `groupId` is `org.apache.isis.tools`.
 [[__ad_metamodel]]
 == Metamodel
 
-The metamodel...
-
+The diagram below shows a simplified version of Apache Isis' internal metamodel.
 
 
 [plantuml,_images/metamodel,png]
@@ -344,15 +385,30 @@ Object\nActionParameter ^-down- OneToOne\nActionParameter
 Object\nActionParameter ^-down- OneToMany\nActionParameter
 Object\nAction -left-> "*" Object\nActionParameter
 
-FacetHolder ^-.right- Object\nSpecification
-FacetHolder ^-.right- Object\nMember
-FacetHolder ^-.- Object\nActionParameter
-FacetHolder -left-> "*" Facet
+FacetHolder ^-.left- Object\nSpecification
+FacetHolder ^-.down- Object\nMember
+FacetHolder ^-.down- Object\nActionParameter
+FacetHolder -right-> "*" Facet
 
 
 Object\nAdapter  -up-> Oid
 
-Oid -left-> Object\nSpecId
+Oid -right-> Object\nSpecId
 
 --
 
+where in the `metamodel` package:
+
+`ObjectSpecification`:: is equivalent to `java.lang.Class`
+`ObjectSpecId`:: is a value object equivalent to the `@DomainObject#objectType` or `@DomainService#objectType` attribute
+`OneToOneAssociation`:: represents a scalar property
+`OneToManyAssociation`:: represents a collection
+`ObjectAction`:: represents an action (with multiple parameters, either scalar or list)
+
+and in the `runtime` package:
+
+`Oid`:: is equivalent to the applib `Bookmark`
++
+and appears in URLs in the Wicket and Restful Objects viewers
+
+`ObjectAdapter`:: is equivalent to `java.lang.Object`