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.
+
