GridService

Provides the ability to load the XML layout (grid) for a domain class.

API

GridService.java
interface GridService {
  boolean supportsReloading()     (1)
  void remove(Class<?> domainClass)     (2)
  boolean existsFor(Class<?> domainClass)     (3)
  Grid load(Class<?> domainClass)     (4)
  Grid load(Class<?> domainClass, String layout)     (5)
  Grid defaultGridFor(Class<?> domainClass)     (6)
  Grid normalize(Grid grid)     (7)
  Grid complete(Grid grid)     (8)
  Grid minimal(Grid grid)     (9)
  GridMarshallerService<? extends Grid> marshaller()
  Grid toGridForExport(Class<?> domainClass, LayoutExportStyle style)
}
1 supportsReloading()

Whether dynamic reloading of layouts is enabled.
2 remove(Class)

To support metamodel invalidation/rebuilding of spec.
3 existsFor(Class)

Whether any persisted layout metadata (eg a .layout.xml file) exists for this domain class.
4 load(Class)

Returns a new instance of a Grid for the specified domain class, for example as loaded from a layout.xml file.
5 load(Class, String)

Returns an alternative layout for the domain class.
6 defaultGridFor(Class)

Returns a default grid; eg where none can be loaded using #load(Class) .
7 normalize(Grid)

Returns a normalized grid for the domain class obtained previously using #load(Class) .
8 complete(Grid)

Modifies the provided Grid with additional metadata, broadly speaking corresponding to the DomainObjectLayout , ActionLayout , PropertyLayout and CollectionLayout .
9 minimal(Grid)

Modifies the provided Grid , removing all metadata except the basic grid structure.

Members

supportsReloading()

Whether dynamic reloading of layouts is enabled.

The default implementation just delegates to the configured GridLoaderService ; the default implementation of that service enables reloading wihle prototyping, disables in production.

remove(Class)

To support metamodel invalidation/rebuilding of spec.

The default implementation just delegates to the configured GridLoaderService .

existsFor(Class)

Whether any persisted layout metadata (eg a .layout.xml file) exists for this domain class.

The default implementation just delegates to the configured GridLoaderService .

load(Class)

Returns a new instance of a Grid for the specified domain class, for example as loaded from a layout.xml file.

If non exists, returns null . (The caller can then use GridService#defaultGridFor(Class) to obtain a default grid if necessary).

The default implementation just delegates to the configured GridLoaderService .

load(Class, String)

Returns an alternative layout for the domain class.

The alternative layout name can for example be returned by the domain object’s layout() method, whereby - based on the state of the domain object - it requests a different layout be used.

The default implementation just delegates to the configured GridLoaderService ; the default implementation of that service uses the layout name to search for a differently named layout file, [domainClass].layout.[layout].xml .

defaultGridFor(Class)

Returns a default grid; eg where none can be loaded using #load(Class) .

Used when no existing grid layout exists for a domain class.

The default implementation searches through all available GridSystemService s and asks each in turn for a GridSystemService#defaultGrid(Class) default grid .

normalize(Grid)

Returns a normalized grid for the domain class obtained previously using #load(Class) .

If a 'normalized' grid is persisted as the layout.xml , then the expectation is that any ordering metadata from layout annotations can be removed from the domain class because the binding of properties/collections/actions will be within the XML. However, the layout annotations ( DomainObjectLayout , ActionLayout , PropertyLayout and CollectionLayout ) (if present) will continue to be used to provide additional layout metadata. Of course, there is nothing to prevent the developer from extending the layout XML to also include the layout XML (in other words moving towards a #complete(Grid) complete grid. Metadata within the layout.xml file takes precedence over any annotations.

complete(Grid)

Modifies the provided Grid with additional metadata, broadly speaking corresponding to the DomainObjectLayout , ActionLayout , PropertyLayout and CollectionLayout .

If a 'complete' grid is persisted as the layout.xml , then there should be no need for any of the layout annotations, to be required in the domain class itself.

minimal(Grid)

Modifies the provided Grid , removing all metadata except the basic grid structure.

If a 'minimal' grid is persisted as the layout.xml , then the expectation is that most of the layout annotations ( DomainObjectLayout , ActionLayout , PropertyLayout , CollectionLayout will still be retained in the domain class code.

Implementation

The framework provides a default implementation of this service, namely o.a.c.core.metamodel.services.grid.GridServiceDefault.

Caching

Once a grid has been loaded for a domain class, this is cached internally by Apache Causeway' internal meta model (in the GridFacet facet).

If running in prototype mode, any subsequent changes to the XML will be detected and the grid rebuilt. This allows for dynamic reloading of layouts, providing a far faster feedback (eg if tweaking the UI while working with end-users). Dynamic reloading is disabled in production mode.

See also

This service is called by LayoutService, exposed in the UI through LayoutServiceMenu (to download the layout XML as a zip file for all domain objects) and the downloadLayout() mixin (to download the layout XML for a single domain object).

This service delegates to:

  • to GridLoaderService to load a pre-existing layout for the domain class, if possible

  • to GridSystemService to normalize the grid with respect to Apache Causeway' internal metamodel, in other words to ensure that all of the domain objects' properties, collections and actions are associated with regions of the grid.