Hints & Tips Guide

The most significant aspect of the UI is the layout of the object’s members: its properties, collections and actions. These can be organized into columns, rows and tabs.

This can be accomplished using either annotations or through a separate file-based layout. Since this is a large topic, it has its own layout chapter in the Wicket viewer guide.

In Apache Isis every object is identified to the user by a title (label) and an icon. This is shown in several places: as the main heading for an object; as a link text for an object referencing another object, and also in tables representing collections of objects.

The icon is often the same for all instances of a particular class, but it’s also possible for an individual instance to return a custom icon. This could represent the state of that object (eg a shipped order, say, or overdue library book).

It is also possible for an object to provide a CSS class hint. In conjunction with customized CSS this can be used to apply arbitrary styling; for example each object could be rendered in a page with a different background colour.

Apache Isis allows font awesome icons to be associated with each action, and for Bootstrap CSS to be applied to action rendered as buttons. These UI hints can be applied either to individual actions, or can be applied en-masse using pattern matching.

It is also possible to specify additional CSS for an object’s members (not just actions).

The name of classes and class members are usually inferred from the Java source code directly. For example, an action method called placeOrder will be rendered as "Place Order", and a collection called orderItems is rendered as "Order Items".

Occasionally though the desired name is not possible; either the name is a Java reserved word (eg "class"), or might require characters that are not valid, for example abbreviations.

In such cases the name can be specified declaratively.

It is also possible to specify a description declaratively; this is used as a tooltip in the UI.

The table below summarizes the annotations available:

The framework also supports i18n: locale-specific names and descriptions. for more information, see the beyond-the-basics guide.

By default, parented collections all rendered lazily, in other words in a "collapsed" table view.

For the more commonly used collections we want to show the table expanded:

For this we annotate the collection using @CollectionLayout#defaultView(); for example

Alternatively, it can be specified the Xxx.layout.xml file:

It might be thought that collections that are eagerly rendered should also be eagerly loaded from the database by enabling the defaultFetchGroup attribute:

While this can be done, it’s likely to be a bad idea, because doing so will cause DataNucleus to query for more data irrespective of how the object is used/rendered.

Of course, your mileage may vary, so do experiment.

From this thread on the Apache Isis users mailing list:

Yes, you can do this, by installing a custom implementation of the Wicket Bootstrap’s ActiveThemeProvider.

The Isis addons' todoapp (non-ASF) actually does this, storing the info via the (non-ASF) Incode Platform’s settings module :

and

From this thread on the Apache Isis users mailing list:

The above FAQ was raised against 1.10.0. As of 1.11.0 (due to ISIS-1093) it is now possible to internationalize both the Wicket viewer’s labels as well as the regular translations of the domain object metadata using the .po translation files as supported by the TranslationService.

Full details of the msgIds that must be added to the translations.po file can be found in i18n section of the beyond the basics guide.

In prior releases (1.10.0 and earlier) it was necessary to use Wicket’s internationalization support, namely resource bundles. This is still supported (as a fallback):

(As per ISIS-1604), SVG images can be used:

However, SVGs are not, by default, displayed on the welcome page. SVGs can be attached as Blobs, but they are displayed as bitmaps (by means of the Batik rasterizer) and do not scale. The rasterizer (of course) can not deal with animations (cf. attachment).

To fix this, you can add the following dependencies:

However, please note that these dependencies have high CVE values, and so may constitute a security risk.

Further discussion on this mailing list thread.

This screencast shows how to explore the Restful API using Chrome plugins/extensions, and how we use them to write end-2-end (TCK) tests for the Restful Objects viewer.

The hypermedia API exposed by Apache Isis' Restful Objects viewer is intended be support both bespoke custom-written viewers as well as generic viewers. Indeed, we expect most clients consuming the API will be bespoke, not generic.

This page captures one or two tips on using Angular to write such a bespoke client.

