svn commit: r1424855 - in /isis/site/trunk/content: contributors/recreating-an-archetype.md learning-more/articles.md learning-more/articles/ learning-more/articles/about.md learning-more/articles/understanding-isis-infoq-2010.md

[da...@apache.org]

Author: danhaywood
Date: Fri Dec 21 10:40:03 2012
New Revision: 1424855

URL: http://svn.apache.org/viewvc?rev=1424855&view=rev
Log:
isis site - articles; recreating an archetype

Added:
    isis/site/trunk/content/learning-more/articles/
    isis/site/trunk/content/learning-more/articles/about.md
    isis/site/trunk/content/learning-more/articles/understanding-isis-infoq-2010.md
Modified:
    isis/site/trunk/content/contributors/recreating-an-archetype.md
    isis/site/trunk/content/learning-more/articles.md

Modified: isis/site/trunk/content/contributors/recreating-an-archetype.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/contributors/recreating-an-archetype.md?rev=1424855&r1=1424854&r2=1424855&view=diff
==============================================================================
--- isis/site/trunk/content/contributors/recreating-an-archetype.md (original)
+++ isis/site/trunk/content/contributors/recreating-an-archetype.md Fri Dec 21 10:40:03 2012
@@ -21,7 +21,12 @@ Finally, double check that the app is ru
 
 Before we generate the archetype, we clear out all non source code artifacts.
 
-To view the files/directories that needs removing, use:
+Start by doing the regular `mvn clean`:
+<pre>
+mvn clean
+</pre>
+
+To view the remaining files/directories that needs removing, use:
 <pre>
 for a in .project .classpath .settings bin target-ide; do find . -name $a -print; done
 find . -name "*.log" -print
@@ -36,10 +41,11 @@ find . -name "*.log" -exec rm {} \;
 Now we can create the archetype:
 
 <pre>
-mvn clean archetype:create-from-project
-groovy ../../../scripts/updateGeneratedArchetypeSources.groovy
+mvn archetype:create-from-project
+groovy ../../../scripts/updateGeneratedArchetypeSources.groovy -v 1.2.3
 </pre>
 
+where `1.2.3` is the version of isis core that is to be the parent of the generated archetype.
 
 ### Test the archetype
 
@@ -112,7 +118,7 @@ If this a new archetype, then add a refe
 
 Finally, commit the changes:
 <pre>
-git commit -m "ISIS-nnn: updating archetype"
+git commit -am "ISIS-nnn: updating archetype"
 </pre>
 
 ### Setting up Eclipse IDE

Modified: isis/site/trunk/content/learning-more/articles.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/learning-more/articles.md?rev=1424855&r1=1424854&r2=1424855&view=diff
==============================================================================
--- isis/site/trunk/content/learning-more/articles.md (original)
+++ isis/site/trunk/content/learning-more/articles.md Fri Dec 21 10:40:03 2012
@@ -1,9 +1,5 @@
 Title: Articles
 
-{stub
-This page is a stub.
-}
+Some articles relating to either Apache Isis or its predecessor, the Naked Objects framework:
 
