Getting the latest code

It is important that you make changes against the latest version of the development code so that it easier merge. Code that is easier to merge gets incorporated more quickly.

The latest version of the source can be checked out of the Subversion repository using the following command:

$ svn co http://nakedobjects.svn.sourceforge.net/svnroot/nakedobjects/framework/trunk nakedobjects

or, assuming you have already checked it out, then ensure that it up-to-date:

$ cd nakedobjects
$ svn up

Changing the code

Make the changes to your local copy ensuring that you use the same coding style and formatting (see code style for details and for the location of the Eclipse settings to assist you).

Creating the patch

A patch is just a special file that details what files are affected and what the changes are. This way a set of related changes can be grouped together and the size of the file is minimal.

Creating from within Eclipse

Creating a patch from within Eclipse can be done easily, but only if you are have one of the Subversion plug-ins installed and the project is shared (see the Team/Share... option).

From within Eclipse open up the contextual menu (right-click) on the file, package or project that has been changed and select the Team/Create Patch... option. In the dialog (shown below) that comes up specify a descriptive file name and confirm that all the files that are checked are the ones that you want to submit. Press the Finish button to create the patch file.

Creating using Subversion

Subversion’s diff command will do a similar thing, but of course you need to use the command line. (You can also use other Subversion clients, such as Tortoise, but you need to find out which menu items correspond to the diff command). Use the following command with a specific project (as shown here), package or file identified to create the patch and redirect the output to a file. Here we are creating a patch for the whole of the runtime project and placing it in the file fixture-patch.txt.

$ svn diff core/runtime > fixture-patch.txt

NOTE – when using Subversion’s diff command only those files that are under Subversion’s control are included. Specifically new files are not part of that set until they have been added (using svn add). So to submit new files either add them with the appropriate svn command or submit them separately.

An example file

The result of this is a file like this (which has been truncated to save space):

Index: /home/rcm/no-development/workspace_DEV_4.0/nakedobjects/core/runtime/src/main/java/org/nakedobjects/runtime/fixture/ObjectFixtureService.java
===================================================================
--- /home/rcm/no-development/workspace_DEV_4.0/nakedobjects/core/runtime/src/main/java/org/nakedobjects/runtime/fixture/ObjectFixtureService.java	(revision 14471)
+++ /home/rcm/no-development/workspace_DEV_4.0/nakedobjects/core/runtime/src/main/java/org/nakedobjects/runtime/fixture/ObjectFixtureService.java	(working copy)
@@ -2,10 +2,12 @@

 import java.io.BufferedReader;
 import java.io.File;
+import java.io.FileNotFoundException;
 import java.io.FileReader;
 import java.io.FileWriter;
 import java.io.IOException;
 import java.io.PrintWriter;
+import java.io.Reader;
 import java.util.HashMap;
 import java.util.HashSet;
 import java.util.Map;
@@ -28,6 +30,7 @@
 import org.nakedobjects.metamodel.spec.feature.OneToOneAssociation;
 import org.nakedobjects.metamodel.util.CollectionFacetUtils;
 import org.nakedobjects.runtime.context.NakedObjectsContext;
