Apache Isis Plugin for JAX-RS (Resteasy v3)

JAX-RS plugin using jboss resteasy.

License

License

Categories

Categories

RESTEasy Program Interface REST Frameworks
GroupId

GroupId

org.apache.isis.core
ArtifactId

ArtifactId

isis-core-plugins-jaxrs-resteasy-3
Last Version

Last Version

2.0.0-M2
Release Date

Release Date

Type

Type

jar
Description

Description

Apache Isis Plugin for JAX-RS (Resteasy v3)
JAX-RS plugin using jboss resteasy.
Project Organization

Project Organization

The Apache Software Foundation

Download isis-core-plugins-jaxrs-resteasy-3

How to add to project

<!-- https://jarcasting.com/artifacts/org.apache.isis.core/isis-core-plugins-jaxrs-resteasy-3/ -->
<dependency>
    <groupId>org.apache.isis.core</groupId>
    <artifactId>isis-core-plugins-jaxrs-resteasy-3</artifactId>
    <version>2.0.0-M2</version>
</dependency>
// https://jarcasting.com/artifacts/org.apache.isis.core/isis-core-plugins-jaxrs-resteasy-3/
implementation 'org.apache.isis.core:isis-core-plugins-jaxrs-resteasy-3:2.0.0-M2'
// https://jarcasting.com/artifacts/org.apache.isis.core/isis-core-plugins-jaxrs-resteasy-3/
implementation ("org.apache.isis.core:isis-core-plugins-jaxrs-resteasy-3:2.0.0-M2")
'org.apache.isis.core:isis-core-plugins-jaxrs-resteasy-3:jar:2.0.0-M2'
<dependency org="org.apache.isis.core" name="isis-core-plugins-jaxrs-resteasy-3" rev="2.0.0-M2">
  <artifact name="isis-core-plugins-jaxrs-resteasy-3" type="jar" />
</dependency>
@Grapes(
@Grab(group='org.apache.isis.core', module='isis-core-plugins-jaxrs-resteasy-3', version='2.0.0-M2')
)
libraryDependencies += "org.apache.isis.core" % "isis-core-plugins-jaxrs-resteasy-3" % "2.0.0-M2"
[org.apache.isis.core/isis-core-plugins-jaxrs-resteasy-3 "2.0.0-M2"]

Dependencies

compile (11)

Group / Artifact Type Version
org.apache.isis.core : isis-core-viewer-restfulobjects-rendering jar 2.0.0-M2
org.apache.isis.core : isis-core-viewer-restfulobjects-server jar 2.0.0-M2
org.jboss.resteasy : resteasy-jaxb-provider jar 3.1.4.Final
org.jboss.resteasy : resteasy-jackson-provider jar 3.1.4.Final
org.jboss.resteasy : resteasy-jaxrs jar 3.1.4.Final
commons-logging : commons-logging jar 1.2
com.fasterxml.jackson.core : jackson-core jar 2.8.0
com.fasterxml.jackson.core : jackson-databind jar 2.8.0
com.fasterxml.jackson.core : jackson-annotations jar 2.8.0
com.fasterxml.jackson.module : jackson-module-jaxb-annotations jar 2.8.0
org.slf4j : slf4j-api jar 1.7.21

test (9)

Group / Artifact Type Version
org.apache.isis.core : isis-core-viewer-restfulobjects-applib test-jar 2.0.0-M2
org.apache.isis.core : isis-core-unittestsupport jar 2.0.0-M2
org.apache.isis.core : isis-core-viewer-restfulobjects-server test-jar 2.0.0-M2
javax.jdo : jdo-api jar 3.1
org.jmock : jmock-junit4 jar 2.6.0
org.hamcrest : hamcrest-library jar 1.3
org.junit.jupiter : junit-jupiter-api jar 5.3.1
org.junit.jupiter : junit-jupiter-engine jar 5.3.1
org.junit.vintage : junit-vintage-engine jar 5.3.1

Project Modules

There are no modules declared in this project.

Apache Isis

badge badge badge measure?project=apache isis&metric=alert status badge

Apache Isis software is a framework for rapidly developing domain-driven apps in Java. Write your business logic in entities, domain services and repositories, and the framework dynamically generates a representation of that domain model as a webapp or a RESTful API.