The JSON representations generated by the Restful Objects viewer are in compact form if the deployment type is SERVER (ie production), but will automatically be "pretty printed" (in other words indented) if the deployment type is PROTOTYPE.

From this thread on the Apache Isis users mailing list:

The RO viewer returns the image as a string, in the form:

This is in the form:

This is basically the Blob value type, in string form.

To use, split the parts then format the mime type and base64 data correctly before using as source in an <img> tag.

The JDO Objectstore (or rather, the underlying DataNucleus implementation) builds its own persistence metamodel by reading both annotations on the class and also by searching for metadata in XML files. The metadata in the XML files takes precedence over the annotations, and so can be used to override metadata that is "hard-coded" in annotations.

In fact, JDO/DataNucleus provides two different XML files that have slightly different purposes and capabilities:

If you want to use the first approach (the .jdo file), you’ll find that you can download the effective XML representation of domain entities using the downloadJdoMetadata mixin action available in prototyping mode. This then needs to be renamed and placed in the appropriate location on the classpath; see the DataNucleus documentation for details.

However, using this first approach does create a maintenance effort; if the domain entity’s class structure changes over time, then the XML metadata file will need to be updated.

The second approach (using an .orm file) is therefore often more useful than the first, because the metadata provided overrides rather than replaces the annotations (and annotations not overridden continue to be honoured).

A typical use case is to change the database schema for an entity. For example, as of 1.9.0 the various (non-ASF) Incode Platform modules use schemas for each entity. For example, the AuditEntry entity in the (non-ASF) Incode Platform's audit module is annotated as:

This will map the AuditEntry class to a table "IsisAddonsAudit"."AuditEntry"; that is using a custom schema to own the object.

Suppose though that for whatever reason we didn’t want to use a custom schema but would rather use the default. Also suppose we are using SQL Server as our target database.

We can override the above annotation using a AuditEntry-sqlserver.orm file, placed in the same package as the AuditEntry entity. For example:

It’s also necessary to tell JDO/DataNucleus about which vendor is being used (sqlserver in the example above). This is done using a configuration property:

Taken from this thread on the Apache Isis users mailing list…​

If it seems that Apache Isis (or rather DataNucleus) isn’t fully populating domain entities (ie leaving some properties as null), then check that your actions are not accessing the fields directly. Use getters instead.

Why so? Because DataNucleus will potentially lazy load some properties, but to do this it needs to know that the field is being requested. This is the purpose of the enhancement phase: the bytecode of the original getter method is actually wrapped in code that does the lazy loading checking. But hitting the field directly means that the lazy loading code does not run.

This error can be subtle: sometimes "incorrect" code that accesses the fields will seem to work. But that will be because the field has been populated already, for whatever reason.

One case where you will find the issue highlighted is for subtype tables that have been mapped using an inheritance strategy of NEW_TABLE, eg:

and then:

This will generate two tables in the database, with the primary key of the supertype table propagated as a foreign key (also primary key) of the subtype table (sometimes called "table per type" strategy). This means that DataNucleus might retrieve data from only the supertype table, and the lazily load the subtype fields only as required. This is preferable to doing a left outer join from the super- to the subtype tables to retrieve data that might not be needed.

On the other hand, if the SUPERCLASS_TABLE strategy (aka "table per hierarchy" or roll-up) or the SUBCLASS_TABLE strategy (roll-down) was used, then the problem is less likely to occur because DataNucleus would obtain all the data for any given instance from a single table.

Final note: references to other objects (either scalar references or in collections) in particular require that getters rather than fields to be used to obtain them: it’s hopefully obvious that DataNucleus (like all ORMs) should not and will not resolve such references (otherwise, where to stop…​ and the whole database would be loaded into memory).

In summary, there’s just one rule: always use the getters, never the fields.

DataNucleus 4.x supports Java 7, but can also be used with Java 8, eg for streams support against collections managed by DataNucleus.

Just include within <dependencies> of your dom module’s pom.xml:

