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.
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.3 \ -D groupId=com.mycompany \ -D artifactId=myapp
groupIdrepresents your own organization, and
artifactIdis 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:
The archetype generation process will then run; it only takes a few seconds.
Switch into the root directory of your newly generated app, and build your app:
cd myapp mvn clean install
myapp is the
artifactId entered above.
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:
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:
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.
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
Once you are familiar with the generated app, you'll want to start modifying it. There is plenty of guidance on this site (check out the getting started section first).
If you use Eclipse, do also install the Eclipse templates; these will help you follow the Isis naming conventions.
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
Customer) without having to waste time deleting lots of generated code.
|myapp||The parent (aggregator) module|
|myapp-dom||The domain object model, consisting of ToDoItem and ToDoItems (repository) interface.|
|myapp-fixture||Domain object fixtures used for initializing the system when being demo'ed or for unit testing.|
|myapp-integtests||End-to-end integration tests, that exercise from the UI through to the database|
|myapp-objstore-jdo||Implementation of ToDoItems repository, using JDO objectstore.|
|myapp-webapp||Run as a webapp (from web.xml) using either the Wicket viewer or the RestfulObjects viewer|
If you run into issues, please don't hesitate to ask for help on the users mailing list.
All edits are reviewed before going live, so feel free to do much more than fix typos or links. If you see a page that could benefit from an entire rewrite, we'd be thrilled to review it. Don't be surprised if we like it so much we ask you for help with other pages :)NOTICE: unless indicated otherwise on the pages in question, all editable content available from apache.org is presumed to be licensed under the Apache License (AL) version 2.0 and hence all submissions to apache.org treated as formal Contributions under the license terms.