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`