+import org.nakedobjects.runtime.fixturesinstaller.FixtureException;

 public class ObjectFixtureService {
@@ -55,6 +58,9 @@

         public NakedObject get(String data) {
             int pos = data.indexOf('#');
+            if (pos == -1) {
+                throw new FixtureException("read failed - object spec: " + data);
+            }
             String id = data.substring(pos + 1);
             NakedObject object = idMap.get(id);
             if (object == null) {

This was produced using Subversion. The file produced by Eclipse is the same except it has a couple of comments at the top, one of which indicates which project the changes come from.

Submitting the patch

Now simply email the patch to us. The email address is patches@nakedobjects.org. The subject line should start with the text PATCH: so that they are not picked out as Spam. Attach the files to the email and in the body explain what the patch is for and what changes it makes. This will help the developers assess the patches and apply them quickly. Please also ensure your email address is correct so that we can contact you if necessary.

When we receive a patch we will load it up using Eclipse and can immediately see what changes will be made. After checking the changes they will be applied to the code and checked in. If you have requested a response we will then email you to let you know what change has been applied.

If you are using Naked Objects with other development tools, or using it in ways that are not talked about then please write about it, or contact me at rmatthews at nakedobjects dot org  and I’ll create a posting for you.  If you do write something, or mention Naked Objects elsewhere, then please let me know so I can add a link to it. Thanks.

To set up Eclipse so these are available you need to import the template files that are included in the distribution. In both the Ant and Maven based distributions they can be found the following directory:

resources
|-- ide
|   `-- eclipse
|       |-- launch
|       `-- templates
|           |-- jmock2-templates.xml
|           |-- junit4-templates.xml
|           `-- nakedobjects-templates.xml

Open up Eclipse’s preferences dialog (Windows/Preferences) and navigate to Java – Editor - Template. Click the Import button, browse to the templates directory, select the nakedobjects-templates.xml file and press OK. A series of templates will be added prefixed with no such as noa, nol, nop etc. Press OK to commit the changes and you are ready to use them.

For example, to insert a property type nop in the editor window within the class declations and press ctrl-space to bring up the available templates.

Each template has a brief description and the template result is shown in the box next to the list. Selecting the template inserts the code into your file at the cursor replacing the template name that you typed.

It also highlights the parts that you can change. So in this example, when we type Purchase, tab, Date, tab, and date we end up with a complete property declaration for a Date value that will display with the label Date as we can see below.

The other files each provide a couple of templates for building Junit version 4 tests and using JMock.

The available Naked Objects templates are:-

Naked Objects uses the feature of Maven to create new Naked Object
application in a couple of commands. What I am going to describe now is
the same as for other Maven archetype, the only additional task is to
specify where the archetype is to be found. We maintain that catalog on
our website so to build a application from scratch type in the following
(assuming that you have Maven 2.1 or 2.2 installed, see
http://maven.apache.org/download.html).

$ mvn archetype:generate -DarchetypeCatalog=http://nakedobjects.org

You will then be prompted with a list of archetypes (at time of
writing there is only one).

Choose archetype:
1: http://nakedobjects.org -> application-archetype (Naked Objects Application)
Choose a number:  (1):

Enter ‘1′ and press return. Once prompted enter a group ID, an
artifact ID, a version number and a suitable package name. The group and
artifact IDs combine to form a unique name for you project and typically
the group ID is used across all you different projects – a suitable choice
here is your domain name reversed, e.g., com.mycompany. The version and
packages prompts provide suitable defaults and can be left as such unless
you have good reason to change them.

After entering these details you are asked to confirm, so ‘ y’ must
be entered. The following example shows me setting up a test project to
explore an idea. I have used org.test as the group ID so I do not clutter
up my project space, and I can more simply and safely remove all my test
stuff from the Maven repsository by deleting the org/test directory.

Define value for groupId: : org.test
Define value for artifactId: : expenses
Define value for version:  1.0-SNAPSHOT: :
Define value for package:  org.test: :
Confirm properties configuration:
groupId: org.test
artifactId: expenses
version: 1.0-SNAPSHOT
package: org.test
 Y: : y

I now have directory called expenses and that contains the
following:-

expenses/
|-- commandline
|   |-- config
|   |-- ide
|   |-- pom.xml
|   `-- src
|-- dom
|   |-- pom.xml
|   `-- src
|-- fixture
|   |-- pom.xml
|   `-- src
|-- pom.xml
|-- service
|   |-- pom.xml
|   `-- src
`-- webapp
    |-- ide
    |-- pom.xml
    `-- srcconfig

This is our recommended directory structure for projects so that
they separate out the different parts of the application. Its probably too
complex for simple projects, but it is the right thing for larger ones.

With the project created the first thing to do is build it and
confirm it runs.

$ cd expenses
$ mvn package

This compile the source code, runs any tests and packages up the
results in the typical Maven fashion. If you go to the target directory in
the commandline directory you will find a distribution file (ending in
.zip) and a directory of the same name with the contents expanded into it.
If you go into that directory you can run the application, so following on
this example:

$ cd commandline/target/expenses-commandline-1.0-SNAPSHOT-commandline.dir/expenses-commandline-1.0-SNAPSHOT/

you will see the following config

expenses.jar
images
lib
nakedobjects.bat
nakedobjects.sh

Run the application using the script

$ ./nakedobjects.sh

Login with sven/pass and ensure that you have a single class
available to you. That’s all there is to it, all the work is done by
Maven!

$ mvn archetype:generate -DarchetypeCatalog=http://nakedobjects.org/snapshot-catalog.xml

Select the scimpi-archetype-quickstart archetype and after entering a suitable group id and artifact id you are ready to build and run the application.

$ cd mywebapp
$ mvn install
$ mvn jetty:run

Now browse to http://localhost:8080/mywebapp/ (where the last part needs to be the artifact ID that you specified in the first step) to see the opening page. This uses a very simple domain model with only one class so the view is not very interesting yet.

With it running, it’s time to add details to the existing class and add some new ones. And it’s time to look at the documentation (see http://scimpi.org).

With such a dramatic changes there could be a few teething problems so please bear with us as we resolve these and let us know if you come across anything that’s not right. Specifically email webmaster at nakedobjects dot org.

The web sites are http://www.nakedobjects.org and http://www.scimpi.org.

Naked Objects is available, as before, from SourceForge (http://sourceforge.net/projects/nakedobjects/) but now you have a choice about how you use it: with Maven, Ant or just using the jars with your favourite IDE. Maven provides the most flexibility, so that is what I’m going to look at now.  Although with Maven you can get up and running without downloading anything from SourceForge, I strongly recommend that you start off by downloading nakedobjects-4.n.n-for-maven.zip or nakedobjects-4.n.n-for-maven.tar.gz from the download page.  This will ensure that you have access to the documentation, some useful resources like icons and a set of examples that you can browse and run, and later experiment with. Once downloaded extract the contents and you’ll end up with a directory called nakedobjects-4.n.n.

Running an example

Let’s start off by looking at the examples to see what Naked Objects looks like when it runs.

Before we can run anything we need to build it.  Using Maven we can do this in one step. So go to one of the example’s directory, in this case we use the claims one as it the simplest, and use the package goal to compile and package it all.

$ cd nakedobjects-4.0.0/examples/orders
$ mvn package
[INFO] Scanning for projects...
Downloading: http://repo1.maven.org/maven2/org/nakedobjects/release/4.0.0/release-4.0.0.pom
7K downloaded
[INFO] ------------------------------------------------------------------------
[INFO] Building Example Orders DOM
[INFO]    task-segment: [package]
[INFO] ------------------------------------------------------------------------
[INFO] [resources:resources]
[INFO] Using default encoding to copy filtered resources.
Downloading: http://repo1.maven.org/maven2/org/nakedobjects/applib/4.0.0/applib-4.0.0.pom
2K downloaded
Downloading: http://repo1.maven.org/maven2/org/nakedobjects/core/4.0.0/core-4.0.0.pom
5K downloaded
Downloading: http://repo1.maven.org/maven2/org/nakedobjects/nakedobjects-parent/5/nakedobjects-parent-5.pom
14K downloaded
:
:
:
Downloading: http://repo1.maven.org/maven2/org/nakedobjects/plugins/xml-persistor/1.0.0/xml-persistor-1.0.0.jar
53K downloaded
Downloading: http://repo1.maven.org/maven2/org/nakedobjects/plugins/xstream-marshalling/1.0.0/xstream-marshalling-1.0.0.jar
7K downloaded
Downloading: http://repo1.maven.org/maven2/org/nakedobjects/core/remoting/4.0.0/remoting-4.0.0.jar
195K downloaded
[INFO] [compiler:compile]
[INFO] Nothing to compile - all classes are up to date
[INFO] [resources:testResources]
[INFO] Using default encoding to copy filtered resources.
[INFO] [compiler:testCompile]
[INFO] No sources to compile
[INFO] [surefire:test]
[INFO] No tests to run.
[INFO] [jar:jar]
[INFO] [assembly:single {execution: default}]
[INFO] Reading assembly descriptor: src/main/assembly/descriptor.xml
[INFO] Processing DependencySet (output=lib)
[INFO] Building zip: /home/bob/tmp/nakedobjects-4.0.0/examples/orders/target/orders-demo-4.0.0-commandline.zip
[WARNING] Assembly file: /home/bob/tmp/nakedobjects-4.0.0/examples/orders/target/orders-demo-4.0.0-commandline.zip is not a regular file (it may be a directory). It cannot be attached to the project build for installation or deployment.
[INFO] Processing DependencySet (output=lib)
[INFO] Copying files to /home/bob/tmp/nakedobjects-4.0.0/examples/orders/target/orders-demo-4.0.0-commandline.dir
[WARNING] Assembly file: /home/bob/tmp/nakedobjects-4.0.0/examples/orders/target/orders-demo-4.0.0-commandline.dir is not a regular file (it may be a directory). It cannot be attached to the project build for installation or deployment.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 1 minute 21 seconds
[INFO] Finished at: Wed Aug 12 20:13:35 BST 2009
[INFO] Final Memory: 25M/495M
[INFO] ------------------------------------------------------------------------
$

As you can see from the output Maven downloads all the dependencies that the application needs, compiles the code, tests it and then creates a distribution for it. The results can be seen in commandline/target/ where there is both a zip file and exploded version. Before sending the zip files to all you friends lets take a look at it. So go into the exploded version and run the nakedobjects script.

$ cd target/orders-demo-4.0.0-commandline.dir/orders-demo-4.0.0/
$ ./nakedobjects.sh

When started you will be prompted for a user name and password. Enter sven and pass and press the Logon button.

The opening screen shows a set of service objects. Here we have right-clicked on the Products icons to access its actions.

These actions correspond to the two public methods in the ProductRepository class:

    public List<Product> showAll() {
        return allInstances(Product.class);
    }

    public Product findByCode(@Named("Code") final String code) {
        return firstMatch(Product.class, new Filter<Product>() {
            public boolean accept(Product obj) {
                return code.equals(obj.getCode());
            }
        });
    }

What important to remember here, and in all the following screen shots is that the views are created from the code that I am showing you.  There is no code in the application for creating these views, it is Naked Objects building a model of the domain objects and then creating views automatically to show the objects to the user.  This will be further demonstrated later when we use another interface to show the same objects.

After selecting the Show All option, a list of all the products is opened. Double clicking on one of those opens up a view for that specific object.

This time it is the properties (the get/set method pairs) that are used and shown as fields. Notice that the properties are annotated to indicate things like length, and that the code property should only be enabled until the object is persisted.  As well as the properties there is also an object title method that is picked up by convention. This method just returns a String to use as the title, and in this case uses a utility class to build the title from the properties.

    public String title() {
        TitleBuffer t = new TitleBuffer();
        if (getCode() != null){
           t.append(getCode());
           t.append(":", getDescription());
        }
        return t.toString();
    }

    private String code;
    @TypicalLength(9)
    @MaxLength(9)
    @Disabled(When.ONCE_PERSISTED)
    public String getCode() {
        return this.code;
    }
    public void setCode(String code) {
        this.code = code;
    }

    private String description;
    @TypicalLength(50)
    @MaxLength(255)
    public String getDescription() {
        return this.description;
    }
    public void setDescription(String description) {
        this.description = description;
    }

    private Double price;
    public Double getPrice() {
        return this.price;
    }
    public void setPrice(Double price) {
        this.price = price;
    }

The next screen shots shows a view for a particular customer, which differs in layout as it contains a collection. After right-clicking on the customer’s icon the order’s singular public method is shown as an action. There is also a submenu that provides the options available from the Orders service object, in this case these is just the one and that accept a Customer objects as it one parameter.

After clicking on this option, a dialog is brought up to allow the methods parameters to be entered.  The method being

   public void placeOrder(
            Product p,
            @Named("Quantity") Integer quantity ) {
        Order order = (Order)getContainer().newTransientInstance(Order.class);
        order.modifyCustomer(this);
        order.modifyProduct(p);
        order.setOrderDate(new Date(Clock.getTime()));
        order.setQuantity(quantity);
        addToOrders(order);
        modifyLastOrder(order);
        getContainer().persist(order);
    }

As you can see from the method’s code this will create a new Order object and sets up its properties using a combination of the entered values, the current Customer object and some other programmatically derived values. When the OK button is pressed the dialog will be closed, this method will be called and then any changed views updated. In this case the Customer object was changed by having the new item added to its order list. The next screen shot show this after the user has clicked on the new item in the tree view on the left-hand side, which results in the new object being show on the right-hand side.

Now for another viewer. Shut down the application by right-clicking on the background and selecting Quit. Next run the script again but with a parameter to indicate that the HTML viewer is to be used

$ ./nakedobjects.sh --viewer html

Now open up a web browser and open the URL http://localhost:8080/logon.app and log in as before with sven and pass

The opening page shows the same three service object, this time across the top of the page.  In this next screen shot I have clicked the Products link and get presented with the options from the product repository.

This time I click the Show All link instead of double-clicking the icons. This shows a list of the products, each of which is hyperlinked.  I have not click on them yet as the HTML viewer only shows one object at a time.

Clicking on one of the items in the list open it up and adds the list to the history bar (titled “6 Objects”).

Using the Find Customer option on the Customers service object I then searched for a specific customer that resulted in the following screen.

As for the earlier web page this one does not show us the contained objects, but provides us with a link to the list of orders. The options in this viewer are shown on the left hand side as links instead of as a popup menu.  But as in Drag and Drop user interface all the available actions are shown. Again, clicking on the right link, this time the Place Order… one, we open up a dialog that prompts us for the parameters of the underlying method.

After changing the fields if needed we press on the Ok button and the action method is run creating a new order and adding it to the customer’s order list as we saw before.

That concludes my first blog about the new version of Naked Objects.  I suggest that you try a few of things out on the Order project, adding new properties and public methods and see how the user interfaces change.  In the next part I’ll show you how create a new application from scratch using a Maven archetype.

The reflector has been practically rewritten to create a more fine grained meta-model of the domain objects that Naked Objects is working with, allowing you to redefine part, or all, of the programming model. This also provides consistency in accessing and manipulating the domain objects both within the framework and in its extensions. The programming model itself has essentially remained the same bar a few minor tweaks and some subtle improvements, so an existing version 3.0 applications should run with minimal work (although, as the package names have been rationalised throughout, the imports will need updating).  One significant change is the automatic calling of objectChanged and resolve in the setter and getter methods so that these calls are no longer necessary within your application code. Other minor changes include the correcting of method names such as makePersistent to persist and saved/saving to persisted/persisting.

Part of the move toward greater extensibility is a more componentised structure to the framework, where specific component can be installed at runtime providing different user interfaces, persistence mechanisms and so on.  Other projects have now been started that provide new components, such as a JPA based persistor and an RCP viewer.

Other interesting additions and changes include:

• HTTP remoting
• More views – grid, calendar, histogram – and better feedback in the DND viewer with  stylable windows, buttons etc
• Runnable in the Naked Objects container, a Web container, or standalone via Jetty
• New Value type allowing you to define new value such as URL,  email address, temperature, geocode
• An email service and objects
• Perspectives have been replaced with user profiles, which are more comprehensive and are stored separately from the domain objects
• Headless viewer for applying business logic between POJOs
• Ability to embed headless Naked Objects in other systems
• Junit4 runner for testing Naked Objects applications (utilizing the Headless viewer)

All this hard work is now available as a beta release, while the core release will be made in about a months time, with a target date of the 27th July. Other components will be available as well and will follow their own release schedules.

This latest version is available in two different ways.  As before a tarball/zip file can be downloaded from the downloads page on SourceForge and includes the core framework, documentation, examples and a range of plugins including those available from elsewhere. We have also started making the artifacts available using Maven. For this the simplest way to get started is to use the archetypes that we have created to build some template applications. To use this you will need to specify our archetype catalogue as follows:

$ mvn archetype:generate -DarchetypeCatalog=http://nakedobjects.org

Scimpi is a web development framework that builds on the Naked Objects framework (please see my previous blog). This is being updated in line with the development of the underlying framework and a new release will be available around the same time.

Finally I should mention Dan Haywood’s upcoming book “Domain-Driven Design Using Naked Objects”. You can obtain it from the Pragmatic Programmers web site. This talks about how install and use Naked Objects and in a way that follows the style of Domain Driven development. The writing of this book has been instrumental to the further development of Naked Objects and my thanks go to Dan for his hard work in the redesigning and development of this release.And finally, thanks to all of you for your ongoing interest and support.

Robert Matthews

PS thanks to the anonymous commenter for prompting this update.

To make web application development simple there should only be one file per page, and each page should only detail what is absolutely necessary, keeping them short yet readable. For example, if I want to show an object then I should not need to work through each field laying out labels and content; simple markup that says ’show object x’ should be all that is needed. Hence Scimpi was designed to process HTML pages with additional markup that dynamically generates HTML snippets to include with the static markup. Each dynamic tag interacts with the Naked Objects framework and generates suitable markup to allow tasks like displaying and editing objects, running actions, building tables etc., to quickly build up dynamic web pages. There are controllers within the system and others can be added, but these are specialised devices, rather than a mandatory part of process. Also, as there are no new controllers to be written and the only interactions are defined within the the HMTL markup, there is no need for any configuration files, which just link together those disparate parts. This may seem at odds with the contemporary web application development process, but in reality all you are doing in defining Scimpi pages is detailing how your users will interact with the system, and this is no different than directing a user in exactly how to the use the generic user interface to complete a task.

In creating this framework we specifically chose not to use JSP as the mechanism to create the pages as these allow, and potentially encourage, code to be included. Scimpi pages need no code, they rely solely on the behaviour provided within the domain model. The pages are therefore simply HTML pages with additional markup.Just to show how simple the process is here are a couple of example pages.

File 1: example1.shtml

<html>
  <head>
    <link rel="stylesheet" type="text/css" href="style/screen.css"/>
  </head>
  <body>
    <swf:run-action object="service:claims" method="allClaims"/>
    <swf:table/>
  </body>
</html>

Screen shot 1: a table generated from the results of the allClaims methodFile 2: example2.shtml

<html>
  <head>
    <link rel="stylesheet" type="text/css" href="style/screen.css"/>
  </head>
  <body>
    <swf:run-action object="service:claims" method="findClaims">
      <swf:parameter number="1" value="city"/>
    </swf:run-action>
    <swf:short-form/>
  </body>
</html>

Screen shot 2: a form generated from an findClaims action with an included parameterFile 3: example3.shtml

<html>
  <head>
    <link rel="stylesheet" type="text/css" href="style/screen.css"/>
  </head>
  <body>
    <swf:action-form object="service:claims" method="findClaims"/>
  </body>
</html>

Screen shot 3: an entry form for running the same findClaims action, where the parameter is now prompted forI now have to start looking at other things, but the first release is going to be made available on SourceForge shortly.

For the moment the documentation and framework can be downloaded from the Scimpi website. (See http://scimpi.org/downloads/index.shtml for both addresses.)

Richard