Start learning about Apache Isis using the "Hello World" starter app. Explore features with our daily built demo docker image "DemoApp". Build your own apps using our "SimpleApp" starter app.

For help and support, join our Slack channel or mailing list.

Core Features

Apache Isis automatically generates the UI from the domain classes.

Sign-in

Apache Isis integrates with Apache Shiro. The core framework supports file-based realms, while the SecMan extension provides a well-features subdomain of users, roles and permissions against features derived from the Apache Isis metamodel.

010 login

Install Fixtures

Apache Isis has lots of features to help you prototype and then fully test your application. One such are fixture scripts, which allow pre-canned data to be installed in the running application. This is great to act as the starting point for identifying new stories; later on when the feature is being implemented, the same fixture script can be re-used within that feature’s integration tests. (More on tests later).

020 install fixtures

Dashboard and View Models

Most of the time the end-user interacts with representations of persistent domain entities, but Isis also supports view models which can aggregate data from multiple sources. The todoapp example uses a "dashboard" view model to list todo items not yet done vs those completed.

030 dashboard view model

In general we recommend to initially focus only on domain entities; this will help drive out a good domain model. Later on view models can be introduced in support of specific use cases.

Domain Entity

The screenshot below is of the todoapp’s ToDoItem domain entity. Like all web pages, this UI is generated at runtime, directly from the domain object itself. There are no controllers or HTML to write.

040 domain entity

In addition to the domain entity, Apache Isis allows layout metadata hints to be provided, for example to specify the grouping of properties, the positioning of those groups into columns, the association of actions (the buttons) with properties or collections, the icons on the buttons, and so on. This metadata can be specified either as annotations or in JSON form; the benefit of the latter is that it can be updated (and the UI redrawn) without restarting the app.

Any production-ready app will require this metadata but (like the view models discussed above) this metadata can be added gradually on top of the core domain model.

Edit properties

By default properties on domain entities are editable, meaning they can be changed directly. In the todoapp example, the `ToDoItem’s description is one such editable property:

050 edit property

Note that some of the properties are read-only even in edit mode; individual properties can be made non-editable. It is also possible to make all properties disabled and thus enforce changes only through actions (below).

Actions

The other way to modify an entity is to an invoke an action. In the screenshot below the `ToDoItem’s category and subcategory can be updated together using an action:

060 invoke action

There are no limitations on what an action can do; it might just update a single object, it could update multiple objects. Or, it might not update any objects at all, but could instead perform some other activity, such as sending out email or printing a document.

In general though, all actions are associated with some object, and are (at least initially) also implemented by that object: good old-fashioned encapsulation. We sometimes use the term "behaviourally complete" for such domain objects.

Mixins

As an alternative to placing actions (business logic) on a domain object, it can instead be placed inside a mixin object. When an object is rendered by Apache Isis, the mixin "contributes" its behaviour to the domain object (similar to aspect-oriented traits).

In the screenshot below the highlighted "export as xml" action, the "relative priority" property (and "previous" and "next" actions) the "similar to" collection and the two "as DTO" actions are all contributed by mixins:

065 contributions

The code snippet below shows how this works for the "as DTO v1.0" action:

067 contributed action

Extensible Views

The Apache Isis viewer is implemented using Apache Wicket, and has been architected to be extensible. For example, when a collection of objects is rendered, this is just one several views, as shown in the selector drop-down:

070 pluggable views

The (non-ASF) gmap3 component will render any domain entity (such as ToDoItem) that implements its Locatable interface:

080 gmap3 view

Similarly the (non-ASF) fullcalendar2 component will render any domain entity (such as ToDoItem) that implements its Calendarable interface:

090 fullcalendar2 view

Yet another "view" (though this one is rather simpler) is that provided by the (non-ASF) excel component. This provides a download button to the table as a spreadsheet:

100 excel view and docx

The screenshot above also shows an "export to Word" action. This is not a view but instead is a (contributed) action that uses the (non-ASF) docx library module to perform a "mail-merge":

110 docx

Security, Auditing and other Services

As well as providing extensions to the UI, the framework has a rich set of extensions to support various cross-cutting concerns.