(As of DN 4.1) set a break point in FetchRequest#execute(…​):

The "Variables" pane will tell you which field(s) are being loaded, and the stack trace should help explain why the field is required.

For example, it may be that an object is being loaded in a table and the initial query did not eagerly load that field. In such a case, consider using fetch groups in the initial repository query to bring the required data into memory with just one SQL call. See this hint/tip for further details.

Fetch groups provide a means to hint to DataNucleus that it should perform a SQL join when querying. A common use case is to avoid the n+1 issue.

(So far as I could ascertain) it isn’t possible to specify fetch group hints using JDOQL, but it is possible to specify them using the programmatic API or using typesafe queries.

For example, here’s a JDOQL query:

which normally would be used from a repository:

This can be re-written as a type-safe query as follows:

Now the IncomingInvoice has four fields that require eager loading. This can be specified by defining a named fetch group:

This fetch group can then be used in the query using q.getFetchPlan().addGroup(…​). Putting this all together, we get:

The bypass security component consists of an implementation of both the AuthenticationManager and AuthorizationManager APIs, and are intended for prototyping use only.

The authentication manager allows access with any credentials (in a sense, "bypassing" authentication), while the authorization manager provides access to all class members (in a sense, "bypassing" authorization).

To tell Apache Isis to bypass security, just update the WEB-INF/isis.properties file:

This installs the appropriate no-op implementations for both authentication and authorization:

This hint shows how to temporarily change the current user as reported by Shiro. This can be useful to support "Run As", for example.

The heavy lifting is done in ShiroService:

This could be exposed in the UI using a simple RunAsService, for example:

Credits: adapted from this gist.

We don’t want to repeat the entire Shiro documentation set here, but we should flag a number of other features that are worth checking out.

Sometimes an action might perform irreversible changes. In such a case it’s probably a good idea for the UI to require that the end-user explicitly confirms that they intended to invoke the action.

The framework provides default implementations for many of the domain services. This is convenient, but sometimes you will want to replace the default implementation with your own service implementation.

For example, suppose you wanted to provide your own implementation of LocaleProvider. The trick is to use the @DomainService#menuOrder() attribute, specifying a low number (typically "1").

Here’s how:

The framework uses the value of the menuOrder attribute to determine priority; lowest number wins.

Thus, if a single instance is to be injected, eg:

then the custom implementation will be used in preference to the framework’s default implementation.

If multiple instances are injected, eg:

then all implementations will be present in the list, ordered by priority; your custom implementation will be first in the list.

(As of 1.15.0 onwards), there is no need to specify the menuOrder attribute: its default value is now set to a lower value (specifically: Integer.MAX_VALUE - 100). Thus, the code simplifies to:

eg if included an addon such as auditing or security.

solution is to write a domain event subscriber that vetoes the visibility

All the addons actions inherit from common base classes so this can be as broad-brush or fine-grained as required

In Apache Isis, every interaction (action invocation or property edit) is automatically wrapped in a transaction, and any repository query automatically does a flush before hand.

