svn commit: r1427077 - in /isis/site/trunk/content: core/metamodel-finetuning-the-programming-model.md core/metamodel.md documentation.md

[da...@apache.org]

Author: danhaywood
Date: Mon Dec 31 10:53:41 2012
New Revision: 1427077

URL: http://svn.apache.org/viewvc?rev=1427077&view=rev
Log:
isis site - how to fine-tune the programming model

Added:
    isis/site/trunk/content/core/metamodel-finetuning-the-programming-model.md
      - copied, changed from r1426042, isis/site/trunk/content/core/metamodel.md
Removed:
    isis/site/trunk/content/core/metamodel.md
Modified:
    isis/site/trunk/content/documentation.md

Copied: isis/site/trunk/content/core/metamodel-finetuning-the-programming-model.md (from r1426042, isis/site/trunk/content/core/metamodel.md)
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/core/metamodel-finetuning-the-programming-model.md?p2=isis/site/trunk/content/core/metamodel-finetuning-the-programming-model.md&p1=isis/site/trunk/content/core/metamodel.md&r1=1426042&r2=1427077&rev=1427077&view=diff
==============================================================================
--- isis/site/trunk/content/core/metamodel.md (original)
+++ isis/site/trunk/content/core/metamodel-finetuning-the-programming-model.md Mon Dec 31 10:53:41 2012
@@ -1,7 +1,60 @@
-Title: Core MetaModel
+Title: Fine-tuning the Programming Model
 
-{stub
-This page is a stub.
-}
+## Core MetaModel
+
+The core metamodel defines APIs and implementations for building the Isis metamodel: a description of the set of entities, domain services and values that make up the domain model.
+
+The description of each domain class consists of a number of elements:
+
+* [ObjectSpecification]()
+
+  Analogous to `java.lang.Class`; holds information about the class itself and holds collections of each of the three types of class' members (below);
+
+* [OneToOneAssociation]()
+
+  Represents a class member that is a single-valued property of the class.  The property's type is either a reference to another entity, or is a value type.
+
+* [OneToManyAssociation]()
+
+  Represents a class member that is a collection of references to other entities.  Note that Isis does not currently support collections of values.
+
+* [ObjectAction]()
+
+  Represents a class member that is an operation that can be performed on the action.  Returns either a single value, a collection of entities, or is `void`.
+
+The metamodel is built up through the [ProgrammingModel](https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/progmodel/ProgrammingModel.java), which defines an API for registering a set of [FacetFactory]()s.   Two special `FacetFactory` implementations - [PropertyAccessorFacetFactory](https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/progmodel/facets/properties/accessor/PropertyAccessorFacetFactory.java) and [CollectionAccessorFacetFactory](https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/progmodel/facets/collections/accessor/CollectionAccessorFacetFactory.java) - are used to identify the class members.  All the other `FacetFactory`s are responsible for installing [Facet](https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facetapi/Facet.java)s onto the metamodel elements.  There are many 
 many such `Facet`s, and are used to do such things get values from properties or collections, modify properties or collections, invoke action, hide or disable class members, provide UI hints for class members, and so on.  In short, the `FacetFactory`s registered defines the Isis programming conventions.
+
+## Modifying the Programming Model
+
+The default implementation of `ProgrammingModel` is [ProgrammingModelFacetsJava5](https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/progmodels/dflt/ProgrammingModelFacetsJava5.java), which registers a large number of `FacetFactory`s.  
+
+By editing `isis.properties` you can modify the programming conventions either by  (a) using the default programming model, but tweaking it to include new `FacetFactory`s or exclude existing, or (b) by specifying a completely different programming model implementation.
+
+Let's see how this is done.
+
+### Fine-tuning the existing programming model
+
+Suppose that for some reason you wanted to disable support for the `@Aggregated` annotation.  This would be done using:
+
+<pre>
+isis.reflector.facets.exclude=org.apache.isis.core.progmodel.facets.object.aggregated.annotation.AggregatedAnnotationFacetFactory
+</pre>
+
+Or, suppose you wanted to use the example ["namefile"](https://github.com/apache/isis/blob/master/example/misc/metamodel/namefile/src/main/java/org/apache/isis/example/metamodel/namefile/facets/NameFileFacetFactory.java) `FacetFactory` as part of your programming conventions, use:
+
+<pre>
+isis.reflector.facets.include=org.apache.isis.example.metamodel.namefile.facets.NameFileFacetFactory
+</pre>
+
+To include/exclude more than one `FacetFactory`, specify as a comma-separated list.  And if you want to dig into this in more detail, the code that implements this logic is [JavaReflectorInstallerNoDecorators](https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/progmodels/dflt/JavaReflectorInstallerNoDecorators.java).
+
+### Specifying a new programming model
+
+To specify a completely new programming model, you'll first need an  implementation of `ProgrammingModel`.  One option is to subclass from `ProgammingModelFacetsJava5`; in your subclass you could remove any `FacetFactory`s that you wanted to exclude, as well as registering your own implementations.
+
+To tell Isis to use your new programming model, use (something like):
+
+<pre>
+isis.reflector.facets=com.mycompany.myapp.isis.IsisProgrammingModel
+</pre>
 
-This module defines APIs and implementations for building the Isis metamodel.

Modified: isis/site/trunk/content/documentation.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/documentation.md?rev=1427077&r1=1427076&r2=1427077&view=diff
==============================================================================
--- isis/site/trunk/content/documentation.md (original)
+++ isis/site/trunk/content/documentation.md Mon Dec 31 10:53:41 2012
@@ -77,7 +77,7 @@ Title: Documentation
 
 - [Deployment Types](core/deployment-type.html)
 - [Applib](core/applib.html)
-- [Core Metamodel](core/metamodel.html) [stub]
+- [Finetuning the Programming Model](core/metamodel-finetuning-the-programming-model.html) [stub]
 - [Core Runtime](core/runtime.html) [stub]
 - [Webserver](core/webserver.html) [stub]