Quickstart Archetype

The quickest way to get started with Apache Isis is to run the quickstart archetype. This will generate a simple one-class domain model, for tracking to-do items. The intention is not to showcase all of Isis' capabilities; rather it is to allow you to very easily modify the generated app to your own domain.

Generating the App

Create a new directory, and cd into that directory.

Then run the following command:

mvn archetype:generate  \
    -D archetypeGroupId=org.apache.isis.archetype \
    -D archetypeArtifactId=quickstart_wicket_restful_jdo-archetype \
    -D archetypeVersion=1.0.2 \
    -D groupId=com.mycompany \
    -D artifactId=myapp

where:

• groupId represents your own organization, and
• artifactId is a unique identifier for this app within your organization.

You'll then be prompted for some further properties; you can generally leave these as the default:

• enter a version, eg 1.0-SNAPSHOT
• enter a package
• confirm the entry

The archetype generation process will then run; it only takes a few seconds.

Building the App

Switch into the root directory of your newly generated app, and build your app:

cd myapp
mvn clean install

where myapp is the artifactId entered above.

Running the App

The quickstart_wicket_restful_jdo archetype generates a single WAR file, configured to run both the Wicket viewer and the Restful Objects viewer. The archetype also configures the JDO Objectstore to use an in-memory HSQLDB connection.

Once you've built the app, you can run the WAR in a variety of ways.

The recommended approach when getting started is to run the self-hosting version of the WAR, allowing Isis to run as a standalone app; for example:

java -jar viewer-webapp/target/myapp-viewer-webapp-1.0-SNAPSHOT-jetty-console.war

This can also be accomplished using an embedded Ant target provided in the build script:

mvn antrun:run

The first is to simply deploying the generated WAR (webapp/target/myapp-webapp-1.0-SNAPSHOT.war) to a servlet container.

Alternatively, you could run the WAR in a Maven-hosted Jetty instance, using:

mvn jetty:run

If you do this, note that the context path changes; check the console output.

Finally, you can also run the app by deploying to a standalone servlet container such as Tomcat.

Using the App

The archetype provides a welcome page that explains the classes and files generated, and provides detailed guidance and what to do next.

The app itself is configured to run using shiro security, as configured in the WEB-INF/shiro.ini config file. To log in, use sven/pass.

App Structure

As noted above, the generated app is a very simple application consisting of a single domain object for tracking to-do items. The intention is not to showcase all of Isis' capabilities; rather it is to allow you to very easily modify the generated application (eg rename ToDoItem to Customer) without having to waste time deleting lots of generated code.

If you run into issues, please don't hesitate to ask for help on the users mailing list.