Getting the Source and Setting up Eclipse

Scimpi development requires:-

Check out the code from the Source Forge repository us the following command

$ svn co https://scimpi.svn.sourceforge.net/svnroot/scimpi/trunk scimpi_DEV

This creates the directory scimpi_DEV with the following (approximate) contents

cart-demo
expenses-demo
LICENSE.TXT
pom.xml
README.TXT
release
scimpi-dispatcher
scimpi-docs
scimpi-server
scimpi-servlet
webapp-template

Before importing the code into the IDE we need to set up the IDE's project structure. Through Maven run the following commands to set up projects (creates .project, .classpath and other Eclipse property files) and set the repository variable (M2_REPO) within Eclipse.

$ mvn eclipse:eclipse
$ mvn -Declipse.workspace=. eclipse:add-maven-repo

Using the import wizard in Eclipse (File/Import menu) select Existing Projects into Workspace and press the Next button. Within the second tab of the wizard specify the directory as checked out above. Once a list has appeared in the Projects field, as seen below, press the finish button.

Running the Demos

Eclipse's Web Standard Tools (WST) and J2EE Standard Tools (JST) provides tooling for building and running web applications including running a Servlet Container from within Eclipse.

Before running such a web application is necessary to ensure that related projects are added to the server's classpath. This is done via the properties for the web application project under the J2EE Module Dependencies section. In there tick the projects that are needed to run Scimpi, at the time of writing these are scimpi-dispatcher and scimpi-servlet.

To run the examples with Eclipse right-click on the cart-demo project and from the Run As menu select the Run on Server option. The dialog that pops up should be correctly set for the local server. (If there are no servers set up they can be added via the preferences, see the section Server/Installed Runtimes and use the Add button to add a server that you have installed on your machine.) Press Next to move to the second page where you add all the other projects as web applications, or Finish to run the server.

How Scimpi works

The Scimpi framework is used to build Java web applications that run in a servlet container such Tomcat or JRun. Using the Naked Objects framework to access a Java domain model Scimpi can be used to create dynamic web pages that access and manipulate that domain model.

Pages are generated by Scimpi by processing template files (with the extension shtml) that contain special tags that instruct the framework to do particular things (all other files with extensions other than shtml are passed to the browser unchanged). The template files are essentially HTML files interspersed with Scimpi tags that are processed and will typically generate some HTML code to replace the tag in the file that is passed to browser. Like most other web applications the template files, and all other browser requestable resources are placed in the webapp directory.

webapp/
    generic/
        action.shtml
        collection.shtml
        edit.shtml
        object.shtml
    images/
        Default.png
        logo.png
    style/
        screen.css
        template.shtml
    WEB-INF/
        nakedobjects.properties
        passwords
        web.xml
    index.shtml

Loading Naked Objects. When the servlet container loads the Scimpi based web application it starts off by loading up Naked Objects and introspecting the domain model. This is controlled by the nakedobjects.properties file. A basic configuration, like the one shown below, will list the service objects that Naked Objects should make available and the fixtures that should be run the first time the web application is started to populate the object store with the initial set of domain objects.

nakedobjects.services.prefix=org.nakedobject.app.cart.services
nakedobjects.services=ClaimantRepository, ClaimRepository

nakedobjects.fixtures.prefix=org.nakedobject.app.cart.fixtures
nakedobjects.fixtures=ClaimsFixture

Default security. Naked Objects is user orientated, that is it expects the interactions with it to be on behalf of a user. To this end the system must authorise a user before anything can be done, this is the same principle as a database engine. The passwords file contains a set of user names and passwords for Naked Object's most basic authorisation implementation. The example below defines a set of actual users for applications that will be based on Naked Objects users, and a system user (webapp) for applications that either have no concepts of users or provide for it within the domain model.

# username:password
sven:pass
dick:pass
bob:pass

webapp:pass

web application configuration. The web application configuration file for a Scimpi application is rather simple and varies little from application to application. The change that needs to be made only applies to applications that use Naked Objects users, for which the to parameters for the dispatcher servlet should be removed so that web application does not log-in automatically when a session is started.

<?xml version="1.0" encoding="UTF-8"?>
<web-app id="WebApp_ID" version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">
    <display-name>example</display-name>

    <welcome-file-list>
        <welcome-file>index.shtml</welcome-file>
    </welcome-file-list>

    <listener>
        <listener-class>org.nakedobjects.webapp.servlet.SystemInitializer</listener-class>
    </listener>

    <servlet>
        <servlet-name>dispatcher</servlet-name>
        <servlet-class>org.nakedobjects.webapp.servlet.DispatcherServlet</servlet-class>
        <init-param>
            <param-name>username</param-name>
            <param-value>webapp</param-value>
        </init-param>
        <init-param>
            <param-name>password</param-name>
            <param-value>pass</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>dispatcher</servlet-name>
        <url-pattern>*.shtml</url-pattern>
    </servlet-mapping>

    <servlet-mapping>
        <servlet-name>dispatcher</servlet-name>
        <url-pattern>*.app</url-pattern>
    </servlet-mapping>
</web-app>

Controllers. Scimpi provides a single dispatcher servlet and a set of controllers. Other controllers can be added if needed.

The built-in controllers are:-

logon

processes a username and password parameter and requests a Naked Object Session from the underlying framework.

logout

End the Naked Object Session from the underlying framework, and clears the request context.

debug

creates a debug page displaying internal details and state of the Scimpi and Naked Objects frameworks.

edit

process a set of fields from an HTML form for a specified object and sets those fields of that object held by Naked Objects.

action

process a set of fields from an HTML form for a specified method on a domain object or service object and invokes that method.