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 2015/06/16 07:42:21 UTC
[33/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-UserProfileService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-UserProfileService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-UserProfileService.adoc
new file mode 100644
index 0000000..3850741
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-UserProfileService.adoc
@@ -0,0 +1,44 @@
+[[_rg_services-spi_manpage-UserProfileService]]
+= `UserProfileService`
+:Notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `UserProfileService` provides the ability for the domain application to return supplementary metadata about the current user. This information is used (by the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer]) to customize the appearance of the tertiary "Me" menu bar (top right). For example, rather than display the username, instead the user's first and last name could be displayed.
+
+Another use case is to allow the user to switch context in some fashion or other. This might be to emulate a sort of "sudo"-like function, or perhaps to focus on some particular set of data.
+
+
+
+== SPI
+
+The SPI defined by the service is:
+
+[source,java]
+----
+public interface UserProfileService {
+ @Programmatic
+ String userProfileName(); // <1>
+}
+----
+<1> is used (in the Wicket viewer) as the menu name of the tertiary "Me" menu bar.
+
+If the method returns `null` or throws an exception then the framework will default to using the current user name.
+
+In the future this API may be expanded; one obvious possibility is to return a profile photo or avatar URL.
+
+
+
+== Implementation
+
+The (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] has a simple implementation of this service:
+
+image::{_imagesdir}reference-services-spi/UserProfileService/todoapp.png[width="800px",link="{_imagesdir}reference-services-spi/UserProfileService/todoapp.png"]
+
+
+[NOTE]
+====
+Currently this feature is not integrated with Isis' authentication mechanisms; the information provided is purely metadata provided for presentation purposes only.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-UserRegistrationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-UserRegistrationService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-UserRegistrationService.adoc
new file mode 100644
index 0000000..83aa0ff
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-UserRegistrationService.adoc
@@ -0,0 +1,81 @@
+[[_rg_services-spi_manpage-UserRegistrationService]]
+= `UserRegistrationService`
+:Notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The `UserRegistrationService` provides the ability for users to sign-up to access an application by providing a valid email address, and also provides the capability for users to reset their password if forgotten.
+
+For user sign-up, the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] will check whether an implementation of this service (and also the xref:rg.adoc#_rg_services-spi_manpage-EmailNotificationService[`EmailNotificationService`]) is available, and if so will render a sign-up page where the user enters their email address. A verification email is sent (using the aforementioned `EmailNotificationService`) which includes a link back to the running application; this allows the user then to complete their registration process (choose user name, password and so on). When the user has provided the additional details, the Wicket viewer calls _this_ service in order to create an account for them, and then logs the user on.
+
+For the password reset feature, the Wicket viewer will render a password reset page, and use the `EmailNotificationService` to send a "password forgotten" email. This service provides the ability to reset a password based on the user's email address.
+
+It is of course possible for domain objects to use this service; it will be injected into domain object or other domain services in the usual way. That said, we expect that such use cases will be comparatively rare; the primary use case is for the Wicket viewer's sign-up page.
+
+[NOTE]
+====
+For further details on the user registration feature (as supported by the Wicket viewer), see xref:ug.adoc#_ug_wicket-viewer_features_user-registration[here].
+====
+
+
+
+== SPI
+
+The SPI defined by the service is:
+
+[source,java]
+----
+public interface UserRegistrationService {
+ @Programmatic
+ boolean usernameExists(String username); // <1>
+ @Programmatic
+ boolean emailExists(String emailAddress); // <2>
+ @Programmatic
+ void registerUser(String username, String password, String emailAddress); // <3>
+ @Programmatic
+ boolean updatePasswordByEmail(String emailAddress, String password); // <4>
+}
+----
+<1> checks if there is already a user with the specified username
+<2> checks if there is already a user with the specified email address
+<3> creates the user, with specified password and email address. The username and email address must both be unique (not being used by an existing user)
+<4> allows the user to reset their password
+
+
+
+
+== Implementation
+
+The core Isis framework itself defines only an API; there is no default implementation. Rather, the implementation will depend on the security mechanism being used.
+
+That said, if you have configured your app to use the http://github.com/isisaddons/isis-module-security[Isis addons security module], then note that the security module does provide an abstract implementation (`SecurityModuleAppUserRegistrationServiceAbstract`) of the `UserRegistrationService`. You will need to extend that service and provide implementation for the two abstract methods: `getInitialRole()` and `getAdditionalInitialRoles()`.
+
+This is needed so that the self-registered users are assigned automatically to your application role(s) and be able to use the application. Without any role such user will be able only to see/use the logout link of the application.
+
+
+
+
+== Registering the Services
+
+Assuming that the `configuration-and-annotation` services installer is configured:
+
+[source,ini]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+then (if using the (non-ASF) http://github.com/isisaddons/isis-module-security[Isis addons' security] module) you will need to register your concrete implementation of `SecurityModuleAppUserRegistrationServiceAbstract`.
+
+
+
+
+== Related Services
+
+The most common use case is to allow users to sign-up through Isis' Wicket viewer. Because the process requires email to be sent, the following services must be configured:
+
+* xref:rg.adoc#_rg_services-api_manpage-EmailService[`EmailService`]
+* xref:rg.adoc#_rg_services-spi_manpage-EmailNotificationService[`EmailNotificationService`]
+* `UserRegistrationService` (this service)
+
+The `EmailService` in particular requires additional xref:ug.adoc#_ug_runtime_configuring-core[configuration properties] to specify the external SMTP service.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts.adoc
new file mode 100644
index 0000000..f7b255c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts.adoc
@@ -0,0 +1,22 @@
+[[_ug_core-concepts]]
+= Core Concepts
+:Notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+
+This introductory chapter should give you a good about what Apache Isis actually *is*: the fundamental ideas and principles that it builds upon, how it compares with other frameworks, what the fundamental building blocks are for actually writing an Isis application, and what services and features the framework provides for you to leverage in your own apps.
+
+[TIP]
+====
+Parts of this chapter have been adapted from Dan Haywood's 2009 book, 'Domain Driven Design using Naked Objects'. We've also added some new insights and made sure the material we've used is relevant to Apache Isis.
+====
+
+
+include::_ug_core-concepts_philosophy.adoc[leveloffset=+1]
+include::_ug_core-concepts_principles.adoc[leveloffset=+1]
+include::_ug_core-concepts_building-blocks.adoc[leveloffset=+1]
+include::_ug_core-concepts_framework-provided-services.adoc[leveloffset=+1]
+include::_ug_core-concepts_add-ons.adoc[leveloffset=+1]
+include::_ug_core-concepts_other-deployment-options.adoc[leveloffset=+1]
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_add-ons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_add-ons.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_add-ons.adoc
new file mode 100644
index 0000000..83777e3
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_add-ons.adoc
@@ -0,0 +1,35 @@
+[[_ug_core-concepts_add-ons]]
+= Isis Add-ons
+:Notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The link:http://www.isisaddons.org[Isis Addons] website provides a number of reusable modules and other extensions for Apache Isis. This chapter focuses just on the modules, all of which have a name of the form `isis-module-xxx`.
+
+[WARNING]
+====
+Note that Isis addons, while maintained by Isis committers, are not part of the ASF.
+====
+
+
+
+The modules themselves fall into four broad groups:
+
+* modules that provide an implementations of API defined by Apache Isis +
++
+where Isis has hooks to use the service if defined by provides no implementations of its own. The http://github.com/isisaddons/isis-module-command[command], http://github.com/isisaddons/isis-module-audit[auditing], http://github.com/isisaddons/isis-module-publishing[publishing], http://github.com/isisaddons/isis-module-security[security] and http://github.com/isisaddons/isis-module-sessionlogger[sessionlogger] modules fall into this category. Typically the domain objects themselves wouldn't interact with these services
+
+* modules that provide standalone domain services with their own API and implementation +
++
+These are simply intended to be used by domain objects. The http://github.com/isisaddons/isis-module-docx[docx], http://github.com/isisaddons/isis-module-excel[excel], http://github.com/isisaddons/isis-module-settings[settings] and http://github.com/isisaddons/isis-module-stringinterpolator[stringinterpolator] fall into this category.
+
+* modules that provide standalone domain entities (and supporting services) for a particular subdomain +
++
+The http://github.com/isisaddons/isis-module-tags[tags] module falls into this category
+
+* modules that provide developer utilities +
++
+Not intended for use by either the framework or domain objects, but provide utilities that the developer themselves might use. The http://github.com/isisaddons/isis-module-devutils[devutils] module (not suprisingly) falls into this category
+
+Each of the modules has a full README and example application demonstrating their usage. The sections below briefly outline the capabilities of these modules.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_building-blocks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_building-blocks.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_building-blocks.adoc
new file mode 100644
index 0000000..80e045d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_building-blocks.adoc
@@ -0,0 +1,93 @@
+[[_ug_core-concepts_building-blocks]]
+= Building Blocks
+:Notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+
+IMPORTANT: TODO
+
+## A MetaModel with Explicit and Inferred Semantics
+
+IMPORTANT: TODO
+
+* use of annotations
+** reuse JEE annotations where possible
+* layout hints are overridable, to avoid restarting the app/speed up feedback
+
+
+## Domain Objects and Domain Services
+
+IMPORTANT: TODO
+
+* domain model
+** domain objects
+*** domain entity
+*** view model
+** domain service
+** value type
+
+Anything else can be (should be) ignored by annotating with `@Programmatic`.
+
+
+
+## Properties, Collections and Actions
+
+IMPORTANT: TODO
+
+
+## Domain Entities vs View Models
+
+IMPORTANT: TODO
+
+`@DomainObject(nature=...)`
+
+
+
+## Domain Services
+
+Domain services consist of a set of logically grouped actions, and as such follow the same conventions as for entities. However, a service cannot have (persisted) properties, nor can it have (persisted) collections.
+
+Domain services are instantiated once and once only by the framework, and are used to centralize any domain logic that does not logically belong in a domain entity or value. Isis will automatically inject services into every domain entity that requests them, and into each other.
+
+For convenience you can inherit from AbstractService or one of its subclasses, but this is not mandatory.
+
+
+### Domain Services vs View Services
+
+IMPORTANT: TODO
+
+`@DomainService(nature=...)`
+
+.Factories, Repositories and Services
+****
+A distinction is sometimes made between a factory (that creates object) and a repository (that is used to find existing objects). You will find them discussed separately in Evans' link:http://books.google.com/books/about/Domain_Driven_Design.html?id=hHBf4YxMnWMC[Domain Driven Design], for example.
+
+In Apache Isis these are all implemented as domain services. Indeed, it is quite common to have a domain service that acts as both a factory and a repository.
+****
+
+
+
+
+## Value Objects (Primitives)
+
+IMPORTANT: TODO
+
+
+
+## Contributions
+
+IMPORTANT: TODO
+
+
+
+
+## Event Bus
+
+IMPORTANT: TODO
+
+
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_framework-provided-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_framework-provided-services.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_framework-provided-services.adoc
new file mode 100644
index 0000000..719a234
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_framework-provided-services.adoc
@@ -0,0 +1,54 @@
+[[_ug_core-concepts_framework-provided-services]]
+= Framework-provided Services
+:Notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+
+
+Most framework domain services are API: they exist to provide support functionality to the application's domain objects and services. In this case an implementation of the service will be available, either by Apache Isis itself or by Isis Addons (non ASF).
+
+Some framework domain services are SPI: they exist primarily so that the application can influence the framework's behaviour. In these cases there is (usually) no default implementation; it is up to the application to provide an implementation.
+
+
+General purpose:
+
+* xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer[`DomainObjectContainer`]
+* xref:rg.adoc#_rg_services-api_manpage-ClockService[`ClockService`]
+* xref:rg.adoc#_rg_services-api_manpage-IsisSupportJdo[`IsisSupportJdo`]
+* xref:rg.adoc#_rg_services-api_manpage-WrapperFactory[`WrapperFactory`]
+* xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`]
+* xref:rg.adoc#_rg_services-api_manpage-EmailService[`EmailService`]
+
+Commands/Background/Auditing:
+
+* xref:rg.adoc#_rg_services-api_manpage-CommandContext[`CommandContext`] (SPI)
+* xref:rg.adoc#_rg_services-spi_manpage-CommandService[`CommandService`] (SPI)
+* xref:rg.adoc#_rg_services-spi_manpage-AuditingService[`AuditingService`] (SPI)
+* xref:rg.adoc#_rg_services-api_manpage-BackgroundService[`BackgroundService`]
+* xref:rg.adoc#_rg_services-spi_manpage-BackgroundCommandService[`BackgroundCommandService`] (SPI)
+* xref:rg.adoc#_rg_services-spi_manpage-PublishingService[`PublishingService`] (SPI)
+
+Information Sharing:
+
+* xref:rg.adoc#_rg_services-api_manpage-ScratchPad[`ScratchPad`]
+* xref:rg.adoc#_rg_services-api_manpage-ActionInvocationContext[`ActionInvocationContext`]
+* xref:rg.adoc#_rg_services-api_manpage-QueryResultsCache[`QueryResultsCache`]
+
+
+UserManagement:
+
+* xref:rg.adoc#_rg_services-spi_manpage-UserProfileService[`UserProfileService`] (SPI)
+* xref:rg.adoc#_rg_services-spi_manpage-UserRegistrationService[`UserRegistrationService`] (SPI)
+* xref:rg.adoc#_rg_services-spi_manpage-EmailNotificationService[`EmailNotificationService`] (SPI)
+
+
+Bookmarks and Mementos:
+
+* xref:rg.adoc#_rg_services-api_manpage-BookmarkService[`BookmarkService`]
+* xref:rg.adoc#_rg_services-api_manpage-MementoService[`MementoService`]
+* xref:rg.adoc#_rg_services-api_manpage-DeepLinkService[`DeepLinkService`]
+* xref:rg.adoc#_rg_services-api_manpage-XmlSnapshotService[`XmlSnapshotService`]
+
+
+A full list of services can be found in the xref:rg.adoc#_rg_services-api[Domain Services (API)] and xref:rg.adoc#_rg_services-spi[Domain Services (SPI)] chapters of the reference guide.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_other-deployment-options.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_other-deployment-options.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_other-deployment-options.adoc
new file mode 100644
index 0000000..2b671b5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_other-deployment-options.adoc
@@ -0,0 +1,81 @@
+[[_ug_core-concepts_other-deployment-options]]
+= Other Deployment Options
+:Notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+Apache Isis is a mature platform suitable for production deployment, with its "sweet spot" being line-of-business enterprise applications. So if you're looking to develop that sort of application, we certainly hope you'll seriously evaluate it.
+
+But there are other ways that you can make Isis work for you; in this chapter we explore a few of them.
+
+
+
+== Deploy to production
+
+Let's start though with the default use case for Isis: building line-of-business enterprise applications, on top of its Wicket viewer.
+
+Apache Wicket, and therefore Apache Isis in this configuration, is a stateful architecture. As a platform it is certainly capable of supporting user bases of several thousand (with perhaps one or two hundred concurrent); however it isn't an architecture that you should try to scale up to tens of thousands of concurrent users.
+
+The UI UI generated by the Wicket viewer is well suited to many line-of-business apps, but it's also worth knowing that (with a little knowledge of the Wicket APIs) it relatively straightforward to extend. As described in xref:ug.adoc#_ug_core-concepts_add-ons[Isis addons] chapter, the viewer already has integrations with https://github.com/isisaddons/isis-wicket-gmap3[google maps], https://github.com/isisaddons/isis-wicket-fullcalendar2[a full calendar] and an https://github.com/isisaddons/isis-wicket-excel[export to Excel] component. We are also aware of integrations with SVG images (for floor maps of shopping center) and of custom widgets displaying a catalogue (text and images) of medical diseases.
+
+Deploying on Isis means that the framework also manages object persistence. For many line-of-business applications this will mean using a relational database. It is also possible (courtesy of its integratinon with link:http://www.datanucleus.org[DataNucleus]) to deploy an Isis app to a NoSQL store such as Neo4J or MongoDB; and it is also possible to deploy to cloud platforms such as link:https://cloud.google.com/appengine/docs[Google App Engine (GAE)].
+
+
+
+== Use for prototyping
+
+Even if you don't intend to deploy your application on top of Isis, there can be a lot of value in using Isis for prototyping. Because all you need do to get an app running is write domain objects, you can very quickly explore a domain object model and validate ideas with a domain expert.
+
+By focusing just on the domain, you'll also find that you start to develop a ubiquitous language - a set of terms and concepts that the entire teamEnum (business and technologists alike) have a shared understanding.
+
+Once you've sketched out your domain model, you can then "start-over" using your preferred platform.
+
+
+
+
+
+== Deploy on your own platform
+
+The programming model defined by Isis deliberately minimizes the dependencies on the rest of the framework. In fact, the only hard dependency that the domain model classes have on Isis is through the `org.apache.isis.applib` classes, mostly to pick up annotations such as `@Disabled`.
+So, if you have used Isis for prototyping (discussed above), then note that it's quite feasible to take your domain model a the basis of your actual development effort; Isis' annotations and programming conventions will help ensure that any subtle semantics you might have captured in your prototyping are not lost.
+
+If you go this route, your deployment platform will of course need to provide similar capabilities to Isis. In particular, you'll need to figure out a way to inject domain services into domain entities (eg using a JPA listener), and you'll also need to reimplement any domain services you have used that Isis provides "out-of-the-box" (eg xref:rg.adoc#_rg_services-api_manpage-QueryResultsCache[`QueryResultsCache`] domain service).
+
+
+
+
+
+== Deploy the REST API
+
+REST (Representation State Transfer) is an architectural style for building highly scalable distributed systems, using the same principles as the World Wide Web. Many commercial web APIs (twitter, facebook, Amazon) are implemented as either pure REST APIs or some approximation therein.
+
+The http://restfulobjects.org[Restful Objects specification] defines a means by a domain object model can be exposed as RESTful resources using JSON representations over HTTP. Isis' <<_restfulobjects_viewer, Restful Objects viewer] is an implementation of that spec, making any Isis domain object automatically available via REST.
+
+There are a number of use cases for deploying Isis as a REST API, including:
+
+* to allow a custom UI to be built against the RESTful API +
++
+For example, using AngularJS or some other RIA technology such as Flex, JavaFX, Silverlight
+
+* to enable integration between systems +
++
+REST is designed to be machine-readable, and so is an excellent choice for synchronous data interchange scenarios.
+
+* as a ready-made API for migrating data from one legacy system to its replacement.
+
+
+As for the auto-generated webapps, the framework manages object persistence. It is perfectly possible to deploy the REST API alongside an auto-generated webapp; both work from the same domain object model.
+
+
+
+
+
+== Implement your own viewer
+
+Isis' architecture was always designed to support multiple viewers; and indeed Isis out-of-the-box supports two: the Wicket viewer, and the Restful Objects viewer (or three, if one includes the Wrapper Factory).
+
+While we mustn't understate the effort involved here, it is feasible to implement your own viewers too. Indeed, one of Isis' committers does indeed have a (closed source) viewer, based on http://www.wavemaker.com/[Wavemaker].
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy.adoc
new file mode 100644
index 0000000..b31b507
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy.adoc
@@ -0,0 +1,21 @@
+[[_ug_core-concepts_philosophy]]
+= Philosophy and Architecture
+:Notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+
+This section describes some of the core ideas and architectural patterns upon which Apache Isis builds.
+
+include::_ug_core-concepts_philosophy_domain-driven-design.adoc[leveloffset=+1]
+
+include::_ug_core-concepts_philosophy_naked-objects-pattern.adoc[leveloffset=+1]
+
+include::_ug_core-concepts_philosophy_hexagonal-architecture.adoc[leveloffset=+1]
+
+include::_ug_core-concepts_philosophy_aop.adoc[leveloffset=+1]
+
+// include::_ug_core-concepts_philosophy_dci.adoc[leveloffset=+1]
+
+include::_ug_core-concepts_philosophy_how-eases-ddd.adoc[leveloffset=+1]
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_aop.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_aop.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_aop.adoc
new file mode 100644
index 0000000..7e3b0a2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_aop.adoc
@@ -0,0 +1,36 @@
+[[_ug_core-concepts_philosophy_aop]]
+= Aspect Oriented
+:Notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+
+
+Although not a book about object modelling, Evans' "Domain Driven Design" does use object orientation as its primary modelling tool; and many tend to think of xref:ug.adoc#_ug_core-concepts_philosophy_domain-driven-design,DDD>> as an updated treatise on good object modelling[in the same vein as Rebecca Wirf Brock's link:http://en.wikipedia.org/wiki/Responsibility-driven_design[Responsibility Driven Design], say. Meanwhile the <<_naked_objects_pattern, naked objects pattern] very much comes from an OO background (it even has 'object' in its name); and Richard Pawson lists Alan Kay as a key influence.
+
+It's certainly true that to develop an Apache Isis application you will need to have good object oriented modelling skills. But given that all the mainstream languages for developing business systems are object oriented (Java, C#, Ruby), that's not such a stretch.
+
+However, what you'll also find as you write your applications is that in some ways an Isis application is more aspect-oriented than it is object oriented. Given that aspect-orientation -- as a programming paradigm at least -- hasn't caught on, that statement probably needs unpacking a little.
+
+== AOP Concepts
+
+Aspect-orientation, then, is a different way of decomposing your application, by treating _cross-cutting concerns_ as a first-class citizen. The canonical (also rather boring) example of a cross-cutting concern is that of logging (or tracing) all method calls. An aspect can be written that will weave in some code (a logging statement) at specified points in the code).
+
+This idea sounds rather abstract, but what it really amounts to is the idea of interceptors. When one method calls another the AOP code is called in first. This is actually then one bit of AOP that is quite mainstream; DI containers such as Spring provide aspect orientation in supporting annotations such as `@Transactional` or `@Secured` to java beans.
+
+Another aspect (ahem!) of aspect-oriented programming has found its way into other programming languages, that of a mix-in or trait. In languages such as Scala these mix-ins are specified statically as part of the inheritance hierarchy, whereas with AOP the binding of a trait to some other class/type is done without the class "knowing" that additional behaviour is being mixed-in to it.
+
+== Realization within Isis
+
+What has all this to do with Apache Isis, then?
+
+Well, a different way to think of the naked objects pattern is that the visualization of a domain object within a UI is a cross-cutting concern. By following certain very standard programming conventions that represent the _Apache Isis Programming Model_ (POJOs plus annotations), the framework is able to build a metamodel and from this can render your domain objects in a standard generic fashion. That's a rather more interesting cross-cutting concern than boring old logging!
+
+Isis also draws heavily on the AOP concept of interceptors. Whenever an object is rendered in the UI, it is filtered with respect to the user's permissions. That is, if a user is not authorized to either view or perhaps modify an object, then this is applied transparently by the framework. The http://github.com/isisaddons/isis-module-security[Isis addons' security] module, mentioned previously, provides a rich user/role/permissions subdomain to use out of the box; but you can integrate with a different security mechanism if you have one already.
+
+Another example of interceptors are the http://github.com/isisaddons/isis-module-command[Isis addons' command] and http://github.com/isisaddons/isis-module-audit[Isis addons' audit] modules. The command module captures every user interaction that modifies the state of the system (the "cause" of a change) while the audit module captures every change to every object (the "effect" of a change). Again, this is all transparent to the user.
+
+Apache Isis also has an internal event bus (you can switch between an underlying implementation of Gauva or Axon). A domain event is fired whenever an object is interacted with, and this allows any subscribers to influence the operation (or even veto it). This is a key mechanism in ensuring that Isis applications are maintainable, and we discuss it in depth in the section on xref:ug.adoc#_ug_more-advanced_decoupling[Decoupling]. But fundamentally its relying on this AOP concept of interceptors.
+
+Finally, Isis also a feature that is akin to AOP mix-ins. A "contributed action" is one that is implemented on a domain service but that appears to be a behaviour of rendered domain object. In other words, we can dissociate behaviour from data. That's not always the right thing to do of course. In Richard Pawson's description of the xref:ug.adoc#_ug_core-concepts_philosophy_naked-objects-pattern[naked objects pattern] he talks about "behaviourally rich" objects, in other words where the business functionality encapsulated the data. But on the other hand sometimes the behaviour and data structures change at different rates. The link:http://en.wikipedia.org/wiki/Single_responsibility_principle[single responsibility principle] says we should only lump code together that changes at the same rate. Isis' support for contributions (not only contributed actions, but also contributed properties and contributed collections) enables this. And again, to loop back to the topic of this s
ection, it's an AOP concept that being implemented by the framework.
+
+The nice thing about aspect orientation is that for the most part you can ignore these cross-cutting concerns and - at least initially at least - just focus on implementing your domain object. Later when your app starts to grow and you start to break it out into smaller modules, you can leverage Isis' AOP support for mixins (xref:ug.adoc#_ug_more-advanced_decoupling_contributions[contributions]) and interceptors (the xref:ug.adoc#_ug_more-advanced_decoupling_event-bus[event bus]) to ensure that your codebase remains maintainable.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_dci.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_dci.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_dci.adoc
new file mode 100644
index 0000000..1e4c916
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_dci.adoc
@@ -0,0 +1,9 @@
+[[_ug_core-concepts_philosophy_dci]]
+= DCI
+:Notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+
+
+IMPORTANT: TODO ... Trygve Reenskaug
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_domain-driven-design.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_domain-driven-design.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_domain-driven-design.adoc
new file mode 100644
index 0000000..764df57
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_domain-driven-design.adoc
@@ -0,0 +1,80 @@
+[[_ug_core-concepts_philosophy_domain-driven-design]]
+= Domain-Driven Design
+:Notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+
+This section describes some of the core ideas and architectural patterns upon which Apache Isis builds.
+
+There's no doubt that we developers love the challenge of understanding and deploying complex technologies. But understanding the nuances and subtleties of the business domain itself is just as great a challenge, perhaps more so. If we devoted our efforts to understanding and addressing those subtleties, we could build better, cleaner, and more maintainable software that did a better job for our stakeholders. And there's no doubt that our stakeholders would thank us for it.
+
+A couple of years back Eric Evans wrote his book link:http://www.amazon.co.uk/Domain-driven-Design-Tackling-Complexity-Software/dp/0321125215[Domain-Driven Design], which is well on its way to becoming a seminal work. In fact, most if not all of the ideas in Evans' book have been expressed before, but what he did was pull those ideas together to show how predominantly object-oriented techniques can be used to develop rich, deep, insightful, and ultimately useful business applications.
+
+There are two central ideas at the heart of domain-driven design.
+
+* the *_ubiquitous language_* is about getting the whole team (both domain experts and developers) to communicate more transparently using a domain model.
+
+* Meanwhile, *_model-driven design_* is about capturing that model in a very straightforward manner in code.
+
+Let's look at each in turn.
+
+== Ubiquitous Language
+
+It's no secret that the IT industry is plagued by project failures. Too often systems take longer than intended to implement, and when finally implemented, they don't address the real requirements anyway.
+
+Over the years we in IT have tried various approaches to address this failing. Using waterfall methodologies, we've asked for requirements to be fully and precisely written down before starting on anything else. Or, using agile methodologies, we've realized that requirements are likely to change anyway and have sought to deliver systems incrementally using feedback loops to refine the implementation.
+
+But let's not get distracted talking about methodologies. At the end of the day what really matters is communication between the domain experts (that is, the business) who need the system and the techies actually implementing it. If the two don't have and cannot evolve a shared understanding of what is required, then the chance of delivering a useful system will be next to nothing.
+
+Bridging this gap is traditionally what business analysts are for; they act as interpreters between the domain experts and the developers. However, this still means there are two (or more) languages in use, making it difficult to verify that the system being built is correct. If the analyst mistranslates a requirement, then neither the domain expert nor the application developer will discover this until (at best) the application is first demonstrated or (much worse) an end user sounds the alarm once the application has been deployed into production.
+
+Rather than trying to translate between a business language and a technical language, with _DDD_ we aim to have the business and developers using the same terms for the same concepts in order to create a single *_domain model_*. This domain model identifies the relevant concepts of the domain, how they relate, and ultimately where the responsibilities are. This single domain model provides the vocabulary for the ubiquitous language for our system.
+
+
+.Ubiquitous Language
+****
+Build a common language between the domain experts and developers by using the concepts of the domain model as the primary means of communication. Use the terms in speech, in diagrams, in writing, and when presenting.
+
+If an idea cannot be expressed using this set of concepts, then go back and extend the model. Look for and remove ambiguities and inconsistencies.
+****
+
+
+Creating a ubiquitous language calls upon everyone involved in the system's development to express what they are doing through the vocabulary provided by the model. If this can't be done, then our model is incomplete. Finding the missing words deepens our understanding of the domain being modeled.
+
+This might sound like nothing more than me insisting that the developers shouldn't use jargon when talking to the business. Well, that's true enough, but it's not a one-way street. A *ubiquitous language* demands that the developers work hard to understand the problem domain, but it also demands that the business works hard in being *precise* in its naming and descriptions of those concepts. After all, ultimately the developers will have to express those concepts in a computer programming language.
+
+Also, although here I'm talking about the "domain experts" as being a homogeneous group of people, often they may come from different branches of the business. Even if we weren't building a computer system, there's a lot of value in helping the domain experts standardize their own terminology. Is the marketing department's "prospect" the same as sales' "customer," and is that the same as an after-sales "contract"?
+
+The need for precision within the ubiquitous language also helps us scope the system. Most business processes evolve piecemeal and are often quite ill-defined. If the domain experts have a very good idea of what the business process should be, then that's a good candidate for automation, that is, including it in the scope of the system. But if the domain experts find it hard to agree, then it's probably best to leave it out. After all, human beings are rather more capable of dealing with fuzzy situations than computers.
+
+So, if the development team (business and developers together) continually searches to build their ubiquitous language, then the domain model naturally becomes richer as the nuances of the domain are uncovered. At the same time, the knowledge of the business domain experts also deepens as edge conditions and contradictions that have previously been overlooked are explored.
+
+We use the ubiquitous language to build up a domain model. But what do we do *with* that model? The answer to that is the second of our central ideas.
+
+
+== Model-Driven Design
+
+Of the various methodologies that the IT industry has tried, many advocate the production of separate analysis models and implementation models. One example (from the mid 2000s) was that of the _OMG_'s Model-Driven Architecture ( _MDA_) initiative, with its platform-independent model (the _PIM_) and a platform-specific model (the _PSM_).
+
+Bah and humbug! If we use our ubiquitous language just to build up a high-level analysis model, then we will re-create the communication divide. The domain experts and business analysts will look only to the analysis model, and the developers will look only to the implementation model. Unless the mapping between the two is completely mechanical, inevitably the two will diverge.
+
+What do we mean by *model* anyway? For some, the term will bring to mind _UML_ class or sequence diagrams and the like. But this isn't a model; it's a visual *representation* of some aspect of a model. No, a domain model is a group of related concepts, identifying them, naming them, and defining how they relate. What is in the model depends on what our objective is. We're not looking to simply model everything that's out there in the real world. Instead, we want to take a relevant abstraction or simplification of it and then make it do something useful for us. A model is neither right nor wrong, just more or less useful.
+
+For our ubiquitous language to have value, the domain model that encodes it must have a straightforward, literal representation to the design of the software, specifically to the implementation. Our software's design should be driven by this model; we should have a model-driven design.
+
+
+.Model-Driven Design
+****
+There must be a straightforward and very literal way to represent the domain model in terms of software. The model should balance these two requirements: form the ubiquitous language of the development team and be representable in code.
+
+Changing the code means changing the model; refining the model requires a change to the code.
+****
+
+
+Here also the word *design* might mislead; some might again be thinking of design documents and design diagrams. But by *design* we mean a way of organizing the domain concepts, which in turn leads to the way in which we organize their representation in code.
+
+Luckily, using *_object-oriented_* ( _OO_) languages such as Java, this is relatively easy to do; _OO_ is based on a modeling paradigm anyway. We can express domain concepts using classes and interfaces, and we can express the relationships between those concepts using associations.
+
+So far so good. Or maybe, so far so much motherhood and apple pie. Understanding the _DDD_ concepts isn't the same as being able to apply them, and some of the _DDD_ ideas can be difficult to put into practice. Time to discuss the naked objects pattern and how it eases that path by applying these central ideas of _DDD_ in a very concrete way.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_hexagonal-architecture.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_hexagonal-architecture.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_hexagonal-architecture.adoc
new file mode 100644
index 0000000..7e33166
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_hexagonal-architecture.adoc
@@ -0,0 +1,29 @@
+[[_ug_core-concepts_philosophy_hexagonal-architecture]]
+= Hexagonal Architecture
+:Notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+
+One of the patterns that Evans discusses in his book is that of a *layered architecture*. In it he describes why the domain model lives in its own layer within the architecture. The other layers of the application (usually presentation, application, and persistence) have their own responsibilities, and are completely separate. Each layer is cohesive and depending only on the layers below. In particular, we have a layer dedicated to the domain model. The code in this layer is unencumbered with the (mostly technical) responsibilities of the other layers and so can evolve to tackle complex domains as well as simple ones.
+
+This is a well-established pattern, almost a de-facto; there's very little debate that these responsibilities should be kept separate from each other. With Apache Isis the responsibility for presentation is a framework concern, the responsibility for the domain logic is implemented by the (your) application code.
+
+A few years ago Alistair Cockburn reworked the traditional layered architecture diagram and came up with the *_hexagonal architecture_*:.
+
+[TIP]
+====
+The hexagonal architecture is also known as the link:http://c2.com/cgi/wiki?PortsAndAdaptersArchitecture[Ports and Adapters] architecture or (less frequently) as the link:http://jeffreypalermo.com/blog/the-onion-architecture-part-1/[Onion] architecture.
+====
+
+.The hexagonal architecture emphasizes multiple implementations of the different layers.
+image::{_imagesdir}core-concepts/philosophy/hexagonal-architecture.png[width="700px"]
+
+What Cockburn is emphasizing is that there's usually more than one way *into* an application (what he called the *_user-side' ports_*) and more than one way *out of* an application too (the *_data-side ports_*). This is very similar to the concept of primary and secondary actors in use cases: a primary actor (often a human user but not always) is active and initiates an interaction, while a secondary actor (almost always an external system) is passive and waits to be interacted with.
+
+Associated with each port can be an *_adapter_* (in fact, Cockburn's alternative name for this architecture is *_ports and adapters_*). An adapter is a device (piece of software) that talks in the protocol (or _API_) of the port. Each port could have several adapters.
+
+Apache Isis maps very nicely onto the *hexagonal architecture*. Isis' viewers act as user-side adapters and use the Isis metamodel API as a port into the domain objects. For the data side, we are mostly concerned with persisting domain objects to some sort of object store. Here Apache Isis delegates most of the heavy lifting to ORM implementing the JDO API. Most of the time this will be DataNucleus configured to persist to an RDBMS, but DataNucleus can also support other object stores, for example Neo4J. Alternatively Isis can be configured to persist using some other JDO implementation, for example Google App Engine.
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_how-eases-ddd.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_how-eases-ddd.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_how-eases-ddd.adoc
new file mode 100644
index 0000000..95637bd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_how-eases-ddd.adoc
@@ -0,0 +1,74 @@
+[[_ug_core-concepts_philosophy_how-eases-ddd]]
+= How Apache Isis eases DDD
+:Notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The case for _DDD_ might be compelling, but that doesn't necessarily make it easy to do. Let's take a look at some of the
+challenges that _DDD_ throws up and see how Apache Isis (and its implementation of the naked objects pattern) helps address them.
+
+== DDD takes a conscious effort
+
+Here's what Eric Evans says about ubiquitous language:
+
+pass:[<div class="extended-quote-first"><p>]With a conscious effort by the [development] team the domain model can provide the backbone for [the] common [ubiquitous] language...connecting team communication to the software implementation."
+pass:[</p></div>]
+
+pass:[<div class="extended-quote-attribution"><p>]-- Eric Evans
+pass:[</p></div>]
+
+The word to pick up on here is *conscious*. It takes a conscious effort by the entire team to develop the ubiquitous language. Everyone in the team must challenge the use of new or unfamiliar terms, must clarify concepts when used in a new context, and in general must be on the lookout for sloppy thinking. This takes willingness on the part of all involved, not to mention some practice.
+
+With Apache Isis, though, the ubiquitous language evolves with scarcely any effort at all. For the business experts, the Isis viewers show the domain concepts they identify and the relationships between those concepts in a straightforward fashion. Meanwhile, the developers can devote themselves to encoding those domain concepts directly as domain classes. There's no technology to get distracted by; there is literally nothing else for the developers to work on.
+
+
+== DDD must be grounded
+
+Employing a model-driven design isn't necessarily straightforward, and the development processes used by some organizations positively hinder it. It's not sufficient for the business analysts or architects to come up with some idealized representation of the business domain and then chuck it over the wall for the programmers to do their best with.
+
+Instead, the concepts in the model must have a very literal representation in code. If we fail to do this, then we open up the communication divide, and our ubiquitous language is lost. There is literally no point having a domain model that cannot be represented in code. We cannot invent our ubiquitous language in a vacuum, and the developers must ensure that the model remains grounded in the doable.
+
+In Apache Isis, we have a very pure one-to-one correspondence between the domain concepts and its implementation. Domain concepts are represented as classes and interfaces, easily demonstrated back to the business. If the model is clumsy, then the application will be clumsy too, and so the team can work together to find a better implementable model.
+
+
+
+== Abstract models are difficult to represent
+
+If we are using code as the primary means of expressing the model, then we need to find a way to make this model understandable to the business.
+
+We could generate _UML_ diagrams and the like from code. That will work for some members of the business community, but not for everyone. Or we could generate a _PDF_ document from Javadoc comments, but comments aren't code and so the document may be inaccurate. Anyway, even if we do create such a document, not everyone will read it.
+
+A better way to represent the model is to show it in action as a working prototype. As we show in the xref:ug.adoc#_ug_getting_started[Getting Started] section, Apache Isis enables this with ease. Such prototypes bring the domain model to life, engaging the audience in a way that a piece of paper never can.
+
+Moreover, with Apache Isis prototypes, the domain model will come shining through. If there are mistakes or misunderstandings in the domain model (inevitable when building any complex system), they will be obvious to all.
+
+
+
+
+== Layered architectures are easily compromised
+
+_DDD_ rightly requires that the domain model lives in its own layer within the architecture. The other layers of the application (usually presentation, application, and persistence) have their own responsibilities, and are completely separate.
+
+However, there are two immediate issues. The first is rather obvious: custom coding each of those other layers is an expensive proposition. Picking up on the previous point, this in itself can put the kibosh on using prototyping to represent the model, even if we wanted to do so.
+
+The second issue is more subtle. It takes real skill to ensure the correct separation of concerns between these layers, if indeed you can get an agreement as to what those concerns actually are. Even with the best intentions, it's all too easy for custom-written layers to blur the boundaries and put (for example) validation in the user interface layer when it should belong to the domain layer. At the other extreme, it's quite possible for custom layers to distort or completely subvert the underlying domain model.
+
+Because of Apache Isis' generic __OOUI__s, there's no need to write the other layers of the architecture. Of course, this reduces the development cost. But more than that, there will be no leakage of concerns outside the domain model. All the validation logic *must* be in the domain model because there is nowhere else to put it.
+
+Moreover, although Apache Isis does provide a complete runtime framework, there is no direct coupling of your domain model to the framework. That means it is very possible to take your domain model prototyped in Naked Objects and then deploy it on some other _J(2)EE_ architecture, with a custom _UI_ if you want. Isis guarantees that your domain model is complete.
+
+
+
+
+== Extending the reach of DDD
+
+Domain-driven design is often positioned as being applicable only to complex domains; indeed, the subtitle of Evans book is "Tackling Complexity in the Heart of Software". The corollary is that DDD is overkill for simpler domains. The trouble is that we immediately have to make a choice: is the domain complex enough to warrant a domain-driven approach?
+
+This goes back to the previous point, building and maintaining a layered architecture. It doesn't seem cost effective to go to all the effort of a DDD approach if the underlying domain is simple.
+
+However, with Apache Isis, we don't write these other layers, so we don't have to make a call on how complex our domain is. We can start working solely on our domain, even if we suspect it will be simple. If it is indeed a simple domain, then there's no hardship, but if unexpected subtleties arise, then we're in a good position to handle them.
+
+If you're just starting out writing domain-driven applications, then Apache Isis should significantly ease your journey into applying _DDD_. On the other hand, if you've used _DDD_ for a while, then you should find Isis a very useful new tool in your arsenal.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_naked-objects-pattern.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_naked-objects-pattern.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_naked-objects-pattern.adoc
new file mode 100644
index 0000000..e870754
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_naked-objects-pattern.adoc
@@ -0,0 +1,60 @@
+[[_ug_core-concepts_philosophy_naked-objects-pattern]]
+= Naked Objects Pattern
+:Notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+
+Apache Isis implements the naked objects pattern, originally formulated by Richard Pawson. So who better than Richard to explain the origination of the idea?
+
+pass:[<div class="extended-quote-first"><p>]The Naked Objects pattern arose, at least in part, from my own frustration at the lack of success of the domain-driven approach. Good examples were hard to find--as they are still.
+pass:[</p></div>]
+
+pass:[<div class="extended-quote"><p>]A common complaint from _DDD_ practitioners was that it was hard to gain enough commitment from business stakeholders, or even to engage them at all. My own experience suggested that it was nearly impossible to engage business managers with _UML_ diagrams. It was much easier to engage them in rapid prototyping -- where they could see and interact with the results -- but most forms of rapid prototyping concentrate on the presentation layer, often at the expense of the underlying model and certainly at the expense of abstract thinking.
+pass:[</p></div>]
+
+pass:[<div class="extended-quote"><p>]Even if you could engage the business sponsors sufficiently to design a domain model, by the time you'd finished developing the system on top of the domain model, most of its benefits had disappeared. It's all very well creating an agile domain object model, but if any change to that model also dictates the modification of one or more layers underneath it (dealing with persistence) and multiple layers on top (dealing with presentation), then that agility is practically worthless.
+pass:[</p></div>]
+
+pass:[<div class="extended-quote"><p>]The other concern that gave rise to the birth of Naked Objects was how to make user interfaces of mainstream business systems more "expressive" -- how to make them feel more like using a drawing program or _CAD_ system. Most business systems are not at all expressive; they treat the user merely as a dumb *process-follower*, rather than as an empowered *problem-solver*. Even the so-called usability experts had little to say on the subject: try finding the word "empowerment" or any synonym thereof in the index of any book on usability. Research had demonstrated that the best way to achieve expressiveness was to create an object-oriented user interface (_OOUI_). In practice, though, __OOUI__s were notoriously hard to develop.
+pass:[</p></div>]
+
+pass:[<div class="extended-quote"><p>]Sometime in the late 1990s, it dawned on me that if the domain model really did represent the "ubiquitous language" of the business and those domain objects were behaviorally rich (that is, business logic is encapsulated as methods on the domain objects rather than in procedural scripts on top of them), then the _UI_ could be nothing more than a reflection of the user interface. This would solve both of my concerns. It would make it easier to do domain-driven design, because one could instantly translate evolving domain modeling ideas into a working prototype. And it would deliver an expressive, object-oriented user interface for free. Thus was born the idea of Naked Objects.
+pass:[</p></div>]
+
+pass:[<div class="extended-quote-attribution"><p>]-- Richard Pawson
+pass:[</p></div>]
+
+You can learn much more about the pattern in the book, link:http://www.amazon.com/exec/obidos/ISBN=0470844205/[Naked Objects], also freely available to link:http://www.nakedobjects.org/book/[read online]. Richard co-wrote the book with one of Isis' committers, Robert Matthews, who was in turn the author of the Naked Objects Framework for Java (the original codebase of of Apache Isis).
+
+You might also want to read Richard's link:resources/core-concepts/Pawson-Naked-Objects-thesis.pdf[PhD on the subject].
+
+
+[TIP]
+====
+One of the external examiners for Richard's PhD was link:http://en.wikipedia.org/wiki/Trygve_Reenskaug[Trygve Reenskaug], who originally formulated the MVC pattern at Xeroc PARC. In his paper, link:http://heim.ifi.uio.no/~trygver/2007/2007.02.13-babyUML.pdf[Baby UML], Reenskaug describes that when implemented the first MVC, "the conventional wisdom in the group was that objects should be visible and tangible, thus bridging the gap between the human brain and the abstract data within the computer." Sound familiar? It's interesting to speculate what might have been if this idea had been implemented back then in the late 70s.
+
+Reenskaug then goes on to say that "this simple and powerful idea failed because ... users were used to seeing [objects] from different perspectives. The visible and tangible object would get very complex if it should be able to show itself and be manipulated in many different ways."
+
+In Apache Isis the responsibility of rendering an object is not the object itself, it is the framework. Rather, the object inspects the object and uses that to decide how to render the object. This is also extensible. In the link:http://www.isisaddons.org[Isis Addons] (non-ASF) the http://github.com/isisaddons/isis-wicket-gmap3[Isis addons' gmap3] wicket extension renders any object with latitude/longitude on a map, while http://github.com/isisaddons/isis-wicket-fullcalendar2[Isis addons' fullcalendar2 wicket extension] renders any object with date(s) on a calendar.
+====
+
+
+
+include::_ug_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc[leveloffset=+1]
+
+
+
+
+== What this means in practice
+
+The screencast below shows what all of this means in practice, showing the relationship between a running app and the actual code underneath.
+
+.How Apache Isis builds a webapp from the underlying domain object model…
+video::ludOLyi6VyY[youtube,width="640px",height="472px"]
+
+[NOTE]
+====
+This screencast shows Apache Isis v1.0.0, Jan 2013. The UI has been substantially refined since that release.
+====
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc
new file mode 100644
index 0000000..96b6fac
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc
@@ -0,0 +1,18 @@
+[[_ug_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping]]
+= Object Interface Mapping
+:Notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+
+
+Another -- more technical -- way to think about the naked objects pattern is as an _object interface mapper_, or `OIM`. We sometimes use this idea to explain naked objects to a bunch of developers.
+
+Just as an ORM (such as link:http://datanucleus.org[DataNucleus] or link:http://hibernate.org[Hibernate]) maps domain entities to a database, you can think of the naked objects pattern as representing the concept of mapping domain objects to a user interface.
+
+This is the way that the link:http://metawidget.org/[MetaWidget] team, in particular Richard Kennard, the primary contributor, likes to describe their tool. MetaWidget has a number of ideas in common with Apache Isis, specifically the runtime generation of a UI for domain objects. You can hear more from Kennard and others on this http://devchat.tv/js-jabber/150-jsj-oims[Javascript Jabber podcast].
+
+[NOTE]
+====
+We compare Apache Isis' with MetaWidget xref:ug.adoc#_ug_core-concepts_principles_apache-isis-vs_metawidget[here].
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles.adoc
new file mode 100644
index 0000000..da52685
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles.adoc
@@ -0,0 +1,16 @@
+[[_ug_core-concepts_principles]]
+= Principles and Values
+:Notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+
+
+This section describes some of the core principles and values that the framework aims to honour and support.
+
+The first of these relate to how we believe your domain application should be written: it should be decoupled, testable and so on). Others relate to the implementation of the framework itself.
+
+The section concludes by contrasting the framework with some other open source frameworks commonly used.
+
+include::_ug_core-concepts_principles_your-apps.adoc[leveloffset=+1]
+include::_ug_core-concepts_principles_isis-itself.adoc[leveloffset=+1]
+include::_ug_core-concepts_principles_apache-isis-vs.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs.adoc
new file mode 100644
index 0000000..cb4bcda
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs.adoc
@@ -0,0 +1,36 @@
+[[_ug_core-concepts_principles_apache-isis-vs]]
+= Apache Isis vs ...
+:Notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+
+Many other frameworks promise rapid application development and provide automatically generated user interfaces, so how
+do they compare to Apache Isis?
+
+
+include::_ug_core-concepts_principles_apache-isis-vs_mvc-server-side-frameworks.adoc[leveloffset=+1]
+
+
+
+== vs CQRS
+
+IMPORTANT: TODO
+
+== vs Event Sourcing
+
+IMPORTANT: TODO
+
+
+== vs Angular
+
+IMPORTANT: TODO
+
+
+
+include::_ug_core-concepts_principles_apache-isis-vs_metawidget.adoc[leveloffset=+1]
+
+
+
+== vs OpenXava
+
+IMPORTANT: TODO
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_metawidget.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_metawidget.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_metawidget.adoc
new file mode 100644
index 0000000..30adc9f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_metawidget.adoc
@@ -0,0 +1,16 @@
+[[_ug_core-concepts_principles_apache-isis-vs_metawidget]]
+= vs MetaWidget
+:Notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+
+
+MetaWidget (mentioned xref:ug.adoc#_ug_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping[earlier] has a number of ideas in common with Apache Isis, specifically the runtime generation of a UI for domain objects. And like Apache Isis, MetaWidget builds its own metamodel of the domain objects and uses this to render the object.
+
+However, there is a difference in philosophy in that MW is not a full-stack framework and does not (in their words) try to "own the UI". Rather they support a huge variety of UI technologies and allow the domain object to be rendered in any of them.
+
+In contrast, Apache Isis is full-stack and does generate a complete UI; we then allow you to customize or extend this UI (as per the various link:http://www.isisaddons.org[Isis Addons] (non-ASF), and we also provide a full REST API through the xref:ug.adoc#_ug_restfulobjects-viewer[Restful Objects viewer]
+
+Also, it's worth noting that MetaWidget does have an elegant pipeline architecture, with APIs to allow even its metamodel to be replaced. It would be feasible and probably quite straightforward to use Isis' own metamodel as an implementation of the MetaWidget API. This would allow MetaWidget to be able to render an Isis domain application.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_mvc-server-side-frameworks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_mvc-server-side-frameworks.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_mvc-server-side-frameworks.adoc
new file mode 100644
index 0000000..a873888
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_mvc-server-side-frameworks.adoc
@@ -0,0 +1,19 @@
+[[_ug_core-concepts_principles_apache-isis-vs_mvc-server-side-frameworks]]
+= vs MVC server-side frameworks
+:Notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+Some of most commonly used frameworks today are link:http://www.spring.io/[Spring MVC], link:http://rubyonrails.org/[Ruby on Rails] and link:http://www.grails.org[Grails], all of which implement one flavour or another of the server-side MVC pattern. The MVC 1.0 specification (scheduled for JavaEE 8) is also similar.
+
+These frameworks all use the classic *model-view-controller* ( _MVC_) pattern for web applications, with scaffolding, code-generation, and/or metaprogramming tools for the controllers and views, as well as convention over configuration to define how these components interact. The views provided out of the box by these frameworks tend to be simple _CRUD_-style interfaces. More sophisticated behavior is accomplished by customizing the generated controllers.
+
+The most obvious difference when developing an Apache Isis application is its deliberate lack of an explicit controller layer; non- _CRUD_ behavior is automatically made available in its generic object-oriented _UI_s. More sophisticated UIs can be built either by xref:ug.adoc#_ug_extending_wicket-viewer[extending Isis' Wicket viewer] or by writing a bespoke UI leveraging the REST (hypermedia) API automatically exposed by xref:ug.adoc#_ug_restfulobjects-viewer[Isis' Restful Objects viewer]. Other frameworks can also be used to implement REST APIs, of course, but generally they require a significant amount of development to get anywhere near the level of sophistication provided automatically by Isis' REST API.
+
+Although these frameworks all provide their own ecosystems of extensions, Isis' equivalent link:http://www.isisaddons.org[Isis Addons] (non-ASF) tend to work at a higher-level of abstraction. For example, each of these frameworks will integrate with various security mechanism, but the http://github.com/isisaddons/isis-module-security[Isis addons' security module] provides a full subdomain of users, roles, features and permissions that can be plugged into any Isis application. Similarly, the http://github.com/isisaddons/isis-module-command[Isis addons' command] and http://github.com/isisaddons/isis-module-audit[Isis addons' audit] modules in combination provide a support for auditing and traceability that can also be used for out of the box profiling. Again, these addons can be plugged into any Isis app.
+
+In terms of testing support, each of these other frameworks provide mechanisms to allow the webapp to be tested from within a JUnit test harness. Isis' support is similar. Where Isis differs though is that it enables end-to-end testing without the need for slow and fragile Selenium tests. Instead, Isis provides a "xref:ug.adoc#_ug_testing_integ-test-support_wrapper-factory[WrapperFactory]" domain service that allows the generic UI provided to in essence be simulated. On a more pragmatic level, the http://github.com/isisaddons/isis-module-fakedata[Isis addons' fakedata] module does "what it says on the tin", allowing both unit- and integration-tests to focus on the salient data and fake out the rest.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_isis-itself.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_isis-itself.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_isis-itself.adoc
new file mode 100644
index 0000000..8997d46
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_isis-itself.adoc
@@ -0,0 +1,47 @@
+[[_ug_core-concepts_principles_isis-itself]]
+= Isis itself
+:Notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+
+
+This section discusses some of the principles and values we apply to the development of the Apache Isis framework itself.
+
+== Full-stack but Extensible
+
+IMPORTANT: TODO
+
+
+== Focuses on its USP
+
+IMPORTANT: TODO
+
+
+add-ons
+
+* Isis is at heart a metamodel with runtime, and coordinates interations using an AOP set of principles
+* Apache Isis vs Isis Addons
+* Apache Isis vs Shiro vs DataNucleus
+
+
+
+... all code has legacy in it.... parts of the Isis codebase are well over a decade old; and back then a lot of the JEE technologies that we'd like to be using just didn't exist, so we had to invent the features we required ourselves.
+
+... also, Apache Isis today is more pragmatic than previously
+* a client/server solution, with AWT-based client
+* a HTML browser, Scimpi (JSF-like, but not using JSF), ...
+* security
+* objectstores
+
+We're working hard to remove duplication, reuse existing open source/JEE, and simplify.
+
+
+The areas of Isis we consider mature are those that have been developed in support of real-world applications implemented by the committers. Foremost among these is Estatio.
+
+
+Focus on enterprise / line-of-business applications, for use by internal staff.
+
+* problem solvers, not process followers
+
+* view models
+