Under the activity menu are four sets of services which provide support for user session logging/auditing, command profiling, (object change) auditing (shown) and (inter-system) event publishing:

120 auditing

In the security menu is access to the rich set of functionality provided by the SecMan extension:

130 security

In the prototyping menu is the ability to download a GNU gettext .po file for translation. This file can then be translated into multiple languages so that your app can support different locales. Note that this feature is part of Apache Isis core:

140 i18n

The framework also provides an extension module for managing application and user settings. Most apps (the todoapp example included) won’t expose these services directly, but will usually wrap them in their own app-specific settings service that trivially delegates to the settings module’s services:

150 appsettings

Multi-tenancy support

Of the various modules in the Incode Platform, the security module has the most features.

Note
this module has now been integrated into the Apache Isis framework itself, as the SecMan extension.

One significant feature of the is the ability to associate users and objects with a "tenancy". The todoapp uses this feature so that different users' list of todo items are kept separate from one another. A user with administrator is able to switch their own "tenancy" to the tenancy of some other user, in order to access the objects in that tenancy:

160 switch tenancy

For more details, see the security module’s README (or SecMan extension)..

Me

Most of the security module’s domain services are on the "security" menu, which would normally be accessible only to administrators. Kept separate is the "me" action:

170 me

Assuming they have been granted permissions, this allows a user to access an entity representing their own user account:

180 app user entity

If not all of these properties are required, then they can be hidden either using security or though Isis' internal event bus (described below). Conversely, additional properties can be "grafted onto" the user using the contributed properties/collections discussed previously.

Themes

Apache Isis' Wicket viewer uses Twitter Bootstrap, which means that it can be themed. If more than one theme has been configured for the app, then the viewer allows the end-user to switch their theme:

190 switch theme

REST API

In addition to Isis' Wicket viewer, it also provides a fully fledged REST API, as an implementation of the Restful Objects specification. The screenshot below shows accessing this REST API using a Chrome plugin:

200 rest api

Like the Wicket viewer, the REST API is generated automatically from the domain objects (entities and view models).

Integration Testing Support

Earlier on we noted that Apache Isis allows fixtures to be installed through the UI. These same fixture scripts can be reused within integration tests. For example, the code snippet below shows how the FixtureScripts service injected into an integration test can then be used to set up data:

210 fixture scripts

The tests themselves are run in junit. While these are integration tests (so talking to a real database), they are no more complex than a regular unit test:

220 testing happy case

To simulate the business rules enforced by Apache Isis, the domain object can be "wrapped" in a proxy. For example, if using the Wicket viewer then Apache Isis will enforce the rule (implemented in the ToDoItem class itself) that a completed item cannot have the "completed" action invoked upon it. The wrapper simulates this by throwing an appropriate exception:

230 testing wrapper factory

Internal Event Bus

Contributions, discussed earlier, are an important tool in ensuring that the packages within your Apache Isis application are decoupled; by extracting out actions the order of dependency between packages can effectively be reversed.

Another important tool to ensure your codebase remains maintainable is Isis' internal event bus. It is probably best explained by example; the code below says that the "complete" action should emit a ToDoItem.Completed event:

240 domain events

Domain service (application-scoped, stateless) can then subscribe to this event:

250 domain event subscriber

And this test verifies that completing an action causes the subscriber to be called:

260 domain event test

In fact, the domain event is fired not once, but (up to) 5 times. It is called 3 times prior to execution, to check that the action is visible, enabled and that arguments are valid. It is then additionally called prior to execution, and also called after execution. What this means is that a subscriber can in either veto access to an action of some publishing object, and/or it can perform cascading updates if the action is allowed to proceed.

Moreover, domain events are fired for all properties and collections, not just actions. Thus, subscribers can therefore switch on or switch off different parts of an application. Indeed, the example todoapp demonstrates this.

Learning More

The Apache Isis website has lots of useful information and is being continually updated.

Or, you can just start coding using the https:github.com/apache/isis-app-simpleapp[SimpleApp] starter app.

And if you need help or support, join our ASF Slack channel or our mailing list.

org.apache.isis.core

The Apache Software Foundation

Versions

Version
2.0.0-M2
2.0.0-M1