-Isis graduated from the Apache incubator in October 2012; we are currently setting ourselves up as a top-level project.
-
-In the meantime you can access our original incubator website [here](http://incubator.apache.org/isis "Apache Isis (incubator website)").
+* [Understanding Apache Isis (InfoQ 2010)](articles/understanding-isis-infoq-2010.html)
\ No newline at end of file

Added: isis/site/trunk/content/learning-more/articles/about.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/learning-more/articles/about.md?rev=1424855&view=auto
==============================================================================
--- isis/site/trunk/content/learning-more/articles/about.md (added)
+++ isis/site/trunk/content/learning-more/articles/about.md Fri Dec 21 10:40:03 2012
@@ -0,0 +1,3 @@
+Title: Articles
+
+* [Understanding Apache Isis (InfoQ 2010)](understanding-isis-infoq-2010.html)

Added: isis/site/trunk/content/learning-more/articles/understanding-isis-infoq-2010.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/learning-more/articles/understanding-isis-infoq-2010.md?rev=1424855&view=auto
==============================================================================
--- isis/site/trunk/content/learning-more/articles/understanding-isis-infoq-2010.md (added)
+++ isis/site/trunk/content/learning-more/articles/understanding-isis-infoq-2010.md Fri Dec 21 10:40:03 2012
@@ -0,0 +1,116 @@
+Title: Understanding Apache Isis (InfoQ Interview 2010)
+
+*The headline feature that distinguishes Apache Isis from other frameworks is its support for the naked objects pattern - the ability to generate a user interface (at runtime) directly from the domain model. However, there's much more to Apache Isis than this.*
+
+*This chapter introduces the Apache Isis and the naked objects pattern by way of a series of questions and answers. It is adapted from an interview originally published on InfoQ in 2010*
+
+###Apache Isis implements the naked objects pattern... but what is that, exactly?
+
+Naked objects is an architectural pattern where the idea is to automatically expose a domain model objects directly within a object-oriented user interface... not just their state (properties and collections) but also their behaviour (what we call actions). You can think of it as analogous to an ORM such as Hibernate; but whereas an ORM reflects the domain model into the persistence layer, naked objects reflects the domain model into the presentation layer.
+
+Naked Objects (capitals) was a Java framework that implemented the naked objects (lower case) pattern. Since then, we've taken the original framework, along with a number of sister projects developed by the community, into the Apache Incubator. So, what was originally "Naked Objects" is now Apache Isis.
+
+###What type of applications are best suited to Isis?
+
+The naked objects pattern requires that your primary consideration is in building an object-oriented domain model, so it's most suitable for enterprise applications that have complex business rules where there's a desire to represented them within such a domain model. The idea - at least during the initial stages - is to build up a domain model quickly, and to get feedback from the domain experts by exploiting the framework's ability to expose that directly domain model within the user interface. A picture tells a thousand words.
+
+Apache Isis "sweet spot" are those applications that are used internally within the organization, by experienced users who are comfortable with the entities within the domain model, and just need an application that imposes as few constraints as possible on how it is used. These are sometimes called sovereign applications. If you're a developer then your IDE is probably the sovereign application you use the most, and how often did you use any of its wizards? And if you use telephone banking then you'll also know how frustrating a sovereign application can be that is too invasive in dictating the workflow... that poor person on the other end asks making apologies while she goes exits from one screen and then goes into another to check some detail on a bank account. The generic OO UIs generated by naked objects impose no such restrictions, and so are ideal for this sort of application.
+
+###And are there applications where the OO UIs generated by Isis are less suitable?
+
+The opposite of a sovereign application (above) is sometimes called a transient application. These are ones used only occasionally or by inexperienced users, typically outside the organization (ie your customers), who don't know or care to know the domain model, and just want to be led through the system to accomplish some well-defined goal. A good example here is a check-in kiosk at an airport... you just want to get on the plane, and be given the opportunity to choose your seat. But you likely won't care which plane, or even plane type, nor who the pilot is; these are unimportant details.
+
+For this sort of application a generic OO UI that exposes lots of the domain is clearly not appropriate. Instead, we want an application that exposes view models rather than entities, and where the UI can be customized. The view model object is responsible for managing the workflow for the user story, exposing just the subset of the domain that is relevant, and hiding the rest of the domain. We find that these view models can be layered on top of the entities once those entities are understood.
+
+Using view model objects is necessary but probably not sufficient for transient applications; we also usually need to customize the UI. Apache Isis has two viewers that allow the UI to be customized, one that provides a set of taglibs, and one that provides a set of Apache Wicket components.
+
+Putting both of these techniques together (custom view models and views) means that Apache Isis is suitable for transient applications as well as sovereign applications. However, the former will necessarily take more work as opposed to the latter.
+
+###What is the typical development process life cycle for applications built with Isis, and how does it compare to traditional application development process?
+
+The main difference you're likely to encounter is the emphasis on developing the domain model at the same time as identifying and prioritizing user stories, what those practicing domain driven design call a "ubiquitous language" for the team.
+
+So, rather than let the developers in the team "discover" the domain model as part of story implementation, we'd expect that the domain experts/business analysts have already identified some of the main domain concepts through prototyping or spikes, and these can be used to help communicate the stories to the developers during the planning game. Not every business analyst is going to feel comfortable working with an IDE, but it works well to pair with a developer. Because an Apache Isis application can be runs just from domain classes, it's possible to develop the app very very quickly. We've found a good technique is to run workshops with the business analyst facilitating the meeting with the domain experts, and the developer acting as "code monkey" to rapidly convert the ideas into an app. Obviously the code isn't production quality, but it allows the team as a whole to go very quickly and experiment with different representations of the model.
+
+Another alternative is to go a little more slowly, and have the analyst and developer pairing to write production code. The analyst still focuses on identifying and naming the domain concepts and their relationships, while the developer's role (as well as learning about the domain) is to ensure that there's enough rigour and tests around the code that's been written while this is being done. Of course, both approaches to pairing can be used, sometimes spiking ideas, sometimes going straight to writing tested code.
+
+Of course, while the naked objects pattern means that no UI code needs to be written in order to elicit feedback, there do still need to be objects in the app for the domain expert to view. Apache Isis has a pluggable runtime/persistence layer, and for prototyping and most of development we recommend using the in-memory object store. To populate this object store for each run we use fixtures, which we usually arrange into a composite pattern to setup data needed for the particular scenario we might be working on. Using Isis in this way means that we spend our time alternating between defining domain classes and writing fixture data. This can be a great benefit because it helps the domain experts - who after all aren't necessarily technical - distinguish between what are classes and what are instances of classes. For example, if I'm writing a library system and we identify there are loanable books and reference books, we need to know whether "loanable book" and "reference boo
 k" are different subclasses of a book superclass, or merely different instances of a book class with, say, a loanable property set to true or false. Seeing a running application makes it much easier for the domain expert to make the call.
+
+In terms of writing tests, there are several options. First, because the domain objects you write are basically pojos that follow some naming conventions, they are very easy to test using standard TDD tools such as JUnit and JMock. And if you wanted to, you could test the UI generated by Isis using Selenium and similar; indeed we'd recommend that if you've customized the UI.
+
+In addition, though, Isis provides a couple of additional BDD/testing framework integrations. One of these is an integration with FitNesse, and a newer one we've worked on is an integration with Concordion. In both cases the integrations provide the glue code so you can exercise your domain objects directly. For example, your spec might say "the place order action cannot be invoked if the product is out of stock". All the developer needs to do is to wire the spec to these pre-canned integrations, specifying that the placeOrder() action should be called on a Product.
+
+Isis also provides a JUnit runner that works by bootstrapping the Isis runtime for each test, and proxying the domain objects with a bit of cglib so that they are interacted with "as if" through the UI. For example, let's go back to that placeOrder() action. To prevent this from being called for a Product that's out of stock, the developer would write a corresponding validatePlaceOrder() method. Isis automatically calls this validate method prior to the placeOrder() method, and uses the return value ("that product is out of stock") as the reason why the action can't be invoked. In the UI, this business rule is represented by greying out the OK button of the action. In the JUnit runner, this rule is represented by having the cglib proxy throw a validation exception if the test calls placeOrder() with an out of stock Product.
+
+In terms of deployment, there's several steps involved, probably the most significant being to select the runtime and object store. As noted above, Isis has a pluggable persistence layer; you can use the in-memory object store for developing, but will want to switch to a "real" object store for deployment. The amount of work required here depends on the object store selected; in the case of JPA/Hibernate support, for example, it amounts to annotating your domain entities with annotations, and writing implementations of some of the repositories to make the relevant SQL calls.
+
+###What are the limitations of Apache Isis framework?
+
+It's certainly true that naked objects pattern implemented by Apache Isis is opinionated, so if you don't agree with all of its opinions then you're going to find it limiting in one way or another.
+
+The first of these is that everything that the user wants to interact with has to be an object of some sort. As already explained, for sovereign applications, these are likely to be the persisted domain entities, but for a transient application, the object may be a view model to be support a particular workflow, and which may or may not be persisted. Such an approach probably wouldn't be considered much of a limitation, but it's worth contrasting with architectures (eg Spring Web Flow or Struts) where put the responsibility for tracking workflow lives not in an object but instead within some sort of declarative XML markup (or even just in the interplay between controllers and views).
+
+A slightly more subtle consequence of the above is that integration of different technologies happens through the domain objects, rather than in front of them through application-layer or UI layer mashups. For example, supposing that we wanted to have an SMS sent out to confirm a checkout. If you were writing the UI and application service layer yourself, you might choose to have the application layer make the call to the SMS service, judging it to be a coordination responsibility. With Isis, though, you don't get the chance to write any application layer code, and so this would be done by having the domain object call out to the SMS service. The SMS service would be defined by an interface, and the implementation would be injected into the domain object by the framework. For some reason not everyone is necessarily comfortable about injecting domain services into entities; but it works well for us and we're sticking with it.
+
+Another area where Isis is going to feel different - and perhaps limiting to some - is that it pushes some responsibilities onto the domain objects that otherwise might sit in other layers. For example, above we discussed that a placeOrder() action on a Customer can have a supporting validatePlaceOrder() method. It's also possible to have disablePlaceOrder() method, which if returning non-null will cause the action to be greyed out the action in the UI. For example, a blacklisted Customer might not allow any orders to be placed, and would indicate this through the disable method. Some might consider this as a misplaced presentation concern. However, the Customer isn't greying out the UI itself; the disable method is merely a convention by which the presentation layer can interrogate the entity.
+
+Something else we hear sometimes about naked objects-style systems is that they are really only suitable for CRUD style applications. It has to be said that it's a criticism that does irk; because although its true that naked objects frameworks automatically expose object state, they also expose object's behaviour. That is, every public method that is not a property or a collection is taken to be an action and will rendered by the UI as a button or a link. Indeed, we sometimes like to talk of behaviourally complete domain objects; it's the very antithesis of the anaemic domain model anti-pattern.
+
+All the above notwithstanding, probably the biggest impediment to going out and using Isis right now is that it's a small community and as such the codebase is still relatively new. But if that is a turn-off, note that you can still use Apache Isis to prototype your domain model, because they are just pojos after all. Indeed, embedding Isis' metamodel for a deployment hosted on some other framework is the objective of the embedded runtime component of Isis
+
+How extensive is the application security support provided by Isis?
+
+Apache Isis exposes a pluggable authentication API and an authorization API, with default implementations of both.
+
+The job of the authentication API is to authenticate the user credentials and return the user Id and a set of roles for that user. This information is then used in one of two ways. The authorization API uses it to implement declarative class-based security, that is, associating access to features based on the roles of the user. In addition, though, a domain object instance can also access the user credentials, and so can implement imperative instance-based checks if required.
+
+For example, we might say that only a user with HR role can award pay rises to an Employee. This is a class-based check and would be implemented through the authorization API. But, we might also say that a user is allowed to view (though not modify) their own salary of their Employee object, but no-one else's. This would be an instance-based check, and would be implemented in the object itself.
+
+In terms of how naked objects restricts access, this is done either by making an object member (property, collection or action) invisible, or, if it is visible, then making it unusable (greyed out).
+
+How does an Isis applications manage the custom logic in terms of business rules, workflow and other business logic that developers have to manually implement outside the generated code?
+
+"Business rules" is one of those amorphous terms that means different things to different people. A consequence is that the team can struggle to nail down exactly where such rules should reside, so that these rules can start to leach out of the domain layer and the application layer, or even worse, the presentation layer. As noted already, one of the principles of naked objects is that domain objects are behaviourally complete. What that means is that business rules and "other business logic" are the responsibility of domain objects. For workflow, again as noted earlier, we suggest that you introduce a view model object and have that manage the user's interaction.
+
+However, saying that business rules are an object's responsibility doesn't necessarily mean that the implementation has to be in Java. We already said that domain objects can delegate work out to domain services that are injected into them. So if you want to put your business rules into a rules engine, that's fine. Wrap the interface to the rules engine within a domain service, and have the domain object call out to the domain service in order to fulfil its responsibility.
+
+In practical terms, you're going to see business rules both in the small-scale and the large. Small-scale business rules tend to be implemented in terms of the supporting methods (disable, validate and so on) that encode the preconditions for interactions. These ensure that the object or the providing arguments is are valid and will veto the interaction otherwise (blacklisted customers, out-of-stock products). The larger-scale business rules are represented as actions on an object that can perform arbitrary business logic, such as modifying its own state, or related objects, and/or delegating out to domain services.
+
+###How does Isis support SOA-based applications, eg where an enterprise service component is consumed by several different applications and other clients?
+
+We can actually answer this both in terms of an Isis application consuming SOA[1] services, and in it providing services.
+
+For consuming SOA services, the answer is easy enough: wrap the SOA service in a domain service interface, and then register the implementation with the framework so that the service is injected into each domain object. That interaction can be either synchronous or asynchronous; there's nothing to prevent the domain object publishing an event to be picked up by some other component out there on your enterprise service bus.
+
+As to providing SOA services, Isis' JSON viewer exposes the domain objects as a set of RESTful resources. We map objects and object members to the standard HTTP verbs, eg so that a GET on an object returns an object representation, a PUT on an object's property will modify the state, or a POST on an object's actions will invoke the action. As its name suggests, the JSON viewer produces a JSON representation, making it easy to consume (eg in HTML5 or RIA applications).
+
+###Most enterprise applications need to reuse the domain and service layer classes between several different applications. How does Apache Isis address this?
+
+One way to think of reuse in terms of strategic domain-driven design, which couches the discussion in terms of identifying bounded contexts and understanding the relationship between these contexts - context maps.
+
+You can think of a bounded context as both the user population that understands a particular ubiquitous language as well as the actual system that they use. For example, the term "Customer" is going to mean one thing to the marketing department, but a potentially different thing to those in shipping. Those two user populations therefore have incompatible languages, and so any integration of systems that support both sets of users will need to explicitly map their meanings of those terms.
+
+Simplifying somewhat, an Isis (naked objects) application can be thought of in three parts: the domain model objects themselves, the viewer that provides a channel to interact with the domain model, and the domain services that are used by the domain model objects. The domain model objects encode a ubiquitous language for a particular bounded context, so it only makes sense to reuse them by users who have the same understanding of that language. We can if we want use view model objects to provide projections of the domain entities to different subsets of that user population, but all must agree with what a Customer is, even if they use different parts of said Customer.
+
+Viewers are channels by which the domain model is accessed. Apache Isis has viewers that expose the domain model as either a desktop app or as a webapp, and also has a RESTful viewer (producing JSON) which allow the view model objects/domain objects to be surfaced as RESTful resources. In DDD terms the RESTful viewers are examples of an "open host service" context mapping from some client bounded context up to our model's context.
+
+With respect to domain services, these are not reusable per se, rather they allow the domain objects to be the client of some other service within the enterprise. That said, one common type of domain service is to provide an interface to an enterprise service bus, in which case the domain objects can publish events onto that bus. In DDD terms this would be an example of a "published language" context mapping; the downstream systems consuming the events of the publishing domain objects.
+
+Naked objects also allows a somewhat finer-grained level of reuse; indeed its support for "don't repeat yourself" is one of the reasons that some people are attracted to the pattern. For example, if we declare a property or an action parameter to be a date, then the viewers will automatically provide a date chooser widget for that property or parameter unless indicated otherwise. Or, if a property's type is an enum, then we'll get a drop-down box. It's the conventions of the naked objects programming model - establishing a protocol of interaction between the presentation layer and the domain model - that enable this sort of reuse.
+
+Some of Isis' more recent viewers also allow mashups within the UI. For example, the viewer that we've implemented using Apache Wicket uses the chain of responsibility pattern to build the UI. If we have an entity can provide its Location (eg, it implements Locatable), then a GoogleMapsWidget will render the entity in a map. Or, if an entity has a date, then a CalendarWidget might render the entity on a calendar. This stuff is extensible so you're free to write your own components and reuse (or indeed invent your own) domain semantics as you see fit.
+
+###What is the future road map of the project?
+
+*This answer is now out of date; Isis entered the incubator in Sept 2010, and graduated as a top-level project in Oct 2012.*
+
+Our proposal to join the incubator is online, and that captured the thoughts we had at that point in time [1]. A general theme is in the ongoing development of the various viewers, such as the Wicket viewer, improving JSON support within the RESTful viewers, and ongoing development of the taglib-based viewer, Scimpi. Contributors who have expressed interest in developing similar viewers using JSF/Facelets, Tapestry, on Android and in JavaFX/Visage.
+
+Isis has a pluggable architecture with about five major APIs (and numerous more fine-grained APIs) that can be developed. Probably the most significant of these is the runtime/persistence API. One piece of work is to develop an ORM-based object store from Hibernate (which is not compatible with Apache's) to a compatible JPA implementation, We've also had a suggestion [2] to re-implement using JDO 3.0/DataNucleus, which would allow us to cover a lot of persistence technologies in one fell swoop
+
+Another objective during incubation is to make Isis more easily bootstrappable and embeddable, and for that JSR-299 (Contexts and Dependency Injection) looks promising. For example, it should be easy to take just the Isis metamodel component and use it within your own applications, eg to drive the rendering of domain objects within custom UI code.
+
+One other area we might see work is in support for other JVM languages. Isis already supports Groovy as well as Java, and the way that Isis builds up its metamodel means that supporting other languages (Scala, Fantom, Go) ought to be pretty straightforward.
+
+Ultimately, though, Apache Isis' roadmap depends on where its community wants to take it; so any of the above might change as we progress through to graduation.
+