What that means is that there’s no need to explicitly start or commit transactions in Apache Isis; this will be done for you. Indeed, if you do try to manage transactions (eg by reaching into the JDO PersistenceManager exposed by the IsisJdoSupport domain service, then you are likely to confuse the framework and get a stack trace for your trouble.

However, you can complete a given transaction and start a new one. This is sometimes useful if writing a fixture script which is going to perform some sort of bulk migration of data from an old system. For this use case, use the TransactionService.

For example:

You get the idea.

Normally the title of an object is not persisted to the database, rather it is recomputed automatically from underlying properties. On occasion though you might want the title to also be persisted; either to make things easier for the DBA, or for an integration scenario, or some other purpose.

We can implement this feature by leveraging the JDO lifecycle. In the design we discuss here we make it a responsibility of the entities to persist the title as a property, by implementing a ObjectWithPersistedTitle interface:

We can then define a subscribing domain service that leverage this.

Prior to 1.10.0 (when lifecycle events were introduced), this could also be be done by accessing the JDO API directly:

The above is probably the easiest and most straightforward design. One could imagine other designs where the persisted title is stored elsewhere. It could even be stored off into an Apache Lucene (or similar) database to allow for free-text searches.

Vith view models, some care must be taken in how they are instantiated. Specifically, it’s important that the framework doesn’t "know" about the view model until its state is "sufficiently" populated to distinguish from other view models.

In practical terms, this means that view models should be instantiated using a constructor, and then injecting services (if required) using the ServiceRegistry service:

What will most likely fail is to use the FactoryService:

That’s because the internal "OID" identifier that the framework creates to handle this view model will be incomplete. Although the framework can handle changes to the OID (when the corresponding view model’s state changes) once created, this isn’t the case during initial instantiation process.

Although in Apache Isis you can have properties of either values (string, number, date etc) or of (references to other) entities, with collections the framework (currently) only supports collections of (references to) entities. That is, collections of values (a bag of numbers, say) are not supported.

However, it is possible to simulate a bag of numbers using view models.

From this thread on the Apache Isis users mailing list:

One way to implement this idea is to provide a custom implementation of the RoutingService SPI domain service. The default implementation will either return the current object (if not null), else the home page (as defined by @HomePage) if one exists.

The following custom implementation refines this to use the breadcrumbs (available in the Wicket viewer) to return the first non-deleted domain object found in the list of breadcrumbs:

Note that the above implementation uses Java 8, so if you are using Java 7 then you’ll need to backport accordingly.

Of the various modules provided by the (non-ASF) Incode Platform, the security module has the most features. One significant feature is the ability to associate users and objects with a "tenancy".

For more details, see the Incode Platform's security module README.

Suppose you have a hierarchy of classes where a property is derived and abstract in the superclass, concrete implementations in the subclasses. For example:

Currently the Wicket viewer will not render the property in tables (though the property is correctly rendered in views).

The work-around is simple enough; make the method concrete in the superclass and return a dummy implementation, eg:

Alternatively the implementation could throw a RuntimeException, eg

From this thread on the Apache Isis users mailing list:

One way to implement is to use the event bus:

if if the change is made through an edit, you can use @Property#domainEvent().

You’ll need some way to know which fields should be spell checked. Two ways spring to mind:

And you’ll (obviously) also need some sort of spell checker implementation to call.

DataNucleus is the reference implementation of the JDO (Java data objects) spec, and Apache Isis integrates with DataNucleus as its persistence layer. Datanucleus is a very powerful library, allowing domain entities to be mapped not only to relational database tables, but also to NoSQL stores such as Neo4J, MongoDB and Apache Cassandra.

With such power comes a little bit of complexity to the development environment: all domain entities must be enhanced through the DataNucleus enhancer.

What this means is that the enhancer — available as both a Maven plugin and as an Eclipse plugin — must, one way or another, be integrated into your development environment.

If working from the Maven command line, JDO enhancement is done using the maven-datanucleus-plugin.

Both the HelloWorld and SimpleApp Maven archetypes generate applications that have this plugin pre-configured.

Sometimes you just need to see what is going on. There are various ways in which logging can be enabled, here are the ones we tend to use.

Database logging can be configured:

From the Apache Isis mailing list is:

Yes, you can; here’s one way:

Or, you could just write a small shell script and run from the command line:

From this thread on the Apache Isis users mailing list:

The standard approach is to use fixture scripts. These can be run in on start-up typically by being specified in the AppManifest, see for example the SimpleApp archetype.

Alternatively just set isis.fixtures and isis.persistor.datanucleus.install-fixtures properties.

In terms of implementations, you might also want to check out the (non-ASF) Incode Platform's excel module, by using ExcelFixture and overriding ExcelFixtureRowHandler.

An example can be found in this (non ASF) contactapp, see ContactRowHandler.