= GridService
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

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

== API

[source,java]
.GridService.java
----
interface GridService {
  boolean supportsReloading()     // <.>
  void remove(Class<?> domainClass)     // <.>
  boolean existsFor(Class<?> domainClass)     // <.>
  Grid load(Class<?> domainClass)     // <.>
  Grid load(Class<?> domainClass, String layout)     // <.>
  Grid defaultGridFor(Class<?> domainClass)     // <.>
  Grid normalize(Grid grid)     // <.>
  Grid complete(Grid grid)     // <.>
  Grid minimal(Grid grid)     // <.>
  GridMarshallerService<? extends Grid> marshaller()
  Grid toGridForExport(Class<?> domainClass, LayoutExportStyle style)
}
----

<.> xref:#supportsReloading_[supportsReloading()]
+
--
Whether dynamic reloading of layouts is enabled.
--
<.> xref:#remove_Class[remove(Class)]
+
--
To support metamodel invalidation/rebuilding of spec.
--
<.> xref:#existsFor_Class[existsFor(Class)]
+
--
Whether any persisted layout metadata (eg a `.layout.xml` file) exists for this domain class.
--
<.> xref:#load_Class[load(Class)]
+
--
Returns a new instance of a xref:refguide:applib:index/layout/grid/Grid.adoc[Grid] for the specified domain class, for example as loaded from a `layout.xml` file.
--
<.> xref:#load_Class_String[load(Class, String)]
+
--
Returns an alternative layout for the domain class.
--
<.> xref:#defaultGridFor_Class[defaultGridFor(Class)]
+
--
Returns a default grid; eg where none can be loaded using _#load(Class)_ .
--
<.> xref:#normalize_Grid[normalize(Grid)]
+
--
Returns a normalized grid for the domain class obtained previously using _#load(Class)_ .
--
<.> xref:#complete_Grid[complete(Grid)]
+
--
Modifies the provided xref:refguide:applib:index/layout/grid/Grid.adoc[Grid] with additional metadata, broadly speaking corresponding to the xref:refguide:applib:index/annotation/DomainObjectLayout.adoc[DomainObjectLayout] , xref:refguide:applib:index/annotation/ActionLayout.adoc[ActionLayout] , xref:refguide:applib:index/annotation/PropertyLayout.adoc[PropertyLayout] and xref:refguide:applib:index/annotation/CollectionLayout.adoc[CollectionLayout] .
--
<.> xref:#minimal_Grid[minimal(Grid)]
+
--
Modifies the provided xref:refguide:applib:index/layout/grid/Grid.adoc[Grid] , removing all metadata except the basic grid structure.
--

== Members

[#supportsReloading_]
=== supportsReloading()

Whether dynamic reloading of layouts is enabled.

The default implementation just delegates to the configured xref:refguide:applib:index/services/grid/GridLoaderService.adoc[GridLoaderService] ; the default implementation of _that_ service enables reloading wihle prototyping, disables in production.

[#remove_Class]
=== remove(Class)

To support metamodel invalidation/rebuilding of spec.

The default implementation just delegates to the configured xref:refguide:applib:index/services/grid/GridLoaderService.adoc[GridLoaderService] .

[#existsFor_Class]
=== 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 xref:refguide:applib:index/services/grid/GridLoaderService.adoc[GridLoaderService] .

[#load_Class]
=== load(Class)

Returns a new instance of a xref:refguide:applib:index/layout/grid/Grid.adoc[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 xref:refguide:applib:index/services/grid/GridLoaderService.adoc[GridLoaderService] .

[#load_Class_String]
=== 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 xref:refguide:applib:index/services/grid/GridLoaderService.adoc[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]
=== 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 xref:refguide:applib:index/services/grid/GridSystemService.adoc[GridSystemService] s and asks each in turn for a _GridSystemService#defaultGrid(Class) default grid_ .

[#normalize_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 ( xref:refguide:applib:index/annotation/DomainObjectLayout.adoc[DomainObjectLayout] , xref:refguide:applib:index/annotation/ActionLayout.adoc[ActionLayout] , xref:refguide:applib:index/annotation/PropertyLayout.adoc[PropertyLayout] and xref:refguide:applib:index/annotation/CollectionLayout.adoc[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]
=== complete(Grid)

Modifies the provided xref:refguide:applib:index/layout/grid/Grid.adoc[Grid] with additional metadata, broadly speaking corresponding to the xref:refguide:applib:index/annotation/DomainObjectLayout.adoc[DomainObjectLayout] , xref:refguide:applib:index/annotation/ActionLayout.adoc[ActionLayout] , xref:refguide:applib:index/annotation/PropertyLayout.adoc[PropertyLayout] and xref:refguide:applib:index/annotation/CollectionLayout.adoc[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]
=== minimal(Grid)

Modifies the provided xref:refguide:applib:index/layout/grid/Grid.adoc[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 ( xref:refguide:applib:index/annotation/DomainObjectLayout.adoc[DomainObjectLayout] , xref:refguide:applib:index/annotation/ActionLayout.adoc[ActionLayout] , xref:refguide:applib:index/annotation/PropertyLayout.adoc[PropertyLayout] , xref:refguide:applib:index/annotation/CollectionLayout.adoc[CollectionLayout] will still be retained in the domain class code.

include::hooks/GridService_010-implementation.adoc[]

include::hooks/GridService_020-examples-and-usage.adoc[]
